Assinaturas (Pix Automático)

Crie assinaturas com cobrança recorrente via Pix Automático: o pagador autoriza uma única vez e as cobranças de cada ciclo são geradas e liquidadas automaticamente. Para entender o produto, veja o guia Pix Automático.

Criar assinatura

POST/v1/recurrences

Cria uma assinatura Pix Automático e retorna o QR Code de adesão (1º pagamento + autorização)

QR Code composto (Jornada 3)O QR Code retornado é um QR composto: ao escaneá-lo no app do banco, o pagador paga a primeira cobrança imediata (firstCharge) e autoriza a recorrência no mesmo ato. Após a aprovação (evento recurrence.approved), a plataforma agenda automaticamente as cobranças de cada ciclo — você não precisa criar cobranças; basta ouvir os webhooks.

Parâmetros do Request

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor de cada ciclo da assinatura em reais (decimal). Valor fixo — é o mesmo em todos os ciclos.`Ex: 49.90`
`periodicity`	string	Sim	Periodicidade das cobranças: WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou ANNUAL`Ex: "MONTHLY"`
`startDate`	string	Sim	Data da primeira cobrança recorrente (YYYY-MM-DD). Mínimo: hoje + 1 período da periodicidade — a cobrança de ativação já cobre o 1º período (evita cobrança dupla) — respeitando também a antecedência mínima de 3 dias do Pix Automático`Ex: "2026-08-10"`
`endDate`	string	Não	Data de término da assinatura (YYYY-MM-DD). Se omitido, a assinatura vale por prazo indeterminado`Ex: "2027-08-10"`
`retryPolicy`	string	Não	Política de retentativa dos ciclos: NONE (sem retentativa) ou RETRY_3R_7D (até 3 retentativas em 7 dias). Padrão: NONE`Ex: "RETRY_3R_7D"`
`customerName`	string	Sim	Nome completo do pagador`Ex: "João da Silva"`
`customerCpf`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, apenas números`Ex: "12345678901"`
`customerEmail`	string	Não	Email do pagador`Ex: "joao@email.com"`
`description`	string	Não	Descrição da assinatura (máx. 35 caracteres) — aparece para o pagador no app do banco`Ex: "Plano Ouro"`
`externalReference`	string	Não	Identificador externo para referência no seu sistema`Ex: "ASSINATURA-001"`
`postbackUrl`	string	Não	URL de callback para receber as notificações desta assinatura`Ex: "https://cliente.com/webhook"`
`activationExpirationMinutes`	number	Não	Tempo de expiração do QR Code de adesão em minutos`Ex: 60`
`split`	array	Não	Split de pagamentos: replicado automaticamente em cada ciclo da assinatura (mesmas regras das cobranças). Cada item: { subAccountId, type: "PERCENT" \| "FIXED", value }`Ex: [{ "subAccountId": "...", "type": "PERCENT", "value": 10 }]`
`splitFeePayer`	string	Não	Quem absorve a taxa no split percentual, replicado em cada ciclo. SUBACCOUNTS (default): percentual sobre o líquido. OWNER: percentual sobre o bruto — taxa sai do residual da conta principal`Ex: "OWNER"`

Campos da Resposta

recurrenceId: ID único da assinatura no ActivePayments (use para consultas)
idRec: identificador da recorrência no arranjo Pix (BCB) — também aceito nas consultas
status: status da assinatura — inicia em PENDING_APPROVAL até o pagador aderir
amount: valor de cada ciclo (string com decimal — ex: "49.90")
pix.qrCode: código copia-e-cola do QR composto (1º pagamento + adesão)
pix.qrCodeBase64: imagem do QR Code em Base64 (PNG)
pix.expiresAt: data/hora de expiração do QR Code de adesão (ISO 8601)
firstCharge: a primeira cobrança (imediata), com chargeId, externalId (txid), amount, netAmount, fee e status
externalReference: eco do externalReference enviado na requisição

Rate limit e IPEste endpoint aceita até 30 requisições por minuto e não requer IP whitelistado. Os campos amount, netAmount e fee são retornados como string (serialização de Decimal) — converta antes de calcular.

Códigos de Erro

