...DuitNow PayIntegrationInitiate Refund

We've Launched a New Documentation Website (Beta Launch)

The documentation for DuitNow is now available on our newly launched documentation platform. This is an initial beta rollout of our new documentation site, designed to become the long-term home for all documentation moving forward.

You'll find the familiar content you're used to—now hosted on a new platform that will progressively receive updates and enhancements.

We encourage you to start accessing DuitNow materials there to explore the new experience and ensure you're viewing the latest documentation updates. If you have any feedback, please reach out to us.

Visit the New Documentation Website

Initiate Payment Refund

Use this to process refunds for payments made via one-time payment or AutoDebit. Both successful and failed refund attempts will trigger a notification through a webhook.

info

Refunds are available for up to 90 days from the date the transaction was captured.

Process Flow

Step	Sender	Receiver	Process
1	Acquirer	API Gateway	Initiate a refund request to API Gateway.
2	API Gateway	Acquirer	API Gateway will respond with REFUND_PENDING while processing the request.
3	API Gateway	Acquirer	The final refund request will be parsed to Acquirer via webhook.

Request

POST /v1/bw/refund

refundId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a refund request.
checkoutId	String	Max length: 36		Required
The similar checkoutId parsed during the first payment initiated.
paymentMethod	String	Max length: 2		Required
The paymentMethod selected during the first payment initiated.
amount	String	Max length: 18		Required
The refund amount must be specified with two decimal places (e.g., 10.00).
merchantReferenceId	String	Max length: 140		Required
Refund reference to the recipient. To be shown to the user for the details of the refund.

Sample Request:

{
    "refundId": "dd66946f-5834-49a1-9d51-89ccfbd77909",
    "checkoutId": "b4e6c575-5393-4a1e-a231-269e9a3f8af3",
    "paymentMethod": "01",
    "amount": "10.00",
    "merchantReferenceId": "ref20240925T132501"
}

Response

Data Object
endToEndId	String	Max length: 35		Required
Unique message identification from RPP. This can be used to reconcile with RPP BackOffice or Reports.
refundStatus	String	Max length: 35		Required
The status will always be REFUND_PENDING while it’s processing.
End Data Object
message	String	Max length: 1024		Required
Please refer to the list of reason codes in the appendix.

Sample Response:

{
    "data": {
        "endToEndId": "20240927M0000201861OBW00000001",
        "refundStatus": "REFUND_PENDING"
    },
    "message": "OK"
}

Webhook : Update Refund Status

This webhook will notify you with the final status of the refund once the processing is complete.

refundId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a refund request.
checkoutId	String	Max length: 36		Required
The similar checkoutId parsed during the first payment initiated.
endToEndId	String	Max length: 35		Required
Unique message identification from RPP. This can be used to reconcile with RPP BackOffice or Reports.
paymentStatus Object
code	String	Max length: 4		Required
Plese refer to the list of status codes in the appendix.
substate	String	Max length: 35		Required
The final refund status once it has processed. The potential substates are as below: REFUND_PENDING - Refund is in progress. REFUND_ACCEPTED - Refund sent to issuing bank for processing. REFUND_REJECTED - Refund unable to process, refer to message field for the reasons. REFUND_EXCEPTION – An unexpected error occurred during the refund process. Please try again and inform PayNet if the problem persists.
message	String	Max length: 1024		Required
Please refer to the list of reason codes in the appendix.
End paymentStatus Object
issuer	String	Max length: 100		Required
Name of payer’s issuing bank.
paymentMethod	String	Max length: 2		Required
The paymentMethod selected during the first payment initiated.
amount	String	Max length: 18		Required
The amount requested for the refund.

Sample Request:

{
    "refundId": "f36b4c31-44b2-40f2-820a-7fbd081cae9b",
    "checkoutId": "b4e6c575-5393-4a1e-a231-269e9a3f8af3",
    "endToEndId": "20240927M0000201861OBW00000001",
    "paymentStatus": {
        "code": "ACTC",
        "substate": "REFUND_ACCEPTED",
        "message": "U002"
    },
    "issuer": "Ambank",
    "paymentMethod": "01",
    "amount": "10.00"
}