Autenticação e idempotência
Autenticação
Toda requisição leva a chave no cabeçalho Authorization, no esquema Bearer:
export WP_API=https://pay-api.staging.bloomx.cloud
export WP_KEY='wp_test.<key_id>.<segredo>' # lida do cofre do servidor
curl -s "$WP_API/v1/capabilities" -H "Authorization: Bearer $WP_KEY"
| Situação | Resposta |
|---|---|
| sem chave, chave inválida, revogada ou de outro ambiente | 401 unauthorized |
| chave sem a permissão da rota | 403 insufficient_scope |
| estabelecimento sem o produto de pagamentos online habilitado | 403 merchant_disabled |
| pagamento inexistente ou de outro estabelecimento | 404 not_found |
| limite de requisições excedido | 429 rate_limited |
Um pagamento de outro estabelecimento responde 404, e não 403: a API não confirma que o id existe.
Rastreio: X-Correlation-Id
Opcionalmente, envie um UUID no cabeçalho X-Correlation-Id nas operações de pagamento. Ele volta
no campo correlation_id do envelope de erro e ajuda o suporte a localizar a requisição.
Idempotência: Idempotency-Key
Todo POST de pagamento exige o cabeçalho Idempotency-Key: a criação (POST /v1/payments), a
captura (POST /v1/payments/{id}/capture) e o cancelamento ou estorno
(POST /v1/payments/{id}/cancel). Sem ele, a resposta é 400 missing_idempotency_key.
- Formato: de 8 a 128 caracteres entre
A-Z,a-z,0-9,:,_,-e.. - Uma chave por intenção, por exemplo
pedido-1234:autorizar,pedido-1234:capturarepedido-1234:estorno-1. Cada estorno parcial leva a sua própria chave. - Repita com a mesma chave quando reenviar a mesma requisição depois de um timeout ou de uma falha de rede. A API devolve o resultado da primeira execução em vez de cobrar de novo.
| Situação | Resposta |
|---|---|
| mesma chave, mesmo corpo, requisição já concluída | 200 com o resultado original (ou o mesmo erro, se ela falhou) |
| mesma chave, corpo diferente | 409 idempotency_conflict |
| mesma chave, criação ainda em curso | 409 idempotency_in_progress: espere e consulte |
| mesma chave, captura ou estorno ainda em curso | 202 com o pagamento: espere e consulte |
Resultado ambíguo: HTTP 202 e o status unknown
Às vezes a API envia a operação à rede de cartões e não recebe uma resposta conclusiva, por exemplo
num timeout do outro lado. Nesse caso a resposta é HTTP 202 com o pagamento no corpo, em
status: unknown (ou num status de transição, como capturing, enquanto a operação está em curso),
e o bloco operation indica qual operação ficou pendente.
O que fazer:
- Não reenvie com outra
Idempotency-Key. Isso poderia cobrar duas vezes. - Consulte
GET /v1/payments/{id}de tempos em tempos (por exemplo, a cada minuto) ou espere o webhookpayment.status_changed. - A CDX Pay concilia a operação com a rede de cartões e o pagamento sai de
unknownpara o status final (captured,pre_authorized,failede assim por diante). Você recebe o webhook quando isso acontece.
Enquanto o pagamento estiver em unknown, trate o pedido como "pagamento em análise": não libere a
mercadoria e não peça outro cartão ao comprador.