Criar assinatura

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "planId": "<string>",
  "itemOverrides": {},
  "items": [],
  "currency": "<string>",
  "billingGroupId": "<string>",
  "splitConfig": [
    {
      "recipientId": "<string>",
      "value": 1.01,
      "type": "sale",
      "processingFee": true,
      "liable": true
    }
  ],
  "collectionMethod": "charge_automatically",
  "collectionTiming": "prepaid",
  "invoiceGenerationMode": "just_in_time",
  "paymentBehavior": "allow_incomplete",
  "enrollmentInstallments": 6,
  "enrollmentItems": [
    {
      "description": "<string>",
      "amount": 1,
      "quantity": 1
    }
  ],
  "maxCycles": 1,
  "metadata": {},
  "referenceCode": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: '<string>',
    planId: '<string>',
    itemOverrides: {},
    items: [],
    currency: '<string>',
    billingGroupId: '<string>',
    splitConfig: [
      {
        recipientId: '<string>',
        value: 1.01,
        type: 'sale',
        processingFee: true,
        liable: true
      }
    ],
    collectionMethod: 'charge_automatically',
    collectionTiming: 'prepaid',
    invoiceGenerationMode: 'just_in_time',
    paymentBehavior: 'allow_incomplete',
    enrollmentInstallments: 6,
    enrollmentItems: [{description: '<string>', amount: 1, quantity: 1}],
    maxCycles: 1,
    metadata: {},
    referenceCode: '<string>'
  })
};

fetch('https://api.sandbox.z2pay.com/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/subscriptions"

payload = {
    "customerId": "<string>",
    "planId": "<string>",
    "itemOverrides": {},
    "items": [],
    "currency": "<string>",
    "billingGroupId": "<string>",
    "splitConfig": [
        {
            "recipientId": "<string>",
            "value": 1.01,
            "type": "sale",
            "processingFee": True,
            "liable": True
        }
    ],
    "collectionMethod": "charge_automatically",
    "collectionTiming": "prepaid",
    "invoiceGenerationMode": "just_in_time",
    "paymentBehavior": "allow_incomplete",
    "enrollmentInstallments": 6,
    "enrollmentItems": [
        {
            "description": "<string>",
            "amount": 1,
            "quantity": 1
        }
    ],
    "maxCycles": 1,
    "metadata": {},
    "referenceCode": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "sub_hsm2kigu74htdxj3nw2z6f9xw",
  "number": {
    "sequence": 43
  },
  "referenceCode": "CONTRATO-2026-0042",
  "customerId": "cust_c72q6ogr9iko0we85mqal04te",
  "customerEmail": "maria.silva@example.com",
  "customerName": "Maria Silva",
  "customerDocument": "12345678909",
  "currency": "BRL",
  "status": "active",
  "billingGroupId": null,
  "currentPeriodStart": "2025-06-29T03:00:00.000Z",
  "currentPeriodEnd": "2025-07-29T03:00:00.000Z",
  "nextInvoiceAt": "2025-07-29T03:00:00.000Z",
  "recurrence": {
    "interval": 1,
    "unit": "month",
    "anchor": "subscription_start",
    "collectionTiming": "prepaid"
  },
  "collectionMethod": "charge_automatically",
  "collectionTiming": "prepaid",
  "invoiceGenerationMode": "just_in_time",
  "cancelAtPeriodEnd": false,
  "canceledAt": null,
  "endedAt": null,
  "cancellationReason": null,
  "pausedAt": null,
  "pauseResumesAt": null,
  "pauseReason": null,
  "trialEnd": null,
  "incompleteExpiresAt": null,
  "trialRemindersFired": [],
  "maxCycles": null,
  "issuedCycles": 0,
  "completedCycles": 0,
  "defaultPaymentMethodRef": {
    "id": "crd_tsj66oabsygc9kwvvzt8189f9",
    "type": "card"
  },
  "splitConfig": null,
  "paymentBehavior": "allow_incomplete",
  "latestInvoiceId": null,
  "paymentUpdateToken": null,
  "paymentUpdateMethods": null,
  "metadata": {},
  "createdAt": "2025-06-29T13:45:30.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Subscription not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "No refundable payment found"
  }
}

{
  "error": "Idempotency key already used with a different request body"
}

POST

subscriptions