Código	Descrição	Solução
`400`	startDate abaixo do mínimo	Envie `startDate` a partir de hoje + 1 período da periodicidade (a cobrança de ativação já cobre o 1º período), respeitando a antecedência mínima de 3 dias do arranjo Pix Automático
`400`	Pix Automático indisponível	O gateway da sua conta não oferece Pix Automático — entre em contato com o suporte
`400`	Dados inválidos	Verifique os campos obrigatórios, o CPF/CNPJ (11 ou 14 dígitos) e o limite de 35 caracteres da `description`
`401`	Não autenticado	Verifique suas credenciais de API Key
`500`	Erro no gateway	Tente novamente ou entre em contato com o suporte

Listar assinaturas

GET/v1/recurrences

Retorna as assinaturas da sua conta, paginadas e filtráveis por status

Query params

Query (opcional)

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	PENDING_APPROVAL, APPROVED, REJECTED, EXPIRED, CANCELLED`Ex: "APPROVED"`
`page`	number	Não	Página (default 1)`Ex: 1`
`limit`	number	Não	Itens por página (default 20)`Ex: 20`

Resposta

HTTP 200 OK
{
  "success": true,
  "data": [
    {
      "recurrenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "idRec": "RR1234567820260810abcdefghijk",
      "status": "APPROVED",
      "amount": "49.90",
      "periodicity": "MONTHLY",
      "startDate": "2026-08-10",
      "endDate": null,
      "retryPolicy": "RETRY_3R_7D",
      "description": "Plano Ouro",
      "customer": { "name": "João da Silva", "cpf": "12345678901" },
      "externalReference": "ASSINATURA-001",
      "createdAt": "2026-07-09T10:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Consultar assinatura

GET/v1/recurrences/:id

Retorna os dados completos da assinatura, incluindo o QR Code e os ciclos de cobrança

O parâmetro :id aceita tanto o recurrenceId quanto o idRec. A resposta inclui pix.qrCode / pix.qrCodeBase64 (útil para reexibir o QR de adesão enquanto a assinatura está em PENDING_APPROVAL) e o array charges com todos os ciclos.

HTTP 200 OK
{
  "success": true,
  "data": {
    "recurrenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idRec": "RR1234567820260810abcdefghijk",
    "status": "APPROVED",
    "amount": "49.90",
    "periodicity": "MONTHLY",
    "startDate": "2026-08-10",
    "endDate": null,
    "retryPolicy": "RETRY_3R_7D",
    "description": "Plano Ouro",
    "customer": {
      "name": "João da Silva",
      "cpf": "12345678901",
      "email": "joao@email.com"
    },
    "externalReference": "ASSINATURA-001",
    "pix": {
      "qrCode": "00020101021226880014br.gov.bcb.pix...",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..."
    },
    "charges": [
      {
        "chargeId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "transactionId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "externalId": "txid_abc123xyz",
        "cycle": 1,
        "dueDate": "2026-08-10",
        "status": "PAID",
        "amount": "49.90",
        "endToEndId": "E12345678202608101005abc123xyz456",
        "paidAt": "2026-08-10T10:05:23.000Z",
        "failedReason": null,
        "createdAt": "2026-08-08T03:00:00.000Z"
      }
    ],
    "createdAt": "2026-07-09T10:30:00.000Z"
  }
}

Listar ciclos de cobrança

GET/v1/recurrences/:id/charges

Retorna apenas os ciclos de cobrança de uma assinatura

Cada item do array charges representa um ciclo: cycle é o número sequencial, dueDate é o vencimento e status segue o ciclo de vida SCHEDULED → CREATED → ACTIVE → PAID | FAILED | CANCELLED. Quando pago, o ciclo traz transactionId, endToEndId e paidAt; quando falha, failedReason.

HTTP 200 OK
{
  "success": true,
  "data": {
    "recurrenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idRec": "RR1234567820260810abcdefghijk",
    "status": "APPROVED",
    "charges": [
      {
        "chargeId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "transactionId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "externalId": "txid_abc123xyz",
        "cycle": 1,
        "dueDate": "2026-08-10",
        "status": "PAID",
        "amount": "49.90",
        "endToEndId": "E12345678202608101005abc123xyz456",
        "paidAt": "2026-08-10T10:05:23.000Z",
        "failedReason": null,
        "createdAt": "2026-08-08T03:00:00.000Z"
      },
      {
        "chargeId": "d4e5f6a7-b8c9-0123-defa-456789012345",
        "transactionId": null,
        "externalId": "txid_def456uvw",
        "cycle": 2,
        "dueDate": "2026-09-10",
        "status": "SCHEDULED",
        "amount": "49.90",
        "endToEndId": null,
        "paidAt": null,
        "failedReason": null,
        "createdAt": "2026-08-10T03:00:00.000Z"
      }
    ]
  }
}

Cancelar assinatura

DELETE/v1/recurrences/:id

Cancela a assinatura e os ciclos agendados que ainda não foram liquidados

O body é opcional e aceita um motivo: { "reason": "Cliente solicitou cancelamento" }. Ciclos já pagos não são afetados; ciclos agendados e não liquidados são cancelados. O evento recurrence.cancelled é enviado aos seus webhooks.

HTTP 200 OK
{
  "success": true,
  "data": {
    "recurrenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idRec": "RR1234567820260810abcdefghijk",
    "status": "CANCELLED",
    "amount": "49.90",
    "periodicity": "MONTHLY",
    "externalReference": "ASSINATURA-001"
  }
}

Códigos de erro (consultas e cancelamento)

Código	Quando ocorre
`404`	Assinatura não encontrada (ou pertence a outra conta)
`400`	Assinatura em status que não permite cancelamento (ex: já cancelada)

Status da assinatura e dos ciclos

Assinatura

Status	Descrição
`PENDING_APPROVAL`	Aguardando o pagador escanear o QR Code e autorizar a recorrência
`APPROVED`	Adesão confirmada — os ciclos serão cobrados automaticamente
`REJECTED`	O pagador (ou o banco dele) recusou a autorização
`EXPIRED`	O QR Code de adesão expirou sem autorização
`CANCELLED`	Cancelada — por você (via DELETE), pelo pagador no app do banco ou pelo PSP

Ciclo de cobrança

Status	Descrição
`SCHEDULED`	Ciclo agendado internamente para a data de vencimento
`CREATED`	Cobrança do ciclo criada no PSP
`ACTIVE`	Cobrança ativa aguardando liquidação no vencimento
`PAID`	Ciclo liquidado — valor líquido creditado no seu saldo
`FAILED`	Liquidação falhou (ex: saldo insuficiente do pagador) após esgotar as retentativas
`CANCELLED`	Ciclo cancelado (assinatura cancelada antes da liquidação)

Webhooks relacionados

recurrence.approved / recurrence.rejected / recurrence.expired / recurrence.cancelled — mudanças de status da assinatura
recurrence.charge.created / recurrence.charge.paid / recurrence.charge.failed — ciclo criado, pago ou com falha
charge.paid — continua sendo disparado para a transação de cada ciclo e para a 1ª cobrança (compatibilidade)

Veja os payloads completos em Webhooks.

Próximo passoEntenda o produto em Pix Automático e configure seus Webhooks.

Requisição (POST /v1/recurrences)

curl -X POST "https://api.activepayments.com.br/api/v1/recurrences" \
  -H "Authorization: ApiKey PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "periodicity": "MONTHLY",
    "startDate": "2026-08-10",
    "retryPolicy": "RETRY_3R_7D",
    "customerName": "João da Silva",
    "customerCpf": "12345678901",
    "customerEmail": "joao@email.com",
    "description": "Plano Ouro",
    "externalReference": "ASSINATURA-001"
  }'

HTTP 201 Created
{
  "success": true,
  "data": {
    "recurrenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idRec": "RR1234567820260810abcdefghijk",
    "status": "PENDING_APPROVAL",
    "amount": "49.90",
    "periodicity": "MONTHLY",
    "startDate": "2026-08-10",
    "endDate": null,
    "retryPolicy": "RETRY_3R_7D",
    "description": "Plano Ouro",
    "customer": {
      "name": "João da Silva",
      "cpf": "12345678901",
      "email": "joao@email.com"
    },
    "externalReference": "ASSINATURA-001",
    "pix": {
      "qrCode": "00020101021226880014br.gov.bcb.pix...",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
      "expiresAt": "2026-07-09T11:30:00.000Z"
    },
    "firstCharge": {
      "chargeId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "externalId": "txid_abc123xyz",
      "amount": "49.90",
      "netAmount": "47.90",
      "fee": "2.00",
      "status": "PENDING"
    },
    "createdAt": "2026-07-09T10:30:00.000Z"
  }
}