Cria uma pré-autorização (reserva de limite) sem capturar o valor.
Use POST /v1/acquiring/payments/{paymentId}/capture para capturar posteriormente.
Idempotência: o campo orderId é a chave de idempotência, com escopo por merchant
(documentId) dentro do seu tenant. A ordem é reivindicada antes da chamada ao
adquirente — retries (timeout, queda de rede, reprocessamento) com o mesmo orderId
nunca geram uma segunda reserva no cartão: a requisição duplicada recebe
409 ORDER_ALREADY_PREAUTHORIZED, sem cobrança. Tentativas que terminaram em falha
(FAILED/ERROR/EXPIRED) liberam o orderId para reuso — reenvie com a mesma
chave após um timeout ou recusa. Sem orderId (ausente ou vazio) a idempotência
fica desligada: cada POST cria uma nova pré-autorização — evite em produção.
Códigos de erro
Quando a pré-autorização não é aprovada a resposta é 422 com errors[]. O campo code diz o que
aconteceu e se vale retentar:
errors[].code | Significado | O que fazer |
|---|---|---|
AUTHORIZER_REJECTED | O emissor do cartão recusou. msg traz o código de resposta do emissor e o texto, ex.: 51 - Not sufficient funds, 59 - Suspected fraud, 05 - Do not honor, 46 - Identification required, 19 - Re-enter transaction, 61 - Exceeds withdrawal limit. | Recusa definitiva para esta tentativa; nenhuma reserva foi feita. 19 e 46 valem uma nova tentativa pelo portador. |
TOKEN_NOT_AVAILABLE | O token do cartão (tokenData.slugToken) deixou de ser elegível. | Tokenize o cartão novamente. Retentar com o mesmo token continua falhando. |
MSG_GENERAL_ERROR | Erro técnico no processamento (a msg traz o detalhe, ex.: 502 : badGateway). Nenhuma reserva foi feita. | Transitório: retente com o mesmo orderId — a idempotência garante que não haverá segunda reserva. |
UNAUTHORIZED | Falha técnica transitória de autenticação no processamento. | Retente. |
Demais status HTTP: 400 validação do body, 401/403 token ou IP não autorizado, 409
ORDER_ALREADY_PREAUTHORIZED (idempotência — a reserva original está de pé).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Body inválido ou campos obrigatórios ausentes
Token inválido ou IP não autorizado
ORDER_ALREADY_PREAUTHORIZED — o orderId já possui uma pré-autorização ativa. Não é erro do usuário: a reserva original está de pé; consulte-a e siga para captura ou cancelamento.
Pré-autorização recusada pelo adquirente (o body traz errors[] com código e mensagem).