Refund receipt

In this section, you will learn how to retrieve the receipt (comprovante) for the refund of a charge you received.

The receipt is fetched live from the bank that processed the refund, using your own banking credentials, and is returned as a base64-encoded PDF inside a JSON response.

Available Endpoint

• Sandbox: https://sandbox.pixtopay.com.br/v2/transactions/refund/receipt
• Production: https://api.pixtopay.com.br/v2/transactions/refund/receipt

Supported providers

Refund receipts are available for charges processed by StarkBank and EFIPAY. A charge received through any other provider returns 400.

Get the receipt

Route

GET /v2/transactions/refund/receipt

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

Important: Use only one of the parameters below, never more than one.

* Provide exactly one of id, transaction_id or refund_id

Note that id and transaction_id identify the original charge, not the refund. This is deliberate: refunds are sometimes initiated by PixToPay rather than by you, in which case you never receive a refund_id and the charge is the only identifier you hold.

Request example by charge ID

curl --location 'https://api.pixtopay.com.br/v2/transactions/refund/receipt?id=918273' \
--header 'Authorization: API_KEY'

Request example by refund_id

curl --location 'https://api.pixtopay.com.br/v2/transactions/refund/receipt?refund_id=my-refund-001' \
--header 'Authorization: API_KEY'

Response 200 - Success

{
  "type": "refund",
  "provider": "EFIPAY",
  "id": 4471,
  "refund_id": "my-refund-001",
  "transaction": {
    "id": 918273,
    "transaction_id": "order-2024-8891"
  },
  "filename": "refund_my-refund-001.pdf",
  "content_type": "application/pdf",
  "pdf": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBl..."
}

Decode pdf from base64 to obtain the file — see the examples on the Cash-Out Receipt page, which apply unchanged here.

Response 400 - Invalid parameters

{
  "type": "ValidationError",
  "message": "please provide only one of refund_id, id, transaction_id"
}

When none of them is sent:

{
  "type": "ValidationError",
  "message": "one of refund_id, id, transaction_id is required!"
}

Response 400 - Provider not enabled or not supported

{
  "message": "Refund receipts are not supported for provider GENIAL."
}

{
  "message": "EFIPAY is not enabled for this account."
}

Response 400 - This refund belongs to a payout

A payout that was returned by the receiving bank is a different kind of refund, documented separately. Passing its refund_id here returns:

{
  "message": "This refund belongs to a payout. Use GET /v2/withdrawals/refund/receipt instead."
}

See Cash-Out Refund Receipt.

Response 403 - API key not allowed

Returned when a read-only API key does not have access to transactions.

{
  "message": "Access to transactions is forbidden for this API key!"
}

Response 404 - Not found

The charge does not exist, or does not belong to your account:

{
  "message": "Transaction not found!"
}

The charge exists but has never been refunded:

{
  "message": "No refund found for this transaction!"
}

Response 409 - Receipt not available yet

The refund exists but the bank has not issued a receipt for it yet:

{
  "message": "Receipt not available yet: this refund has no provider identifier."
}

Response 409 - More than one refund

A charge can be refunded more than once. When the request is ambiguous, the endpoint refuses to guess and lists the available refunds so you can choose:

{
  "message": "This transaction has more than one refund. Pass refund_id to choose one.",
  "detail": "my-refund-001, my-refund-002"
}

Repeat the request with the refund_id you want.

Response 502 - Provider refused the request

{
  "message": "Failed to retrieve the refund receipt from EFIPAY.",
  "detail": "Request failed with status code 403"
}

The detail field carries the provider's own message and is intended for troubleshooting.

Important Notes

• Identify the charge, not the refund: id and transaction_id refer to the original charge. This differs from Search Charges, where the same parameter names also refer to the charge, and from the refund object itself, which is addressed by refund_id.
• Live data: the receipt is fetched from the bank on every request, using the banking credentials configured for your account. Nothing is cached on our side.
• Partial refunds: a charge may carry several refunds. Pass refund_id to be explicit whenever more than one exists.
• Errors are specific: 409 means "not ready yet, or tell us which refund you mean", while 502 means the bank refused the request. Use the status to decide whether to retry.

Related

• Refund Charge — how to create a refund
• Cash-Out Receipt — receipts for payouts you send
• Cash-Out Refund Receipt — receipts for payouts returned by the receiving bank