/cashin/check-refund Query Refund Detail

Background

/cashin/check-refund is the cashin refund order query API provided to partners. Using the merchant refund order number merchantOrderNo or the platform refund order number platOrderNo, the partner can query a refund order's current status, refund amount, accumulated refund amount, refunded fees, and the original cashin order information.

At least one of merchantOrderNo and platOrderNo must be provided. If both are provided, they must refer to the same refund order. A successful refund query only means the system has returned the refund order's current information; it does not mean the refund has finally succeeded. The refund result is determined by orderStatus.

Endpoint

Item	Value
Method	GET
Path	/cashin/check-refund
Content-Type	application/json
Purpose	Query a cashin refund 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 refund 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 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	Either	Merchant refund order number; provide at least one of this field or platOrderNo.
platOrderNo	Query	string	64	Either	Platform refund order number; provide at least one of this field 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 Example

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

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Message corresponding to status
data	object	N/A	No	Refund order query result; may be omitted when the request fails at signature verification, protocol parsing, parameter validation, or order lookup.
data.subMerchantNo	string	64	Yes	Sub-merchant ID.
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	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.
data.origTotalRefundAmount	decimal(25,2)	25,2	Yes	Accumulated principal successfully refunded so far for the original cashin order, excluding fees.
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	Yes	Accumulated fees successfully refunded so far for the original cashin order, excluding the refund principal.
data.amount	decimal(25,2)	25,2	Yes	Principal amount requested for refund in this request, excluding the fee.
data.refundAmount	decimal(25,2)	25,2	Yes	Principal amount successfully refunded in this request, excluding the fee; for the fee refunded, see data.feeRefundAmount.
data.feeRefundAmount	decimal(25,2)	25,2	Yes	Fee amount refunded in this request; 0 when no fee is refunded.
data.currency	string	3	Yes	Refund currency, identical to the original order's 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	Message corresponding to dataStatus

orderStatus Enum

Value	Description	Final state
PENDING	Refund in progress; the refund request has been accepted and fund processing is not complete yet — 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. Check dataMsg for the failure reason.	Yes

Response Example

The following example shows a first successful refund on the original order: principal 50.00 and fee 0.30 refunded; accumulated refund principal 50.00; accumulated refunded fees 0.30.

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

Integration Notes

1. The query scope is limited to the primary merchant ID in the X-Merchant-Id request header; subMerchantNo is not required, and refund data of other partners cannot be queried by order number.
2. orderStatus is the only business status field for judging the refund result; the API-level status = 200 must not be treated as refund success.
3. The partner should process amounts with high-precision decimal types and verify the currency, original order amount, refund amount of this request, and accumulated refund amount.
4. The refund query API covers synchronous timeouts, missed notifications, and status reconciliation. The final-state refund notification and proactive queries may arrive at the same time; the partner must apply idempotent processing keyed on the refund order number and status.

Response Error Codes

• Response Status