Captura e Estorno
Como capturar e estornar cobranças na API SoarLabz
Captura
A captura efetiva a cobrança de um valor previamente autorizado no cartão de crédito. Cobranças de PIX e boleto são capturadas automaticamente quando o pagamento é confirmado.
Captura Total
Para capturar o valor total autorizado, basta chamar o endpoint sem body:
curl -X POST https://api.payhubrasil.com.br/v1/charges/{id}/capture \
-H "Authorization: Basic {credentials}"const response = await fetch(`https://api.payhubrasil.com.br/v1/charges/${chargeId}/capture`, {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
},
});Captura Parcial
Você pode capturar um valor menor que o autorizado:
curl -X POST https://api.payhubrasil.com.br/v1/charges/{id}/capture \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 8000
}'| Campo | Tipo | Descrição |
|---|---|---|
amount | integer | Valor em centavos para captura parcial (deve ser menor que o autorizado) |
A captura só é possível para cobranças com status authorized. Cobranças de PIX e boleto não utilizam captura manual.
Estorno
O estorno devolve total ou parcialmente o valor de uma cobrança capturada ao cliente.
Estorno Total
Para estornar o valor total, chame o endpoint sem body:
curl -X POST https://api.payhubrasil.com.br/v1/charges/{id}/refund \
-H "Authorization: Basic {credentials}"const response = await fetch(`https://api.payhubrasil.com.br/v1/charges/${chargeId}/refund`, {
method: 'POST'
Estorno Parcial
Você pode estornar apenas uma parte do valor:
curl -X POST https://api.payhubrasil.com.br/v1/charges/{id}/refund \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"reason": "Cliente solicitou reembolso parcial"
}'| Campo | Tipo | Descrição |
|---|---|---|
amount | integer | Valor em centavos para estorno parcial |
reason | string | Motivo do estorno |
Comportamento por Status
| Status após estorno | Condição |
|---|---|
refunded | Estorno total (valor integral devolvido) |
partially_refunded | Estorno parcial (parte do valor devolvido) |
O estorno só é possível para cobranças com status captured ou partially_refunded. Múltiplos estornos parciais são permitidos até atingir o valor total.
Resumo das Operações
| Operação | Status necessário | Resultado |
|---|---|---|
| Captura total | authorized | captured |
| Captura parcial | authorized | captured |
| Estorno total | captured | refunded |
| Estorno parcial | captured / partially_refunded | partially_refunded |