Receipts
Cash-Out Refund Receipt

Payout refund receipt

In this section, you will learn how to retrieve the receipt (comprovante) for a payout that was sent and then returned by the receiving bank — a devolução.

This is different from the Cash-In Refund Receipt, which covers a charge you received and refunded. Here the money left your account as a payout and came back.

Available Endpoint

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

Supported providers

EFIPAY only.

A payout processed by any other provider returns 400. This is a limitation of the providers themselves, not of the API: StarkBank issues reversal receipts for money coming in (deposits and invoices) but not for a returned transfer, so no such document exists to retrieve.

Get the receipt

Route

GET /v2/withdrawals/refund/receipt

Headers

{
  "Authorization": "YOUR_API_KEY"
}

Query Parameters

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

ParameterTypeRequiredDescription
idintegerYes*Internal ID of the payout that was returned
transaction_idstringYes*Unique identifier of the payout on your platform
refund_idstringYes*Identifier of a specific devolution — see below

* Provide exactly one of id, transaction_id or refund_id

Note that id and transaction_id identify the payout, not the devolution. Normally that is all you need.

refund_id is only required when a single payout was returned more than once, which can happen with partial devolutions. You do not supply this value when creating anything — it is generated when the devolution is received. The 409 response below tells you which ones exist.

Request example by payout ID

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

Request example by transaction_id

curl --location 'https://api.pixtopay.com.br/v2/withdrawals/refund/receipt?transaction_id=12345678911' \
--header 'Authorization: API_KEY'

Response 200 - Success

{
  "type": "payout_refund",
  "provider": "EFIPAY",
  "id": 5512,
  "refund_id": "9c3f2a10-4d7b-4a55-9c1e-1b2f3a4d5e6f",
  "payout": {
    "id": 685,
    "transaction_id": "12345678911"
  },
  "filename": "payout_refund_D6070119020260828152562793789137.pdf",
  "content_type": "application/pdf",
  "pdf": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBl..."
}
FieldTypeDescription
typestringAlways payout_refund for this endpoint
providerstringAlways EFIPAY
idnumberInternal ID of the devolution
refund_idstringIdentifier of this devolution
payout.idnumberInternal ID of the original payout
payout.transaction_idstringYour own identifier for the original payout
filenamestringSuggested file name when saving the PDF
content_typestringAlways application/pdf
pdfstringThe receipt itself, base64-encoded

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 supported or not enabled

{
  "message": "Refund receipts are not supported for provider STARKBANK."
}
{
  "message": "EFIPAY is not enabled for this account."
}

Response 403 - API key not allowed

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

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

Response 404 - Not found

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

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

The payout exists but has never been returned:

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

The refund_id you supplied does not exist, or does not belong to a payout:

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

Response 409 - More than one devolution

A payout can be returned in parts. When the request is ambiguous, the endpoint refuses to guess and lists the devolutions in detail so you can choose:

{
  "message": "This payout has more than one refund. Pass refund_id to choose one.",
  "detail": "9c3f2a10-4d7b-4a55-9c1e-1b2f3a4d5e6f, 4e8b1c93-2f6a-4d10-b3c7-8a9e0d1f2b34"
}

Repeat the request with one of the refund_id values from detail.

Response 409 - Receipt not available yet

The devolution is recorded but the provider has not issued a receipt identifier for it yet:

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

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 payout, not the devolution. id and transaction_id refer to the original payout. Reach for refund_id only when a 409 tells you to.
  • Partial devolutions are possible. A payout is only marked as fully refunded once the entire amount has been returned, so a payout can carry a devolution while still appearing as a completed payout.
  • 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.

Related

Cash-In Refund ReceiptBalance