Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Create a Refund

Initiates an original-route refund for a collection that has already been credited to a merchant account.

This API creates an asynchronous refund request. Use Query Collections or Collection Notification to obtain the final refund result.

Endpoint

POST /remittance/refund/create

Sandbox base URL: https://rem-api-sandbox.pagsmile.com Content-Type: application/json; charset=UTF-8

The request uses the standard Remittance API request envelope. The fields below describe the decrypted biz_data object.

Requirement: M = Mandatory, O = Optional, and C = Conditional. A conditional field is mandatory only when the condition stated in its description applies.

Availability and processing rules

  • The merchant account must be active, and its available balance in the refund currency must be sufficient to cover the refund amount.

  • The refund must be requested within 90 calendar days of the collection creation time.

  • The refund currency is always the same as the original collection currency.

  • A collection supports only one refund request. If a partial refund is requested, the remaining amount cannot be refunded through a subsequent request.

  • The refund amount must not exceed the amount received for the original collection.

  • Pagsmile records the refund reason as CUSTOMER_INITIATED for requests created through this API.

Request body

Decrypted biz_data fields

Field
Type
Requirement
Description

collection_id

long

M

Pagsmile-assigned unique identifier of the original collection. Obtain this value from Query Collections or a Collection Notification.

refund_amount

string

O

Amount to refund, expressed in the original collection currency. Must be greater than zero and must not exceed the amount received for the collection. Before the collection is credited, the full collection amount is always refunded

remark

string

O

Partner-provided description or internal reference for the refund request.

Plaintext biz_data example

This example requests a partial refund. Omit refund_amount to request a full refund.

Request example

Use the partner_id and app_id assigned to your integration. The values above are placeholders.

Response

The data field in the response envelope is AES-encrypted. Decrypt random_key with your RSA private key, then use the resulting AES key to decrypt data. See Security for implementation details.

Encrypted response example

Decrypted data example

Response data fields

Field
Type
Requirement
Description

collection_id

long

M

Pagsmile-assigned unique identifier of the original collection.

refund_transaction_id

Long

O

Pagsmile-assigned unique identifier of the accounting transaction created for the refund.

refund_amount

string

M

Accepted refund amount, expressed in the refund currency. When refund_amount is omitted from the request, this value equals the full amount received for the original collection. Before the collection is credited, the full collection amount is always refunded

refund_currency

string

M

Three-letter ISO 4217 code of the refund currency. This value is the same as the original collection currency.

refund_fee

string

O

Refund fee charged for the request.

created_at

string

M

Date and time when Pagsmile accepted the refund request. Format: yyyy-MM-dd HH:​mm:ss. Timezone: UTC.

refund_status

integer

M

Current status of the refund request. Supported values: 1 — Refunding: the request has been accepted and is being processed. 2 — Refunded: the refund completed successfully. 3 — Refund Failed: the refund was rejected or could not be completed.

remark

string

O

Partner-provided description or internal reference submitted with the refund request.

A successful API response confirms that the refund request was accepted. It does not confirm that the refund has completed. Treat refund_status = 2 as the successful final state and refund_status = 3 as the failed final state.

Related APIs

Last updated