Query PIX Out

Query PIX payout status by merchant order number.

Endpoint

GET /cashout/check

Authentication

Merchant Credential. See Authentication.

Background

Merchants can query the current status, transaction amount, fee, payer and payee information, and bank transaction details of their own cashout orders by merchant order number merchantOrderNo or Pix end-to-end transaction ID e2eId (bank transaction reference number).

A successful query means the system has returned the order's current information; it does not mean the cashout order ultimately succeeded. The transaction result is determined by orderStatus.

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID, read from the request header; used to isolate order data across merchants.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds, used for request freshness validation.
X-Nonce	Header	string	64	Yes	Random string for request anti-replay protection.
Digest	Header	string	52	Yes	Request digest. Format: SHA-256=<Base64Digest>. When a GET request has no body, it is computed over an empty byte string.
Authorization	Header	string	Variable	Yes	ES256 request signature, where keyId is the merchant key version.
merchantOrderNo	Query	string	64	Conditional	Merchant order number; provide at least one of this or e2eId.
e2eId	Query	string	64	Conditional	Pix end-to-end transaction ID; provide at least one of this or merchantOrderNo.

Query Rules

• If neither field is provided or both are blank, the request is rejected; each provided field must not exceed 64 bytes.
• If only merchantOrderNo or only e2eId is passed, the order under the current merchant is queried by the corresponding number.
• If both are passed, the two numbers must match the same order; when they do not match, a record-not-found result is returned, and the query does not fall back to using only one of the numbers.
• If the same query condition matches multiple E2E orders, a query error is returned; an arbitrary order is never picked and returned.
• merchantOrderNo must match the merchant order number used when the order was created. platOrderNo is returned only in the response and is not supported as a query condition for this API.
• If the bank transaction reference number is not yet available, query with merchantOrderNo.

Request Examples

GET /cashout/check?e2eId=E1234567820260816000000000000001 HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786845600
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<Base64Digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

To query by merchant order number, or when providing both numbers, use the same authentication headers and recompute the signature:

GET /cashout/check?merchantOrderNo=CASHOUT202608160001 HTTP/1.1

GET /cashout/check?merchantOrderNo=CASHOUT202608160001&e2eId=E1234567820260816000000000000001 HTTP/1.1

Response Fields

Business status: dataStatus is an integer; dataStatus = 200 indicates the business succeeded, in which case dataMsg = "SUCCESS". Any value other than 200 indicates a business error; see dataMsg for the reason.

The API uses a unified status, msg, data response structure. A successful query means the system has returned the order's current information; it does not mean the cashout order ultimately succeeded. The transaction result is determined by orderStatus.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	cashout order query result; may be absent when the request fails at the signature verification, protocol parsing, or order query stage.
data.attach	string	128	Yes	The attach value passed by the merchant when the original cashout order was created; returned as-is if provided at order creation, empty otherwise.
data.merchantOrderNo	string	64	Yes	Merchant order number, corresponding to the merchantOrderNo used at order creation.
data.platOrderNo	string	64	Yes	Platform order number.
data.orderStatus	string	16	Yes	Current status of the cashout order.
data.e2eId	string	64	No	Pix end-to-end transaction ID.
data.amount	decimal	25,2	Yes	cashout order amount.
data.receivedAmount	decimal	25,2	Yes	Amount actually credited to the payee; may be 0 before the transaction completes.
data.fee	decimal	25,2	Yes	cashout fee.
data.fromIspb	string	16	Yes	ISPB code of the paying bank or payment institution.
data.fromIspbName	string	512	Yes	Name of the paying bank or payment institution.
data.fromCnpj	string	64	Yes	Payer CNPJ.
data.fromName	string	128	Yes	Payer name.
data.toPix	string	64	Yes	Payee Pix account or Pix Key.
data.toIspb	string	16	Yes	ISPB code of the payee's bank or payment institution.
data.toIspbName	string	512	Yes	Name of the payee's bank or payment institution.
data.toName	string	128	Yes	Payee name.
data.toCpfCnpj	string	64	Yes	Payee CPF or CNPJ.
data.payTime	int	19	Yes	Payment time or order completion time, Unix timestamp in seconds.
data.dataStatus	int	-	Yes	Response code
data.dataMsg	string	128	Yes	Corresponds to dataStatus

orderStatus Enum

Enum Value	Description	Final State
PENDING	Processing; the cashout order is still being executed. Keep querying or wait for the asynchronous notification.	No
SUCCESS	cashout succeeded; the payee has been credited.	Yes
FAILED	cashout failed; see dataMsg for the failure reason.	Yes

Response Examples

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "attach": "merchant-data-001",
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "orderStatus": "SUCCESS",
    "e2eId": "E1234567820260816000000000000001",
    "amount": 100.25,
    "receivedAmount": 99.75,
    "fee": 0.50,
    "fromIspb": "87654321",
    "fromIspbName": "Example Payment Institution",
    "fromCnpj": "12345678000195",
    "fromName": "Example Merchant Ltda.",
    "toPix": "maria.oliveira@example.com",
    "toIspb": "12345678",
    "toIspbName": "Example Receiving Institution",
    "toName": "Maria Oliveira",
    "toCpfCnpj": "12345678901",
    "payTime": 1786887025,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}