Pré-autorize e capture depois

Na pré-autorização, a cobrança acontece em dois tempos. Primeiro você autoriza: o banco do comprador confirma que o cartão é válido e separa o valor do limite, sem cobrar nada. Depois você captura, e só aí o comprador é cobrado, ou cancela, e a reserva some do limite dele. Use quando o valor final só fica certo depois do pedido: estoque confirmado, análise antifraude manual, reserva de serviço, pedido sob encomenda.

Como funcionaCopiar link da seção

Em resumo:

1. Seu servidor cria a cobrança com captureMethod: "Manual". A Accelerazione pede ao banco do comprador só a autorização, e a cobrança volta status: "RequiresCapture".
2. O valor fica reservado no limite do comprador até captureBefore, 7 dias depois da autorização. Nada foi cobrado.
3. Caminho A: POST /api/v1/paymentintents/{id}/capture cobra o valor. A cobrança vira Succeeded e chega payment_intent.succeeded.
4. Caminho B: POST /api/v1/paymentintents/{id}/cancel libera a reserva sem cobrar. A cobrança vira Canceled e chega payment_intent.canceled.
5. Sem decisão até captureBefore, a Accelerazione libera a reserva sozinha. A cobrança vira Canceled com cancellationReason: "expired".

Antes de começarCopiar link da seção

A pré-autorização vale para um subconjunto da cobrança com cartão. A cobrança precisa ter:

• Crédito, com exatamente um item em paymentMethods. Débito não é aceito.
• Uma parcela: paymentMethodOptions.creditCard.installments igual a 1 ou ausente.
• Sem 3DS: não envie threeDs.sessionToken nem threeDSecure: "required". Se a política de aceitação exigir autenticação para aquele cartão, a cobrança é recusada com THREE_DS_DEFERRED_CAPTURE_NOT_SUPPORTED; nesse caso, cobre com captura automática.
• Confirmação imediata: deferConfirmation ausente ou false.
• Conta habilitada para pré-autorização.

O resto da cobrança é igual ao da cobrança com cartão: cartão aberto ou card.token, comprador, split, postbackUrl e metadata.

1. Autorize o valorCopiar link da seção

Acrescente captureMethod: "Manual" na raiz do corpo. A grafia é exata: capture_method em snake_case é ignorado e a cobrança sai com captura automática, ou seja, cobrada na hora.

{
  "amount": 10990,
  "currency": "BRL",
  "captureMethod": "Manual",
  "paymentMethods": [{
    "type": "CreditCard",
    "amount": 10990,
    "card": {
      "number": "5555555555554444",
      "expMonth": 12,
      "expYear": 2030,
      "cvc": "123",
      "holderName": "MARIA SOUZA"
    }
  }],
  "paymentMethodOptions": { "creditCard": { "installments": 1 } },
  "customer": {
    "name": "Maria Souza",
    "email": "maria@example.com",
    "document": "12345678909",
    "address": { "zipCode": "01310100", "country": "BR" }
  },
  "postbackUrl": "https://loja.example.com/webhooks/dm",
  "metadata": { "orderId": "pedido-1001" }
}

curl -X POST "$DM_API_BASE/api/v1/paymentintents" \
  -H "Authorization: $DM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001-tentativa-1" \
  --data-binary @pre-autorizacao.json

Com o cartão aprovado, a resposta é 201 com status: "RequiresCapture", e o webhook payment_intent.requires_capture é enviado. Guarde o id e o captureBefore.

{
  "id": "3b8f6c2a-91d4-4e7b-a0c5-6d2e8f1a4b97",
  "status": "RequiresCapture",
  "captureMethod": "Manual",
  "amount": 10990,
  "amountCapturable": 10990,
  "amountCaptured": 0,
  "amountReleased": 0,
  "authorizedAt": "2026-11-04T18:00:00Z",
  "captureBefore": "2026-11-11T18:00:00Z",
  "capture": null,
  "lastCaptureError": null,
  "paymentMethods": [{
    "type": "CreditCard",
    "status": "Authorized",
    "amountCapturable": 10990,
    "amountCaptured": 0
  }]
}

Os outros desfechos do create são os da cobrança com cartão:

