Criar assinatura

POST

subscriptions

Create a Subscription

curl --request POST \
  --url https://api.pagou.ai/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "amount": 50000000,
  "token": "<string>",
  "interval_count": 1,
  "failure_policy": "retry_then_cancel",
  "retry_offsets_days": [
    15
  ],
  "currency": "BRL",
  "metadata": {},
  "informations": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "idempotency_key": "<string>",
  "products": [
    {
      "name": "<string>",
      "price": 50000000,
      "quantity": 1,
      "tangible": false,
      "sku": "<string>"
    }
  ],
  "payment_method": "credit_card",
  "trial_end": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.pagou.ai/v2/subscriptions"

payload = {
    "customer_id": "<string>",
    "amount": 50000000,
    "token": "<string>",
    "interval_count": 1,
    "failure_policy": "retry_then_cancel",
    "retry_offsets_days": [15],
    "currency": "BRL",
    "metadata": {},
    "informations": [
        {
            "key": "<string>",
            "value": "<string>"
        }
    ],
    "idempotency_key": "<string>",
    "products": [
        {
            "name": "<string>",
            "price": 50000000,
            "quantity": 1,
            "tangible": False,
            "sku": "<string>"
        }
    ],
    "payment_method": "credit_card",
    "trial_end": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '<string>',
    amount: 50000000,
    token: '<string>',
    interval_count: 1,
    failure_policy: 'retry_then_cancel',
    retry_offsets_days: [15],
    currency: 'BRL',
    metadata: {},
    informations: [{key: '<string>', value: '<string>'}],
    idempotency_key: '<string>',
    products: [
      {
        name: '<string>',
        price: 50000000,
        quantity: 1,
        tangible: false,
        sku: '<string>'
      }
    ],
    payment_method: 'credit_card',
    trial_end: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.pagou.ai/v2/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pagou.ai/v2/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => '<string>',
    'amount' => 50000000,
    'token' => '<string>',
    'interval_count' => 1,
    'failure_policy' => 'retry_then_cancel',
    'retry_offsets_days' => [
        15
    ],
    'currency' => 'BRL',
    'metadata' => [
        
    ],
    'informations' => [
        [
                'key' => '<string>',
                'value' => '<string>'
        ]
    ],
    'idempotency_key' => '<string>',
    'products' => [
        [
                'name' => '<string>',
                'price' => 50000000,
                'quantity' => 1,
                'tangible' => false,
                'sku' => '<string>'
        ]
    ],
    'payment_method' => 'credit_card',
    'trial_end' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pagou.ai/v2/subscriptions"

	payload := strings.NewReader("{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pagou.ai/v2/subscriptions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "string",
    "customerId": "string",
    "status": "incomplete",
    "paymentMethod": "credit_card",
    "billingModel": "merchant_initiated",
    "billingDayOfMonth": 1,
    "interval": "day",
    "intervalCount": 1,
    "amount": 0,
    "currency": "BRL",
    "trialEnd": "2026-07-14T12:00:00.000Z",
    "currentPeriodStart": "2026-07-14T12:00:00.000Z",
    "currentPeriodEnd": "2026-07-14T12:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": "2026-07-14T12:00:00.000Z",
    "failurePolicy": "immediate_cancel",
    "retryOffsetsDays": [
      1
    ],
    "cancellationReason": "user_requested",
    "customerEmail": "string",
    "cardLast4": "string",
    "metadata": {},
    "informations": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "products": [
      {
        "name": "string",
        "price": 0,
        "quantity": 1,
        "tangible": false
      }
    ],
    "recurringAuthorization": {
      "status": "pending"
    },
    "createdAt": "2026-07-14T12:00:00.000Z",
    "updatedAt": "2026-07-14T12:00:00.000Z"
  }
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Pré-requisitos

Crie o cliente com POST /v2/customers — a resposta inclui o customer_id (UUID) que você passa abaixo.
Numa assinatura com cartão, tokenize o cartão pelo fluxo seguro do Payment Element — isso retorna um token de pagamento pgct_ de uso único. Uma assinatura com Pix Automático não usa token.

Assinaturas não criam clientes automaticamente a partir do corpo da requisição; um customer_id desconhecido retorna 404.

Comportamento

customer_id é o identificador público (UUID) do cliente retornado por POST /v2/customers. Numa assinatura com cartão, token precisa ser um token pgct_ de uso único. Numa assinatura com cartão, quando trial_end é informado, podemos cobrar um valor pequeno e estorná-lo para validar o meio de pagamento, e a assinatura é criada com status trialing até o teste expirar. Sem trial_end, a assinatura é criada com status active após o primeiro charge bem-sucedido. Com payment_method: "pix_automatic", não envie token. A assinatura é criada com status incomplete e um QR code em authorization para o pagador. Ela passa para active quando o pagador autoriza e o primeiro débito é pago, ou para trialing quando há trial_end e a autorização é aprovada. Veja Assinaturas com Pix Automático. amount está em centavos e é usado também para cobrar cada ciclo de renovação.

Autorizações

Authorization

string

header

obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

application/json

Option 1
Option 2

customer_id

string

obrigatório

Public customer id (UUID) returned by POST /v2/customers.

Minimum string length: 1

interval

enum<string>

obrigatório

Opções disponíveis:

day,

week,

month

amount

integer

obrigatório

Billing amount in cents (max 100,000,000).

Intervalo obrigatório: 0 < x <= 100000000

token

string

obrigatório

Minimum string length: 6

interval_count

integer

padrão:1

Intervalo obrigatório: 1 <= x <= 365

failure_policy

enum<string>

padrão:retry_then_cancel

Opções disponíveis:

immediate_cancel,

retry_then_cancel

retry_offsets_days

integer[]

Required array length: 1 - 10 elements

Intervalo obrigatório: 1 <= x <= 30

currency

enum<string>

padrão:BRL

Opções disponíveis:

BRL,

MXN,

COP,

CLP,

ARS,

PEN,

USD,

GTQ,

CRC,

NIO,

PYG,

UYU,

BOB,

PHP,

RUB,

INR,

SAR,

AED,

KWD,

QAR,

OMR,

KHR,

SGD,

IDR,

KRW,

THB,

MYR,

HKD,

CNY,

EGP,

EUR,

GBP,

BHD,

MAD,

AUD,

CAD,

CHF,

NZD,

PLN,

KZT,

UZS,

JPY,

GLC

metadata

object | null

Show child attributes

informations

object[]

Custom key/value metadata to attach to the subscription and echo on its webhooks.

Maximum array length: 50

Show child attributes

idempotency_key

string | null

Required string length: 1 - 255

products

object[]

Maximum array length: 100

Show child attributes

payment_method

enum<string>

padrão:credit_card

Opções disponíveis:

credit_card

trial_end

string<date-time> | null

Trial end timestamp (ISO 8601). Must be in the future.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Resposta

HTTP 201 response

success

boolean

obrigatório

requestId

string

obrigatório

data

object

obrigatório

Show child attributes

Create a Subscription

curl --request POST \
  --url https://api.pagou.ai/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "amount": 50000000,
  "token": "<string>",
  "interval_count": 1,
  "failure_policy": "retry_then_cancel",
  "retry_offsets_days": [
    15
  ],
  "currency": "BRL",
  "metadata": {},
  "informations": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "idempotency_key": "<string>",
  "products": [
    {
      "name": "<string>",
      "price": 50000000,
      "quantity": 1,
      "tangible": false,
      "sku": "<string>"
    }
  ],
  "payment_method": "credit_card",
  "trial_end": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.pagou.ai/v2/subscriptions"

payload = {
    "customer_id": "<string>",
    "amount": 50000000,
    "token": "<string>",
    "interval_count": 1,
    "failure_policy": "retry_then_cancel",
    "retry_offsets_days": [15],
    "currency": "BRL",
    "metadata": {},
    "informations": [
        {
            "key": "<string>",
            "value": "<string>"
        }
    ],
    "idempotency_key": "<string>",
    "products": [
        {
            "name": "<string>",
            "price": 50000000,
            "quantity": 1,
            "tangible": False,
            "sku": "<string>"
        }
    ],
    "payment_method": "credit_card",
    "trial_end": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '<string>',
    amount: 50000000,
    token: '<string>',
    interval_count: 1,
    failure_policy: 'retry_then_cancel',
    retry_offsets_days: [15],
    currency: 'BRL',
    metadata: {},
    informations: [{key: '<string>', value: '<string>'}],
    idempotency_key: '<string>',
    products: [
      {
        name: '<string>',
        price: 50000000,
        quantity: 1,
        tangible: false,
        sku: '<string>'
      }
    ],
    payment_method: 'credit_card',
    trial_end: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.pagou.ai/v2/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pagou.ai/v2/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => '<string>',
    'amount' => 50000000,
    'token' => '<string>',
    'interval_count' => 1,
    'failure_policy' => 'retry_then_cancel',
    'retry_offsets_days' => [
        15
    ],
    'currency' => 'BRL',
    'metadata' => [
        
    ],
    'informations' => [
        [
                'key' => '<string>',
                'value' => '<string>'
        ]
    ],
    'idempotency_key' => '<string>',
    'products' => [
        [
                'name' => '<string>',
                'price' => 50000000,
                'quantity' => 1,
                'tangible' => false,
                'sku' => '<string>'
        ]
    ],
    'payment_method' => 'credit_card',
    'trial_end' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pagou.ai/v2/subscriptions"

	payload := strings.NewReader("{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pagou.ai/v2/subscriptions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"<string>\",\n  \"amount\": 50000000,\n  \"token\": \"<string>\",\n  \"interval_count\": 1,\n  \"failure_policy\": \"retry_then_cancel\",\n  \"retry_offsets_days\": [\n    15\n  ],\n  \"currency\": \"BRL\",\n  \"metadata\": {},\n  \"informations\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"idempotency_key\": \"<string>\",\n  \"products\": [\n    {\n      \"name\": \"<string>\",\n      \"price\": 50000000,\n      \"quantity\": 1,\n      \"tangible\": false,\n      \"sku\": \"<string>\"\n    }\n  ],\n  \"payment_method\": \"credit_card\",\n  \"trial_end\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "string",
    "customerId": "string",
    "status": "incomplete",
    "paymentMethod": "credit_card",
    "billingModel": "merchant_initiated",
    "billingDayOfMonth": 1,
    "interval": "day",
    "intervalCount": 1,
    "amount": 0,
    "currency": "BRL",
    "trialEnd": "2026-07-14T12:00:00.000Z",
    "currentPeriodStart": "2026-07-14T12:00:00.000Z",
    "currentPeriodEnd": "2026-07-14T12:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "canceledAt": "2026-07-14T12:00:00.000Z",
    "failurePolicy": "immediate_cancel",
    "retryOffsetsDays": [
      1
    ],
    "cancellationReason": "user_requested",
    "customerEmail": "string",
    "cardLast4": "string",
    "metadata": {},
    "informations": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "products": [
      {
        "name": "string",
        "price": 0,
        "quantity": 1,
        "tangible": false
      }
    ],
    "recurringAuthorization": {
      "status": "pending"
    },
    "createdAt": "2026-07-14T12:00:00.000Z",
    "updatedAt": "2026-07-14T12:00:00.000Z"
  }
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 0,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Clientes

Transações

Checkout Links

Transferências

Assinaturas

Legado v1

Pré-requisitos

Comportamento

Autorizações

Corpo

Resposta

​Pré-requisitos

​Comportamento

Autorizações

Corpo

Resposta

Pré-requisitos

Comportamento