DocsAutorizações, Capturas e Anulações
Gerir fluxos de autorização, captura e anulação de pagamentos
Alguns métodos de pagamento suportam um fluxo em dois passos: primeiro autorizar (reservar fundos), depois capturar (cobrar os fundos) ou anular (libertar a reserva).
Modos de Captura
Defina capture_mode na encomenda para controlar quando os fundos são capturados:
| Modo | Comportamento |
|---|---|
manual | Captura explicitamente quando estiver pronto (ex.: após a expedição). Se não capturar antes da encomenda expirar, a autorização é perdida e não pode ser capturada. |
delayed | Os fundos são automaticamente capturados no momento em que o expiration_period decorre. |
{
"currency": "EUR",
"amount": 5000,
"capture_mode": "manual",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}Com captura manual, deve capturar antes do período de expiração da encomenda terminar. Depois de expirada, a autorização é libertada e os fundos não podem ser capturados. Defina um expiration_period apropriado para o seu cronograma de processamento.
Pode definir capture_mode ao nível da encomenda sem especificar transactions. A página de pagamento alojada mostrará então apenas os métodos de pagamento que suportam o modo de captura especificado.
Verificar Montantes Capturáveis
Antes de capturar, pode verificar quanto está disponível para captura solicitando amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"A resposta inclui um objeto amount_details:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Linhas da Encomenda
Ao utilizar capturas e anulações por linha de encomenda, utilize estes tipos:
| Tipo | Descrição |
|---|---|
physical | Produto físico |
discount | Montante de desconto |
shipping_fee | Custo de envio |
sales_tax | Imposto sobre vendas |
digital | Produto digital |
gift_card | Cartão presente |
store_credit | Crédito de loja |
surcharge | Sobretaxa |
Capturar Pagamentos
Captura por Linha de Encomenda
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Captura por Montante
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Anular Pagamentos
A anulação liberta os fundos autorizados de volta ao cliente.
Anulação por Linha de Encomenda
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Anulação por Montante
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Parâmetros de Consulta
Adicione parâmetros de consulta para incluir detalhes adicionais na resposta:
| Parâmetro | Descrição |
|---|---|
?fields[]=order_line_details | Incluir detalhes das linhas de encomenda |
?fields[]=amount_details | Incluir detalhes dos montantes |
Bloqueio Otimista
Os endpoints de captura e anulação suportam bloqueio otimista baseado em ETag através do cabeçalho if-match. Isto previne condições de corrida quando múltiplos sistemas tentam capturar a mesma transação.
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
-u {api_key}: \
-H "Content-Type: application/json" \
-H "if-match: \"etag-value\"" \
-d '{"description": "Capture", "amount": 2500}'Se o ETag não corresponder (a encomenda foi modificada desde a sua última consulta), receberá uma resposta 412 Precondition Failed.
A Cost+ suporta uma captura por autorização, e as anulações só podem ser processadas antes de qualquer captura. Planeie a sua estratégia de captura em conformidade.
Endpoints Relacionados
- Captura por Montante — capturar um montante específico de uma encomenda autorizada
- Captura por Linha de Encomenda — capturar linhas de encomenda específicas
- Anulação por Montante — anular um montante específico de uma encomenda autorizada
- Anulação por Linha de Encomenda — anular linhas de encomenda específicas