Skip to main content
PIX refunds are asynchronous and account-scoped[cite: 1]. Creating a refund request initiates background processing rather than delivering an immediate final result[cite: 1].
All standard API responses (including validation and business failures) return HTTP 200 with an outer JSON envelope[cite: 1]. Always branch your business logic on the outer code field, not the HTTP status code[cite: 1].

​
Refund Lifecycle Flow

Follow this 4-step execution model to handle PIX refunds securely:
1

Initiate Refund Request

Call POST /v3/refunds/pix passing the original inbound PIX settlement ID, a unique merchant_order_id, and the decimal-string amount[cite: 1].
2

Pending Processing (Status 1)

A successful creation returns numeric status 1 (PENDING)[cite: 1]. Pagsmile queues the operation for asynchronous rail execution[cite: 1].
3

Poll Refund Status

Poll POST /v3/refunds/status/check to monitor state updates[cite: 1].
Each status check request must include a fresh X-Timestamp and X-Nonce header to pass signature validation[cite: 1].
4

Terminal State Reached

Stop polling when status reaches 2 (COMPLETED) or 3 (FAILED)[cite: 1]. Use POST /v3/refunds/details if you require the full accessible transaction projection[cite: 1].

​
Eligibility Rules

Before issuing a refund, verify that your request satisfies all banking and system constraints[cite: 1]:

Transaction Age

Must be an inbound PIX payment owned by the selected account, issued within the last 90 days[cite: 1].

Amount Limits

Must be positive, have at most two decimal places, and not exceed the remaining refundable balance[cite: 1].

Merchant Order ID Format

The first 6 characters must match a valid YYMMDD UTC date within a ±1-hour boundary of the current UTC day[cite: 1].

Account Ownership

The original inbound transaction must belong to the account executing the refund[cite: 1].

​
Idempotency & Replay Protection

Understanding the distinction between API idempotency and signature security is critical:
  • Merchant Order ID Deduplication: The create endpoint retains the merchant_order_id for 48 hours[cite: 1]. Submitting a duplicate order ID returns business error code 4001013[cite: 1].
  • Signature Replay Protection: Deduplication is independent of request signing[cite: 1]. Every retry or status check request requires a unique X-Nonce and current X-Timestamp[cite: 1].