Docs
Referência da APIPré-autorização

Capturar pré-autorização

Captura uma cobrança `RequiresCapture` criada com `captureMethod: Manual`. A captura é do valor total autorizado: a captura parcial não está disponível. `200` confirma a captura (`status: "Succeeded"`) e o webhook `payment_intent.succeeded` é enviado. `202` significa que o resultado ainda está sendo confirmado: **não repita com outra chave**; consulte a cobrança depois de `Retry-After` segundos. Uma captura recusada mantém a cobrança em `RequiresCapture`; você pode tentar de novo com uma nova `Idempotency-Key` até `captureBefore`.

POST
/api/v1/paymentintents/{id}/capture

Captura uma cobrança RequiresCapture criada com captureMethod: Manual. A captura é do valor total autorizado: a captura parcial não está disponível. 200 confirma a captura (status: "Succeeded") e o webhook payment_intent.succeeded é enviado. 202 significa que o resultado ainda está sendo confirmado: não repita com outra chave; consulte a cobrança depois de Retry-After segundos. Uma captura recusada mantém a cobrança em RequiresCapture; você pode tentar de novo com uma nova Idempotency-Key até captureBefore.

Autenticação

ApiKey
headerAuthorization<token>

A chave de API crua, sem prefixo: kpa_test_sk_… no sandbox e kpa_live_sk_… em produção. Use apenas no servidor.

Parâmetros de rota

id*string
Formatouuid

Cabeçalhos

Idempotency-Key?string

Uma por tentativa de captura, 1 a 200 caracteres. Sem cabeçalho, a chave é a própria cobrança: a primeira resposta (inclusive um erro) se repete por 24 horas.

Tamanho1 <= length <= 200

Corpo da requisição

application/json
  1. body
amount?integer

Centavos a capturar. Omita para capturar o valor autorizado; um valor menor responde 422 capture_not_supported_by_provider.

Corpo da resposta

Captura confirmada.

application/json
  1. response
id?string
Formatouuid
object?string
amount?integer
currency?string
status?PaymentIntentStatus
Valores aceitos"Created""Processing""RequiresAction""RequiresCapture""Succeeded""Failed""Canceled""Refund""ChargedBack"
statusDetail?|

Lista aberta, ex. PENDING_CHALLENGE, AUTHENTICATION_FAILED.

merchantId?string
captureMethod?string

Como a cobrança é capturada. Automatic em toda cobrança sem pré-autorização.

Valores aceitos"Automatic""Manual"
amountCapturable?integer

Centavos que ainda podem ser capturados. Maior que 0 só em RequiresCapture.

amountCaptured?integer

Centavos capturados. Numa cobrança Automatic paga, é o valor total.

amountReleased?integer

Centavos liberados de volta ao limite do comprador (cancelamento, expiração ou sobra da captura).

authorizedAt?|
Formatodate-time
captureBefore?|

Prazo da reserva. Depois dele a autorização é liberada sozinha e a cobrança vira Canceled com cancellationReason expired.

Formatodate-time
capturedAt?|
Formatodate-time
canceledAt?|
Formatodate-time
cancellationReason?|
Valores aceitos"requested_by_customer""duplicate""fraudulent""abandoned""expired"null
lastCaptureError?|

Última falha de captura ou cancelamento. Com code capture_ambiguous ou void_ambiguous, o resultado ainda está sendo confirmado: consulte a cobrança antes de repetir.

capture?|

Operação de captura ou cancelamento em curso ou concluída. null até a primeira operação.

paymentMethods?array<>
customer?
split?|null
metadata?
lastPaymentError?|null
nextAction?|null
pixPayment?|null
pagalevePayment?|null
postbackUrl?string|null
description?string|null
statementDescriptor?string|null
created?string
Formatodate-time
succeededAt?|
Formatodate-time
Exemplo de requisição
curl -X POST 'https://g6idryo27h.execute-api.us-east-1.amazonaws.com/api/v1/paymentintents/8b727267-bf39-48a4-91ea-eb0780cb48a9/capture' \  -H 'Content-Type: application/json' \  -d '{  "amount": 10990}'
Exemplo de resposta
{  "id": "3b8f6c2a-91d4-4e7b-a0c5-6d2e8f1a4b97",  "object": "payment_intent",  "amount": 10990,  "currency": "BRL",  "status": "Succeeded",  "captureMethod": "Manual",  "amountCapturable": 0,  "amountCaptured": 10990,  "amountReleased": 0,  "authorizedAt": "2026-11-04T18:00:00Z",  "captureBefore": "2026-11-11T18:00:00Z",  "capturedAt": "2026-11-05T14:20:00Z",  "canceledAt": null,  "cancellationReason": null,  "lastCaptureError": null,  "capture": {    "id": "cap_3f2a9c0e6b1d4e8a9c2b7f5a1d3e6c90",    "amount": 10990,    "status": "Succeeded"  },  "succeededAt": "2026-11-05T14:20:00Z",  "paymentMethods": [    {      "type": "CreditCard",      "amount": 10990,      "currency": "BRL",      "status": "Captured",      "amountCapturable": 0,      "amountCaptured": 10990,      "card": {        "maskedNumber": "**** **** **** 4444",        "expMonth": 12,        "expYear": 2030,        "holderName": "MARIA SOUZA",        "brand": "MASTERCARD",        "lastFourDigits": "4444",        "bin": "555555",        "threeDs": null      },      "pix": null    }  ],  "lastPaymentError": null,  "nextAction": null,  "metadata": {    "orderId": "pedido-1001"  },  "created": "2026-11-04T18:00:00Z"}

Cancelar pré-autorização POST

Cancela uma cobrança `RequiresCapture` e libera o valor reservado no cartão do comprador. Nada é cobrado. `200` confirma o cancelamento (`status: "Canceled"`) e o webhook `payment_intent.canceled` é enviado. Depois da captura não há cancelamento: use o estorno.

Solicitar estorno POST

Pede o estorno **integral** e assíncrono de uma cobrança `Succeeded`. `202` confirma o pedido, não a devolução. O desfecho chega pelos webhooks `payment_intent.refunded` e `payment_intent.refund_failed`. A chave de idempotência vai no **corpo**.