Pular para o conteúdo principal

Refunds

A refund returns funds from a confirmed deposit back to the payer. It is used for suspected fraud, operator error, and the automatic reversals triggered by ownership rules.

API: PUT /v1/pix/refund/{endToEndId}, GET /v1/pix/refund/{endToEndId}

What identifies a refund​

A refund is addressed by the endToEndId of the original deposit — not by its chargeId. You obtain it from the deposit's GET response (pixTransaction.endToEndId) or from the pixChargePaid webhook.

Always store the endToEndId

It is the identifier that links a transaction across deposits, refunds, statements and support tickets. A system that does not persist it cannot refund, cannot reconcile, and cannot answer questions about a payment.

Each refund also needs its own externalId, distinct from the deposit's. It is what distinguishes one partial refund from another on the same transaction, and it is compared exactly as sent — Refund-01 and refund-01 are two different refunds. See Idempotency.

curl --request PUT \
  --url "https://api.sdb.lbpay.com.br/v1/pix/refund/E12345678202608181200abcdef12345" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data '{
    "endToEndId": "E12345678202608181200abcdef12345",
    "externalId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "amount": 3000,
    "description": "Suspected fraud"
  }'

amount is in cents — 3000 refunds R$ 30,00. The response is 202 Accepted with status PROCESSING.

Partial refunds​

A deposit can be refunded in parts, across several operations, up to the original amount.

Two fields on the refund GET govern what is still possible:

FieldMeaning
leftAmountHow much of the original deposit is still refundable
canBeReversedUntilThe deadline after which no refund is accepted

Check both before offering a refund in your interface. Presenting a refund button for a deposit that is past canBeReversedUntil produces a failure the player will read as your system being broken.

Confirming the outcome​

A refund does not settle instantly. Wait for pixRefundSuccess or pixRefundFailed, or poll the GET endpoint — the same rule as everywhere else: do not act on a transitional status. See Contingency polling.