/cashin/pix/refund-partner Create Refund

Background

/cashin/pix/refund-partner is the refund request API for payment orders, provided to partners. The partner can locate the original payment order by the original platform order number or the original merchant order number, and submit the refund amount, refund reason, and other information for this refund.

At least one of the original platform order number origPlatOrderNo and the original merchant order number origMerchantOrderNo must be provided. The refund principal refundAmount excludes the fee, the currency must match the original order's currency, and amounts are in the currency's major unit. The partner must ensure the merchant refund order number is unique within the same merchant scope; it is used for idempotency control of refund requests and for later tracking.

Refund window: a PIX original-route refund must be initiated within 90 calendar days after the original transaction completes; refunds are not allowed after 90 days. This 90-day window applies only to "PIX original-route refunds"; it is not a unified window for all refunds or for MED. After the window, the original transaction can no longer be returned through the PIX refund API; if funds still need to be returned to the customer, use a new payout flow instead. MED disputes follow their own regulatory time limits and processing rules.

Endpoint

Item	Value
Method	POST
Path	/cashin/pix/refund-partner
Content-Type	application/json
Purpose	Initiate a refund for a payment 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 in the format SHA-256=<Base64 digest>.
Authorization	Header	string	-	Yes	ES256 request signature information, where keyId is the partner key version.
subMerchantNo	Body	string	64	Yes	Sub-merchant ID.
origPlatOrderNo	Body	string	64	Either	Original platform order number; provide at least one of this field or origMerchantOrderNo.
origMerchantOrderNo	Body	string	64	Either	Original merchant order number; provide at least one of this field or origPlatOrderNo.
merchantOrderNo	Body	string	64	Yes	Merchant refund order number; must be unique within the same merchant scope.
refundAmount	Body	decimal	25,2	Yes	Principal amount to refund in this request, excluding the fee; must be greater than 0, and the currency must match the original order's currency. Multiple refunds are allowed; the accumulated refund principal must not exceed the original order's principal.
refundReason	Body	string	128	Yes	Refund reason.
refundReasonCategory	Body	string	16	No	Refund reason category.
notifyUrl	Body	string	255	No	URL where the partner receives the refund result notification.

Request Example

Request header example:

POST /cashin/pix/refund-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1790200000
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>"

Request body example:

{
  "subMerchantNo": "SUB00000001",
  "origPlatOrderNo": "BAS202608160000000001",
  "origMerchantOrderNo": "CASHIN202608160001",
  "merchantOrderNo": "REFUND202608160001",
  "refundAmount": 50.00,
  "refundReason": "Refund agreed with the customer",
  "refundReasonCategory": "CUSTOMER_REQUEST",
  "notifyUrl": "https://merchant.example.com/callback/refund"
}

Response Fields

The API uses the standard status, msg, and data response structure. The final refund result is determined by orderStatus, the asynchronous notification, or a later query.

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 response data; may be omitted when the request fails at signature verification or protocol parsing.
data.subMerchantNo	string	64	Yes	Sub-merchant ID, identical to the subMerchantNo in the request.
data.merchantOrderNo	string	64	Yes	Merchant refund order number, echoed from the request.
data.platOrderNo	string	64	Conditional	Platform refund order number; returned after the refund order is created successfully.
data.amount	decimal(25,2)	25,2	Yes	Principal amount requested for refund in this request, excluding the fee; echoes refundAmount from the request.
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.origPlatOrderNo	string	64	Conditional	Original platform order number.
data.origMerchantOrderNo	string	64	Conditional	Original merchant order number.
data.origAmount	decimal	25,2	Conditional	Original merchant order amount.
data.origTotalRefundAmount	decimal(25,2)	25,2	Conditional	Accumulated principal successfully refunded so far for the original cashin order, excluding fees.
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	Conditional	Accumulated fees successfully refunded so far for the original cashin order, excluding the refund principal.
data.e2eId	string	64	No	PIX end-to-end transaction ID.
data.orderStatus	string	16	Yes	Current refund status.
data.refundTime	int	19	No	Refund time, Unix timestamp in seconds.

data.orderStatus Enum

Value	Description	Final state
PENDING	Refund in progress.	No
SUCCESS	Refund succeeded.	Yes
FAILED	Refund failed.	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",
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "amount": 50.00,
    "refundAmount": 50.00,
    "feeRefundAmount": 0.30,
    "origPlatOrderNo": "BAS202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origAmount": 100.00,
    "origTotalRefundAmount": 50.00,
    "origTotalFeeRefundAmount": 0.30,
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025
  }
}

Response Error Codes

• Response Status