Cobra uma única vez um valor no cartão salvo da assinatura, sem CVV, sem 3DS e sem interação do cliente (venda recorrente subsequente, como as mensalidades). Uso típico: o proporcional do restante do ciclo depois de um reajuste — o valor é o que a sua plataforma calcular. Independente da série recorrente: não muda o plano, o próximo vencimento nem o status da assinatura; combine com POST .../change-plan para a mensalidade futura.
Na hora: a cobrança é feita dentro desta chamada e a resposta traz a fatura avulsa (kind=ONE_OFF) no estado final:
status | Significa |
|---|---|
PAID | Aprovada; paymentId em GET /v1/acquiring/payments/{paymentId} |
OVERDUE | Recusada (lastFailureCode ABECS, lastFailureReason). Tentativa única: a Autra não repete; cobre de novo com outro externalRef se quiser. A assinatura não muda de status. |
RETRYING sem nextAttemptAt | O adquirente não respondeu: a venda pode ter passado. Fica em conciliação; ninguém cobra de novo sozinho. Acompanhe por GET .../invoices ou pelos webhooks. |
Idempotência e timeout: externalRef é a sua chave, única por assinatura entre as cobranças avulsas. Depois de um timeout, repita a chamada com o mesmo externalRef e o mesmo valor: a resposta é a mesma fatura no estado em que estiver, sem nova cobrança (a venda também é idempotente pelo id da fatura). Mesmo externalRef com outro valor: 409 EXTERNAL_REF_IN_USE. Se a cobrança não chegou ao adquirente (503 CHARGE_NOT_SENT), nada foi debitado: repita com o mesmo externalRef.
Webhooks (domínio subscriptions): invoice.created, depois invoice.paid ou invoice.payment_failed, com invoice.kind=ONE_OFF, invoice.externalRef e invoice.description para correlacionar com o seu pedido.
Requisitos: assinatura ACTIVE ou PAST_DUE, com cartão salvo pela adesão. Pagamento por cartão de crédito à vista.
Erros — corpo {"errors":[{"code":"...","msg":"..."}]}; msg detalha o campo quando é validação:
code | HTTP | Quando acontece | O que fazer |
|---|---|---|---|
INVALID_INPUT | 400 | amount, description ou externalRef inválido; msg diz qual e a regra. | Corrija o campo indicado. |
INVALID_JSON | 400 | Corpo não é um objeto JSON válido. | Corrija o JSON. |
MISSING_DOCUMENT_ID | 400 | Estabelecimento não informado. | Envie o header X-Merchant-Document (ou documentId). |
TENANT_REQUIRED | 400 | A credencial não identifica o tenant. | Gere o token com as credenciais do seu tenant (POST /v1/oauth/token). |
FEATURE_DISABLED | 403 | O módulo de assinaturas não está habilitado para o tenant. | Peça a habilitação à Autra. |
MERCHANT_NOT_FOUND | 404 | O documento não é de um estabelecimento do seu tenant. | Confira o CPF/CNPJ do estabelecimento. |
SUBSCRIPTION_NOT_FOUND | 404 | Assinatura não existe neste estabelecimento. | Confira o id. |
EXTERNAL_REF_IN_USE | 409 | O externalRef já foi usado nesta assinatura com outro valor. | Use outra chave para outra cobrança. |
PAYLOAD_TOO_LARGE | 413 | Corpo acima de 64 KiB. | Reduza o corpo da requisição. |
SUBSCRIPTION_NOT_CHARGEABLE | 422 | Assinatura fora de ACTIVE/PAST_DUE ou sem cartão salvo válido. | Conclua a adesão do cartão ou reative a assinatura. |
INVALID_DOCUMENT | 422 | Documento do estabelecimento malformado. | CPF com 11 ou CNPJ com 14 dígitos, só números. |
INTERNAL_ERROR | 500 | Falha interna. | Consulte GET .../invoices antes de repetir; repita com o mesmo externalRef. |
CHARGE_NOT_SENT | 503 | A cobrança não chegou ao adquirente; nada foi debitado. | Repita com o mesmo externalRef. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||