Criar assinatura

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "planId": "<string>",
  "itemOverrides": {},
  "items": [],
  "currency": "<string>",
  "billingGroupId": "<string>",
  "splitConfig": [
    {
      "recipientId": "<string>",
      "value": 1.01,
      "type": "sale",
      "processingFee": true,
      "liable": true
    }
  ],
  "collectionMethod": "charge_automatically",
  "collectionTiming": "prepaid",
  "invoiceGenerationMode": "just_in_time",
  "paymentBehavior": "allow_incomplete",
  "enrollmentInstallments": 6,
  "enrollmentItems": [
    {
      "description": "<string>",
      "amount": 1,
      "quantity": 1
    }
  ],
  "maxCycles": 1,
  "metadata": {},
  "referenceCode": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: '<string>',
    planId: '<string>',
    itemOverrides: {},
    items: [],
    currency: '<string>',
    billingGroupId: '<string>',
    splitConfig: [
      {
        recipientId: '<string>',
        value: 1.01,
        type: 'sale',
        processingFee: true,
        liable: true
      }
    ],
    collectionMethod: 'charge_automatically',
    collectionTiming: 'prepaid',
    invoiceGenerationMode: 'just_in_time',
    paymentBehavior: 'allow_incomplete',
    enrollmentInstallments: 6,
    enrollmentItems: [{description: '<string>', amount: 1, quantity: 1}],
    maxCycles: 1,
    metadata: {},
    referenceCode: '<string>'
  })
};

fetch('https://api.sandbox.z2pay.com/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/subscriptions"

payload = {
    "customerId": "<string>",
    "planId": "<string>",
    "itemOverrides": {},
    "items": [],
    "currency": "<string>",
    "billingGroupId": "<string>",
    "splitConfig": [
        {
            "recipientId": "<string>",
            "value": 1.01,
            "type": "sale",
            "processingFee": True,
            "liable": True
        }
    ],
    "collectionMethod": "charge_automatically",
    "collectionTiming": "prepaid",
    "invoiceGenerationMode": "just_in_time",
    "paymentBehavior": "allow_incomplete",
    "enrollmentInstallments": 6,
    "enrollmentItems": [
        {
            "description": "<string>",
            "amount": 1,
            "quantity": 1
        }
    ],
    "maxCycles": 1,
    "metadata": {},
    "referenceCode": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "sub_hsm2kigu74htdxj3nw2z6f9xw",
  "number": {
    "sequence": 43
  },
  "referenceCode": "CONTRATO-2026-0042",
  "customerId": "cust_c72q6ogr9iko0we85mqal04te",
  "customerEmail": "maria.silva@example.com",
  "customerName": "Maria Silva",
  "customerDocument": "12345678909",
  "currency": "BRL",
  "status": "active",
  "billingGroupId": null,
  "currentPeriodStart": "2025-06-29T03:00:00.000Z",
  "currentPeriodEnd": "2025-07-29T03:00:00.000Z",
  "nextInvoiceAt": "2025-07-29T03:00:00.000Z",
  "recurrence": {
    "interval": 1,
    "unit": "month",
    "anchor": "subscription_start",
    "collectionTiming": "prepaid"
  },
  "collectionMethod": "charge_automatically",
  "collectionTiming": "prepaid",
  "invoiceGenerationMode": "just_in_time",
  "cancelAtPeriodEnd": false,
  "canceledAt": null,
  "endedAt": null,
  "cancellationReason": null,
  "pausedAt": null,
  "pauseResumesAt": null,
  "pauseReason": null,
  "trialEnd": null,
  "incompleteExpiresAt": null,
  "trialRemindersFired": [],
  "maxCycles": null,
  "issuedCycles": 0,
  "completedCycles": 0,
  "defaultPaymentMethodRef": {
    "id": "crd_tsj66oabsygc9kwvvzt8189f9",
    "type": "card"
  },
  "splitConfig": null,
  "paymentBehavior": "allow_incomplete",
  "latestInvoiceId": null,
  "paymentUpdateToken": null,
  "paymentUpdateMethods": null,
  "metadata": {},
  "createdAt": "2025-06-29T13:45:30.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Subscription not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "No refundable payment found"
  }
}

{
  "error": "Idempotency key already used with a different request body"
}

