Query Refund Detail

Query refund detail by merchant refund SN.

Endpoint

GET /cashin/check-refund

Authentication

Merchant Credential. See Authentication.

Background

The merchant queries the current status, refund amount, cumulative refund amount, refunded fees, and original cashin order information of its own refund order by merchant refund order number merchantOrderNo or platform refund order number platOrderNo.

At least one of the two refund order numbers is required; if both are provided, they must refer to the same refund order. A successful query only means the current order information has been returned and does not mean the refund has finally succeeded — the refund result is determined by orderStatus. This API can be used for sync timeouts, missed notifications, or status reconciliation.

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 refund order data between 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	Digest of the request body; when a GET request has no body, it is computed over empty bytes. Format: SHA-256=<Base64Digest>.
Authorization	Header	string	-	Yes	ES256 request signature, where keyId is the merchant key version.
merchantOrderNo	Query	string	64	One of two required	Merchant refund order number; fill in at least one of this or platOrderNo.
platOrderNo	Query	string	64	One of two required	Platform refund order number; fill in at least one of this or merchantOrderNo.

If merchantOrderNo and platOrderNo are both provided but do not refer to the same refund order, the API returns a parameter error and no order data.

Request Examples

GET /cashin/check-refund?merchantOrderNo=REFUND202608160001 HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
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>"

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 API response does not mean the refund succeeded; while the refund is still being processed, the merchant should keep querying or wait for the asynchronous notification of the refund result.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	Refund order query result; may be absent when the request fails at the signature verification, protocol parsing, parameter validation, or order query stage.
data.attach	string	128	Yes	The attach value passed by the merchant when the original cashin order was created; returned as-is if provided at order creation, empty otherwise.
data.merchantOrderNo	string	64	Yes	Merchant refund order number.
data.platOrderNo	string	64	Yes	Platform refund order number.
data.origMerchantOrderNo	string	64	Yes	Original merchant cashin order number.
data.origPlatOrderNo	string	64	Yes	Original platform cashin order number.
data.origAmount	decimal(25,2)	25,2	Yes	Original cashin order amount, in the major currency unit.
data.origTotalRefundAmount	decimal(25,2)	25,2	Yes	Cumulative principal successfully refunded so far on the original cashin order, excluding fees.
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	Yes	Cumulative fee amount successfully refunded so far on the original cashin order, excluding the refunded principal.
data.amount	decimal(25,2)	25,2	Yes	Principal amount requested for this refund, excluding fees.
data.refundAmount	decimal(25,2)	25,2	Yes	Principal amount successfully refunded this time, excluding fees; see data.feeRefundAmount for the fee refunded this time.
data.feeRefundAmount	decimal(25,2)	25,2	Yes	Fee amount refunded this time, in the major currency unit; 0 when no fee is refunded.
data.currency	string	3	Yes	Refund currency, same as the original order currency, for example BRL.
data.e2eId	string	64	No	Pix end-to-end transaction ID; may be empty when the channel has not returned it yet.
data.orderStatus	string	16	Yes	Current status of the refund order.
data.refundTime	int	19	No	Refund 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	Refund being processed; the refund request has been accepted but fund processing is not complete. Keep querying or wait for the asynchronous notification.	No
SUCCESS	Refund succeeded; refund fund processing is complete.	Yes
FAILED	Refund failed; this refund has ended. See dataMsg for the failure reason.	Yes

Response Examples

The following example shows the first successful refund on the original order: principal 50.00 and fee 0.30 refunded, cumulative refunded principal 50.00, and cumulative refunded fee 0.30.

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "attach": "order-source=checkout",
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origPlatOrderNo": "BAS202608160000000001",
    "origAmount": 100,
    "origTotalRefundAmount": 50,
    "origTotalFeeRefundAmount": 0.30,
    "amount": 50,
    "refundAmount": 50,
    "feeRefundAmount": 0.3,
    "currency": "BRL",
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025,
    "dataStatus": 200,
    "dataMsg": "SUCCESS"
  }
}