Create Refund

Create a refund for a PIX cashin payment.

Endpoint

POST /cashin/pix/refund

Authentication

Merchant Credential. See Authentication.

Background

The merchant locates its own cashin order by the original platform order number origPlatOrderNo or the original merchant order number origMerchantOrderNo, and submits the refund amount, refund reason, and other information. At least one of the two original order numbers is required.

The currency of the refund amount refundAmount must match the original order currency, and amounts are in the major currency unit. The merchant must ensure the merchant refund order number is unique within the same merchant, for idempotency control of refund requests and subsequent tracking; the final refund result is determined by orderStatus, the asynchronous notification, or a subsequent query.

Refund time limit: 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 limit applies only to "Pix original-route refunds" and is not a unified limit for all refunds or for MED. After this deadline, the original transaction can no longer be refunded through the Pix refund API; if funds still need to be returned to the customer, they should be handled through a new payout. MED disputes are subject to separate regulatory time limits and handling rules.

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID, read from the request header.
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. Format: SHA-256=<Base64Digest>.
Authorization	Header	string	-	Yes	ES256 request signature, where keyId is the merchant key version.
origPlatOrderNo	Body	string	64	One of two required	Original platform order number; fill in at least one of this or origMerchantOrderNo.
origMerchantOrderNo	Body	string	64	One of two required	Original merchant order number; fill in at least one of this or origPlatOrderNo.
merchantOrderNo	Body	string	64	Yes	Merchant refund order number; must be unique within the same merchant.
refundAmount	Body	decimal	25,2	Yes	Principal amount requested for this refund, excluding fees; must be greater than 0, and its currency must match the original order currency. Multiple refunds are allowed; the cumulative refunded principal must not exceed the original order principal.
refundReason	Body	string	128	Yes	Refund reason.
refundReasonCategory	Body	string	16	No	Refund reason category.
notifyUrl	Body	string	255	No	URL where the merchant receives refund result notifications.

Request Examples

Request header example:

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

Request body example:

{
  "origPlatOrderNo": "BAS202608160000000001",
  "origMerchantOrderNo": "CASHIN202608160001",
  "merchantOrderNo": "REFUND202608160001",
  "refundAmount": 50,
  "refundReason": "Refund agreed between merchant and customer",
  "refundReasonCategory": "CUSTOMER_REQUEST",
  "notifyUrl": "https://merchant.example.com/callback/refund"
}

Response Fields

The API uses a unified status, msg, data response structure. The final refund result should be determined by orderStatus, the asynchronous notification, or a subsequent query.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	Refund response data; may be absent when the request fails at the signature verification or protocol parsing stage.
data.merchantOrderNo	string	64	Yes	Merchant refund order number, echoed back 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 this refund, excluding fees; echoes refundAmount from the request.
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; 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	Cumulative principal successfully refunded so far on the original cashin order, excluding fees.
data.origTotalFeeRefundAmount	decimal(25,2)	25,2	Conditional	Cumulative fee amount successfully refunded so far on the original cashin order, excluding the refunded principal.
data.e2eId	string	64	No	Pix end-to-end transaction ID.
data.orderStatus	string	16	Yes	Current status of the refund.
data.refundTime	int	19	No	Refund time, Unix timestamp in seconds.

data.orderStatus Enum

Enum Value	Description	Final State
PENDING	Refund being processed.	No
SUCCESS	Refund succeeded.	Yes
FAILED	Refund failed.	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": {
    "merchantOrderNo": "REFUND202608160001",
    "platOrderNo": "RFD202608160000000001",
    "amount": 50,
    "refundAmount": 50,
    "origPlatOrderNo": "BAS202608160000000001",
    "origMerchantOrderNo": "CASHIN202608160001",
    "origAmount": 100,
    "origTotalRefundAmount": 50,
    "origTotalFeeRefundAmount": 0.30,
    "e2eId": "E1234567820260816000000000000001",
    "orderStatus": "SUCCESS",
    "refundTime": 1786887025,
    "feeRefundAmount": 0.3
  }
}