POST /subscriptions Faz parte do recurso Assinaturas — o conceito, os dez estados e a máquina de transições estão lá. Cria a assinatura e coloca o motor de cobrança para funcionar. A partir daqui, quem emite fatura e quem cobra é a Z2Pay, no ritmo da recorrência configurada.

Informe exatamente um entre customerId e customer. Enviar os dois, ou nenhum, responde 400. O customer inline cria o cadastro na hora ou reaproveita um existente, casando primeiro pelo documento e depois pelo e-mail — é o atalho para quem ainda não tem o cust_.

Informe planId, items, ou os dois. Sem nenhum dos dois não há o que cobrar. Com os dois, os itens recorrentes do plano entram e os de items se somam a eles.Quando todos os itens são avulsos, recurrence e currency passam a ser obrigatórios: não há preço de onde derivá-los.

O estado inicial não se escolhe

Não existe campo status no corpo. O estado em que a assinatura nasce é decidido pela combinação que você envia, avaliada nesta ordem:

O que você envia	Nasce como
`enrollmentItems` + `bootstrapPayment` (adesão já paga por fora)	`active`
`enrollmentItems` sem `bootstrapPayment`	`pending_enrollment`
`trialSpec` com `requiresPaymentMethod` e sem forma de pagamento	`incomplete`, com prazo
`trialSpec` nos demais casos	`trialing`
Nada disso, com `defaultPaymentMethodRef`	`active`
Nada disso, sem `defaultPaymentMethodRef`	`incomplete`, sem prazo

trialing vence a forma de pagamento. Com trialSpec, a assinatura entra em teste mesmo com o cartão já cadastrado — e a primeira fatura só nasce quando o teste acaba. Se você esperava cobrança imediata, não envie trialSpec.

pending_enrollment tem prazo; incomplete quase nunca. A adesão precisa ser paga dentro da janela da conta (7 dias por padrão) ou a assinatura é cancelada. Já a incomplete só expira quando nasceu de um teste com requiresPaymentMethod — cerca de 23 horas. A incomplete comum fica parada até alguém agir. Ver Do incomplete ao active.

Formas de pagamento

Em defaultPaymentMethodRef, o type diz o meio e o resto diz qual:

cartão novo — tokenize com o Tokenizer SDK e envie o tok_ em token. O cartão é salvo na carteira do cliente antes de virar o padrão;
cartão já salvo — envie o crd_ em cardId. Ele precisa pertencer ao cliente da assinatura, senão responde 409;
PIX ou boleto — só o type, sem token nem cardId.

Três combinações são recusadas com 409:

enrollmentItems sem defaultPaymentMethodRef — a adesão precisa de como ser cobrada;
trialSpec junto com enrollmentItems — são opostos: um adia a cobrança, o outro a antecipa;
bootstrapPayment numa assinatura que não nasceria active — ele afirma que o ciclo 1 já foi pago, o que é incompatível com teste ou com falta de forma de pagamento.

referenceCode é o seu identificador do contrato. Volta nas respostas e é filtrável por correspondência exata na listagem. Não é único: a Z2Pay não recusa dois contratos com o mesmo código.

upfront emite tudo de uma vez. Com invoiceGenerationMode: "upfront", todas as maxCycles faturas nascem na criação, cada uma com o seu vencimento — e maxCycles passa a ser obrigatório. O padrão, just_in_time, emite uma fatura por ciclo, na virada.

Exemplo

curl -X POST https://api.sandbox.z2pay.com/v1/subscriptions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: e6c9b2a4-1f3d-4a7b-9c2e-0d8f1a2b3c4d" \
  -d '{
    "customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
    "planId": "plan_lhutpqeq2ml3stia4vn90xars",
    "referenceCode": "contrato-2026-0042",
    "defaultPaymentMethodRef": {
      "type": "card",
      "cardId": "crd_d6bvtkpr7fd4jrb3tbpm8ohqi"
    }
  }'

Resposta 201

