/cashin/check Query Payment by Order SN

Background

/cashin/check is the PIX cashin 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, amount, payer information, and PIX 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.

Endpoint

Item	Value
Method	GET
Path	/cashin/check
Content-Type	application/json
Purpose	Query a cashin 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.
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 body digest; for a GET request without a body, computed over empty bytes, in the format SHA-256=<Base64 digest>.
Authorization	Header	string	-	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, the query matches the merchant order number under the current primary merchant.
• With only e2eId, the payment record is located by the bank transaction reference, and then the associated order under the current primary merchant is queried.
• When both are provided, merchantOrderNo takes precedence: e2eId is not checked for a match, and there is no fallback to e2eId if the merchant order number lookup fails. Pass only one query criterion at a time.
• 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 /cashin/check?e2eId=E1234567820260816000000000000001 HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
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, use the same authentication headers and recompute the signature:

GET /cashin/check?merchantOrderNo=CASHIN202608160001 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 query response does not mean the payment succeeded; the actual transaction result is determined by orderStatus.

Limitations of the current query result

In the current version, in some scenarios where the order is not found, the payment record is missing, or the query is abnormal, the API may still return a success response code while the order fields are empty or incomplete. Always check data.merchantOrderNo, data.platOrderNo, and data.orderStatus together; when the order number or status is empty, do not conclude that the order exists or that the payment succeeded, and do not overwrite locally stored payment results with empty values or default amounts.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Message corresponding to status
data	object	N/A	No	cashin order query result; may be omitted when the request fails at signature verification or protocol parsing.
data.subMerchantNo	string	64	Conditional	Sub-merchant ID that owns this cashin order; returned when the order is found.
data.attach	string	128	Yes	attach value the partner submitted when placing the original payment order; returned as-is if it was submitted, empty otherwise.
data.merchantOrderNo	string	64	Conditional	Merchant order number, corresponding to the merchantOrderNo used at order creation.
data.platOrderNo	string	64	Conditional	Platform order number.
data.e2eId	string	64	Conditional	PIX end-to-end transaction ID, corresponding to the bank-side payment reference.
data.orderStatus	string	16	Yes	Current status of the cashin order.
data.amount	decimal(25,2)	25,2	Yes	Order amount / amount due.
data.payAmount	decimal(25,2)	25,2	Yes	Amount actually paid.
data.fee	decimal(25,2)	25,2	Yes	Fee; BRL by default in Brazil.
data.payerName	string	128	No	Payer's name; usually returned on success.
data.payerTaxNo	string	64	No	Payer's tax ID; CPF has 11 digits and CNPJ has 14 digits; usually returned on success.
data.payTime	int	19	Conditional	Payment time, Unix timestamp in seconds.
data.expireTime	int	19	Conditional	Order expiration 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	Pending payment or processing; keep querying or wait for the asynchronous notification.	No
SUCCESS	Payment received successfully.	Yes
FAILED	Payment failed.	Yes

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUB00000001",
    "attach": "order-source=checkout",
    "merchantOrderNo": "CASHIN202608160001",
    "platOrderNo": "BAS202608160000000001",
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "amount": 100.00,
    "payAmount": 100.00,
    "fee": 0.60,
    "payerName": "Maria Oliveira",
    "payerTaxNo": "12345678901",
    "payTime": 1786887025,
    "expireTime": 1786901100,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}

Response Error Codes

• Response Status