2a. Capture o valorCopiar link da seção

Quando decidir cobrar, capture. O corpo é opcional: sem amount, a captura é do valor autorizado.

curl -X POST "$DM_API_BASE/api/v1/paymentintents/3b8f6c2a-91d4-4e7b-a0c5-6d2e8f1a4b97/capture" \
  -H "Authorization: $DM_API_KEY" \
  -H "Idempotency-Key: captura-pedido-1001-tentativa-1"

A resposta traz a cobrança inteira:

A captura parcial não está disponível. Enviar um amount menor que o autorizado responde 422 capture_not_supported_by_provider; maior que o autorizado, 422 capture_amount_exceeds_capturable. Se o valor final ficou menor, cancele a reserva e crie outra cobrança com o valor certo.

2b. Ou cancele e libere a reservaCopiar link da seção

Se o pedido não vai seguir, cancele. Nada é cobrado e o valor volta ao limite do comprador. O motivo é opcional; o padrão é requested_by_customer.

curl -X POST "$DM_API_BASE/api/v1/paymentintents/3b8f6c2a-91d4-4e7b-a0c5-6d2e8f1a4b97/cancel" \
  -H "Authorization: $DM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancelamento-pedido-1001" \
  -d '{ "cancellationReason": "requested_by_customer" }'

Escreva o motivo em minúsculas. Valor fora da lista responde 400 invalid_cancellation_reason. O motivo expired existe só nas respostas: é a Accelerazione que o usa quando o prazo vence.

Com 200, a cobrança vira Canceled, amountReleased mostra o valor liberado e payment_intent.canceled é enviado. Um 202 tem o mesmo tratamento da captura, com capture.status: "VoidProcessing". Depois da captura não existe cancelamento: a resposta é 409 already_captured_use_refund e o caminho é o estorno.

O prazo da reservaCopiar link da seção

A reserva vale até captureBefore, 7 dias depois de authorizedAt. Agende a decisão dentro desse prazo e use o campo da resposta, não um cálculo próprio.

Sem captura nem cancelamento, a Accelerazione libera a reserva depois de captureBefore: a cobrança vira Canceled com cancellationReason: "expired" e payment_intent.canceled é enviado. A liberação roda em ciclos de alguns minutos, então a mudança de status não é instantânea. Uma captura feita nesse intervalo pode responder 422 authorization_expired; a cobrança então vira Canceled com motivo expired.

Acompanhe pelos webhooksCopiar link da seção

Os eventos chegam na postbackUrl da cobrança, com o mesmo envelope e a mesma assinatura dos demais.

O 202 da captura e do cancelamento não gera webhook: o evento chega quando o resultado sai. O conteúdo de cada evento está em Eventos.

Os campos de valorCopiar link da seção

Todos em centavos.

Toda cobrança passa a ter captureMethod, e uma cobrança Automatic paga mostra amountCaptured igual a amount. Em cobranças Automatic, paymentMethods[].status vem null.

Repita com segurançaCopiar link da seção

A captura e o cancelamento aceitam Idempotency-Key (1 a 200 caracteres), retida por 24 horas.

• Use uma chave por tentativa de decisão, por exemplo captura-pedido-1001-tentativa-1. Repita com a mesma chave depois de timeout, 503 ou queda de conexão.
• Sem o cabeçalho, a chave é a própria cobrança. A primeira resposta, inclusive um erro, se repete por 24 horas. Se a primeira captura foi recusada e você quer tentar de novo, envie uma chave nova.
• A mesma chave com outro corpo (outro amount ou outro motivo) responde 409 idempotency_payload_mismatch.

Depois da captura: estornoCopiar link da seção

Uma pré-autorização capturada é uma cobrança Succeeded comum: o estorno segue o mesmo fluxo e é integral, sobre amountCaptured.

ErrosCopiar link da seção

O código vem em type, no formato Problem Details. Catálogo completo em códigos de erro.

O que esta página não cobreCopiar link da seção

• Captura parcial e várias capturas da mesma reserva: não disponíveis.
• Pré-autorização com 3DS, parcelas ou débito: não disponíveis. Use a cobrança com cartão com captura automática.
• Referência das rotas: Capturar e Cancelar.