{
  "id": "sub_x33m4yn6brazh71en4mki6f5c",
  "number": { "sequence": 42 },
  "referenceCode": "contrato-2026-0042",
  "customerId": "cust_eqjzf65crxsrywqdfptanl7yp",
  "status": "active",
  "currency": "BRL",
  "collectionMethod": "charge_automatically",
  "collectionTiming": "prepaid",
  "invoiceGenerationMode": "just_in_time",
  "recurrence": {
    "interval": 1,
    "unit": "month",
    "anchor": "subscription_start",
    "collectionTiming": "prepaid"
  },
  "cancelAtPeriodEnd": false,
  "maxCycles": null,
  "currentPeriodStart": "2026-08-10T12:00:00.000Z",
  "currentPeriodEnd": "2026-09-10T12:00:00.000Z",
  "nextInvoiceAt": "2026-09-10T12:00:00.000Z",
  "items": [
    {
      "id": "subi_wq3n8fk52hbdzr7m0aeypvcjt",
      "subscriptionId": "sub_x33m4yn6brazh71en4mki6f5c",
      "planItemId": "pli_oaimno59ai3uuqwq0ti7gxs0j",
      "priceVersionId": "price_l1r8693wk6ksbd9044bwvwu93",
      "name": "Assinatura Pro",
      "unitAmount": 9900,
      "quantity": 1
    }
  ]
}

O exemplo está abreviado — o playground ao lado mostra o corpo inteiro.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Headers

Idempotency-Key

string

Chave única para garantir idempotência da requisição

Body

application/json

customerId

string

ID de um cliente existente (exatamente um entre customerId e customer).

Minimum string length: 1

customer

object

Cliente inline: cria ou reusa (por documento, depois email) na criação da assinatura.

Show child attributes

planId

string

Instancia a assinatura a partir de um plano; pode coexistir com items extras.

Minimum string length: 1

itemOverrides

object

Override de quantidade por item do plano: { "<plan_item.key>": quantity }.

Show child attributes

items

object[]

Items da assinatura: referência (priceVersionId) ou inline (description + unitAmount em centavos).

Option 1
Option 2

Show child attributes

recurrence

object

Regra de recorrência; obrigatória quando todos os items são inline.

Show child attributes

currency

string

Moeda ISO 4217; obrigatória quando todos os items são inline.

billingGroupId

string

Grupo de cobrança (billing group).

defaultPaymentMethodRef

object

Forma de pagamento default dos ciclos. Cartão: token (novo, do Tokenizer SDK) OU cardId (cartão já salvo do cliente).

Show child attributes

splitConfig

object[]

Divisão de receita aplicada a cada ciclo cobrado; ausente = 100% pro recebedor owner.

Minimum array length: 1

Show child attributes

collectionMethod

enum<string>

default:charge_automatically

Como a fatura é cobrada. Hoje só a cobrança automática na forma de pagamento padrão.

Available options:

charge_automatically

collectionTiming

enum<string>

default:prepaid

'prepaid' (default) cobra no início do ciclo; 'postpaid' cobra no fim.

Available options:

prepaid,

postpaid

invoiceGenerationMode

enum<string>

default:just_in_time

'just_in_time' (default) gera 1 invoice por ciclo; 'upfront' emite todas na criação (requer maxCycles).

Available options:

just_in_time,

upfront

paymentBehavior

enum<string>

default:allow_incomplete

O que fazer quando a primeira cobrança da assinatura não é aprovada. allow_incomplete (default) cria a assinatura mesmo assim, com a fatura em aberto e a régua de cobrança seguindo. error_if_incomplete cancela a assinatura quando a primeira cobrança falha — use quando não fizer sentido manter um contrato que nunca chegou a ser pago.

Available options:

allow_incomplete,

error_if_incomplete

enrollmentInstallments

integer

Parcelas no cartão da fatura de adesão (1–12; default 1); >1 exige defaultPaymentMethodRef.type=card.

Required range: 1 <= x <= 12

enrollmentItems

object[]

Itens de adesão cobrados uma única vez na 1ª fatura (amount em centavos); ignorado quando planId está set.

Show child attributes

maxCycles

integer | null

Número máximo de ciclos; null/ausente = sem fim.

Required range: x > 0

metadata

object

Metadados livres do integrador.

Show child attributes

referenceCode

string

Código do contrato no sistema do integrador; pesquisável, sem unicidade.

Required string length: 1 - 255

bootstrapPayment

object

Comprovante de cobrança externa do ciclo 1 — a Invoice #1 nasce paga; exige defaultPaymentMethodRef e é incompatível com trial.

Show child attributes

trialSpec

object

