[MARCA] Documentação

Assinaturas (Pix Automático)

Cobrança recorrente pelo Pix Automático: o pagador autoriza uma vez no app do banco dele e, a cada ciclo (semanal, mensal, trimestral, semestral ou anual), o valor é debitado no vencimento — sem QR novo nem lembrete. Com first_payment_amount, o QR de adesão também cobra o primeiro pagamento na hora (Jornada 3). As cobranças de cada ciclo aparecem em /charges (type = recurring, com subscription_id) e seguem os eventos de sempre.

Criar assinatura

POST /v1/subscriptions

Requer o escopo charges:write. Cria a recorrência no banco e devolve o checkout_url (página de adesão com QR) e o br_code (Pix Copia e Cola da adesão). A assinatura fica pending até o pagador aprovar no app do banco dele; aprovada, vira active (evento subscription.approved) e as cobranças dos ciclos passam a ser criadas sozinhas alguns dias antes de cada vencimento.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

CampoTipoDescrição
amount obrigatóriostring (valor)

Valor de cada ciclo.

period obrigatóriostring
weeklymonthlyquarterlysemiannualannual
start_date obrigatóriostring (date)

Vencimento do 1º ciclo recorrente (pelo menos daqui a 2 dias).

end_datestring (date)

Último vencimento possível (opcional: sem data, até cancelar).

description obrigatóriostring

O que está sendo assinado (aparece no app do pagador).

payer obrigatórioobject
Campos de payer
CampoTipoDescrição
name obrigatóriostring
document obrigatóriostring

CPF ou CNPJ

retry_policystring
nonethree_in_seven_days

Débito que não aconteceu no vencimento: three_in_seven_days tenta de novo até 3 vezes em 7 dias.

first_payment_amountstring (valor)

Cobra o 1º pagamento na adesão, no mesmo QR (Jornada 3). Sem ele, o QR só autoriza a recorrência.

external_refstring

Referência do seu sistema. Única por unidade.

return_urlstring (uri)
metadataMetadata

Até 20 pares chave/valor livres do integrador (chave ≤ 40, valor ≤ 500 caracteres). Não use para dados pessoais.

Respostas

  • 201 Assinatura criada, aguardando a adesão do pagador.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
  • 422 Regra de negócio violada: `idempotency-key-reused`, `refund-exceeds-available`,
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 503 O banco está temporariamente indisponível. Repita com a mesma `Idempotency-Key` após `Retry-After`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/subscriptions" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "49.90",
  "period": "monthly",
  "start_date": "2026-11-05",
  "description": "Plano Mensal Academia",
  "payer": {
    "name": "Maria Assinante",
    "document": "12345678909"
  },
  "first_payment_amount": "49.90",
  "retry_policy": "three_in_seven_days",
  "external_ref": "contrato-8812"
}'

Identificador nos logs: api.subscriptions.create

Listar assinaturas

GET /v1/subscriptions

Requer o escopo charges:read.

Parâmetros

NomeOndeTipoDescrição
limitconsultainteger
starting_afterconsultastringCursor — ID do último objeto da página anterior.
ending_beforeconsultastringCursor — ID do primeiro objeto da página seguinte.
created_gteconsultastring (date-time)
created_lteconsultastring (date-time)
statusconsultaSubscriptionStatus

Respostas

  • 200 Lista paginada de assinaturas.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/subscriptions?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.subscriptions.list

Consultar assinatura

GET /v1/subscriptions/{subscription_id}

Requer o escopo charges:read.

Parâmetros

NomeOndeTipoDescrição
subscription_id obrigatóriocaminhostring

Respostas

  • 200 Assinatura.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/subscriptions/sub_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.subscriptions.retrieve

Cancelar assinatura

POST /v1/subscriptions/{subscription_id}/cancel

Requer o escopo charges:write. Cancela a autorização no banco e as cobranças de ciclos ainda não pagas (evento subscription.canceled com canceled_by = merchant). O pagador também pode cancelar pelo app do banco dele (canceled_by = payer).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
subscription_id obrigatóriocaminhostring

Respostas

  • 200 Assinatura cancelada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
  • 503 O banco está temporariamente indisponível. Repita com a mesma `Idempotency-Key` após `Retry-After`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/subscriptions/sub_01J9Z3F0A1B2C3D4E5F6G7H8J9/cancel" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.subscriptions.cancel