/cashout/check Query PIX Out

Background

/cashout/check is the PIX payout order query API provided to partners. Using the merchant order number merchantOrderNo or the PIX end-to-end transaction ID e2eId (bank transaction reference), the partner can query an order's current status, transaction amount, fee, payer/payee information, and bank transaction details.

At least one of merchantOrderNo and e2eId must be provided. The query scope is limited to the primary merchant ID in the X-Merchant-Id request header; subMerchantNo is not required. The order amount, amount actually credited, and fee are all in BRL.

Endpoint

Item	Value
Method	GET
Path	/cashout/check
Content-Type	application/json
Purpose	Query a payout order

Access Requirements

• Common specifications

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Primary merchant ID, read from the request header; isolates the order data of different partners.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds, used to validate request freshness.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	Request digest in the format SHA-256=<Base64 digest>; for a GET request without a body, computed over an empty byte string.
Authorization	Header	string	Variable	Yes	ES256 request signature information, where keyId is the partner key version.
merchantOrderNo	Query	string	64	Conditional	Merchant order number; provide at least one of this field or e2eId.
e2eId	Query	string	64	Conditional	PIX end-to-end transaction ID; provide at least one of this field 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.
• With only merchantOrderNo or only e2eId, the order is queried under the current primary merchant by the corresponding number.
• When both are provided, the two numbers must match the same order; on mismatch, a record-not-found result is returned, with no fallback to querying by only one of them.
• If the same query criterion matches multiple E2E orders, a query error is returned; an arbitrary order is never picked and returned.
• merchantOrderNo must be identical to the merchant order number used when placing the order. platOrderNo is returned only in the response and is not supported as a query criterion for this API.
• If the bank transaction reference is not yet available, query with merchantOrderNo.

Request Example

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=<Base64 digest>
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 means the business call succeeded, in which case dataMsg = "SUCCESS". Any value other than 200 indicates a business error; see dataMsg for the reason.

The API uses the standard status, msg, and data response structure. A successful query only means the system has returned the order's current information; it does not mean the payout order finally succeeded. The transaction result is determined by orderStatus.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Message corresponding to status
data	object	N/A	No	Payout order query result; may be omitted when the request fails at signature verification, protocol parsing, or order lookup.
data.subMerchantNo	string	64	Yes	Sub-merchant ID that owns this payout order.
data.attach	string	128	Yes	attach value the partner submitted when placing the original payout order; returned as-is if it was submitted, 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 payout order.
data.e2eId	string	64	No	PIX end-to-end transaction ID.
data.amount	decimal	25,2	Yes	Payout 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	Payout 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	CNPJ of the sending party.
data.fromName	string	128	Yes	Name of the sending party.
data.toPix	string	64	Yes	Payee's 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's name.
data.toCpfCnpj	string	64	Yes	Payee's 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	Message corresponding to dataStatus

orderStatus Enum

Value	Description	Final state
PENDING	Processing; the payout order is still being executed — keep querying or wait for the asynchronous notification.	No
SUCCESS	Payout succeeded; the payee has been credited.	Yes
FAILED	Payout failed; check dataMsg for the failure reason.	Yes

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUBMERCHANT0001",
    "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"
  }
}

Response Error Codes

• Response Status