Override do trial no nível da subscription; mutuamente exclusivo com bootstrapPayment.

Show child attributes

Response

Assinatura criada

string

Identificador único do registro.

number

object

Número do endereço.

Show child attributes

referenceCode

string | null

Código do contrato no sistema do integrador; pesquisável, sem unicidade.

customerId

string

ID do cliente associado ao registro.

customerEmail

string

E-mail do cliente.

customerName

string

Nome do cliente.

customerDocument

string

Documento do cliente (CPF ou CNPJ).

currency

string

Moeda no padrão ISO 4217 (ex.: BRL).

status

enum<string>

Status atual do registro (assinatura, fatura, plano ou slip de pagamento).

Available options:

incomplete,

incomplete_expired,

trialing,

active,

past_due,

unpaid,

paused,

canceled,

completed

billingGroupId

any | null

ID do grupo de cobrança ao qual o registro pertence; nulo se não agrupado.

currentPeriodStart

string<date-time>

Início do período de cobrança atual da assinatura (ISO 8601).

currentPeriodEnd

string<date-time>

Fim do período de cobrança atual da assinatura (ISO 8601).

nextInvoiceAt

string<date-time> | null

Data e hora prevista para a próxima fatura da assinatura (ISO 8601).

recurrence

object

Regra de recorrência (intervalo, unidade e âncora do ciclo).

Show child attributes

collectionMethod

enum<string>

Como a fatura é cobrada. Hoje só a cobrança automática na forma de pagamento padrão.

Available options:

charge_automatically

collectionTiming

enum<string>

Momento da cobrança do ciclo: prepaid (no início) ou postpaid (no fim).

Available options:

prepaid,

postpaid

invoiceGenerationMode

enum<string>

Modo de geração de faturas: just_in_time (a cada ciclo) ou upfront (todas antecipadas).

Available options:

just_in_time,

upfront

cancelAtPeriodEnd

boolean

Indica se a assinatura será cancelada ao fim do período atual.

canceledAt

any | null

Data e hora do cancelamento; nula se não cancelado (ISO 8601).

endedAt

any | null

Data e hora em que a assinatura foi efetivamente encerrada; nula se ainda ativa (ISO 8601).

cancellationReason

any | null

Motivo do cancelamento da assinatura.

pausedAt

any | null

Data e hora em que a assinatura foi pausada; nula se não pausada (ISO 8601).

pauseResumesAt

any | null

Data e hora agendada para a retomada automática da assinatura pausada (ISO 8601).

pauseReason

any | null

Motivo da pausa da assinatura.

trialEnd

any | null

Data e hora de término do período de teste; nula se sem trial (ISO 8601).

incompleteExpiresAt

any | null

Prazo para concluir o primeiro pagamento antes de a assinatura incompleta expirar (ISO 8601).

trialRemindersFired

any[]

Lembretes de fim do período de teste já disparados para a assinatura.

maxCycles

any | null

Número máximo de ciclos da assinatura; nulo se não houver limite.

issuedCycles

integer

Número de ciclos já faturados (faturas emitidas) da assinatura.

completedCycles

integer

Número de ciclos já concluídos (pagos) da assinatura.

defaultPaymentMethodRef

object

Referência da forma de pagamento padrão usada para cobrar a assinatura.

Show child attributes

splitConfig

any | null

Configuração de divisão (split) dos valores entre recebedores; nula se sem split.

paymentBehavior

enum<string>

O que fazer quando a primeira cobrança não é aprovada: allow_incomplete cria a assinatura com a fatura em aberto; error_if_incomplete cancela a assinatura.

Available options:

allow_incomplete,

error_if_incomplete

latestInvoiceId

any | null

ID da fatura mais recente gerada pela assinatura.

paymentUpdateToken

any | null

Token do link público para o cliente atualizar a forma de pagamento; nulo se não gerado.

paymentUpdateMethods

any | null

Formas de pagamento permitidas no link público de troca; nula se não habilitada.

metadata

object

Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Criar assinatura

O estado inicial não se escolhe

Formas de pagamento

Exemplo

Authorizations

Headers

Body

Response

​O estado inicial não se escolhe

​Formas de pagamento

​Exemplo

Authorizations

Headers

Body

Response

O estado inicial não se escolhe

Formas de pagamento

Exemplo