...IntegrationSelf Hosted PageInitiate Checkout

Initiate Checkout (One-Time Payment)

This API endpoint empowers acquirer to seamlessly facilitate one-time payments through DuitNow Online Banking/Wallets transactions, ensuring user authentication within their respective banks for debiting requests. Acquirer can effortlessly integrate directly using the specified specifications and process flow, bypassing PayNet's hosted page. This option grants merchants the flexibility to autonomously manage their payment journey, offering a streamlined and tailored experience.

Process Flow

Step	Sender	Receiver	Process
1	Payer	Acquirer	Payer initiates a payment via DuitNow Pay.
2	Acquirer	API Gateway	Acquirer requests API Gateway to pull the available banks and payment methods.
3	API Gateway	Acquirer	The bank list and available payment methods will be parsing back to acquirer for user to select their preferred payment method.
4	Payer	DuitNow Pay	Payer will select their preferred Online Banking / Wallet (OBW) method and proceed to confirm checkout.
5	Acquirer	API Gateway	Acquirer will initiate the checkout API to initiate the payment request. The endToEndIdSignature in the response will be used to construct the browser redirection (Refer here for the guidance).
6	API Gateway	Acquirer	API Gateway will be sending acknowledgement to acquirer with the redirect for the respective bank for authorization.
7	API Gateway	Acquirer	API Gateway will be sending the mapping of checkout details back to acquirer.
8	Acquirer	API Gateway	Acquirer shall provide an acknowledgement back to API Gateway.
9	Payer	Issuing Bank	Payer will login with the bank credentials to make payments.
10	Issuing Bank	Payer	Bank will provide the checkout details to the payer.
11	Payer	Issuing Bank	For Redirect Retail flow, payer will authorize the transaction upon verifying the transaction details. For Redirect Corporate flow, payer will submit transaction request for authorizer approval.
12	API Gateway	Acquirer	Payment status will be parsed to acquirer as part of the webhook.
13	Acquirer	API Gateway	Acquirer shall provide an acknowledgement back to API Gateway.
14	Issuing Bank	Acquirer	Issuing Bank will redirect back to acquirer from the redirect URL that configured during the onboarding process.
15	Payer	Issuing Bank	Payer as authorizer will login into the corporate bank.
16	Payer	Issuing Bank	Payer will authorize the transaction upon verifying the transaction details.
17	API Gateway	Acquirer	Payment status will be parsed to acquirer as part of the webhook.
18	Acquirer	API Gateway	Acquirer shall provide an acknowledgement back to API Gateway.

Request

POST /v1/bw/checkout

checkoutId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent.
transactionFlow	String	Max length: 2		Optional
This decides which list of banks shall be listed, retail or corporate bank. 01 - Redirect Retail Flow 02 - Redirect Corporate Flow ** It will default to 01 if this field has not parsed. ** Checker shall approve the payment within 5 days (starting from the time when it initiated). ** This field is only applicable when the dataType=01.
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet. It can obtain from the bank list API.
sourceOfFunds	ArrayList	Max length: N/A		Required
Acceptable source of funds by Merchant. 01 – CASA 02 – Credit Card (not supported at the moment) 03 – eWallet (not supported at the moment)
amount	String	Max length: 18		Required
Amount in MYR for the transaction in two decimals. eg: 10.00
Merchant Object
productId	String	Max length: 35		Required
Product identification assigned by PayNet during merchant registration in Developer Portal.
End Merchant Object
merchantName	String	Max length: 100		Optional
Name of merchant. To be shown to the user in the checkout WebView page.
merchantReferenceId	String	Max length: 140		Required
Payment reference to the recipient. To be shown to the user during authorization with their issuer.
Customer Object
name	String	Max length: 140		Required
Name of payer by initiating acquirer.
identityValidation	String	Max length: 2		Required
Indicates if Debiting Bank should perform validation on payer information. 00 - No Validation 01 - Debtor Name Check 02 - Debtor Identification Check (NRIC, Passport or etc) 03 - Debtor Name and Identification Check
identificationType	String	Max length: 2		Optional
When this field is sent, Debiting Bank to ensure the identification field match with their internal record before allowing to debit from the account. 01 - New IC Number The Identification Type used is IC Number. 02 - Army Number The Identification Type used is Army Number. 03 - Passport Number The Identification Type used is Passport Number. 04 - Registration Number The Identification Type used is Registration Number. 05 - Mobile Number The Identification Type used is Mobile Phone.
identification	String	Max length: 140		Conditional
This field is mandatory if identificationType above present. The value will based on the identificationType selected above. New IC Number - without hyphens. Eg: 840312145594 Army Number - only numbers. Eg: 20248 Passport Number - Include country of issuance. Eg: E394029340VSGP Registration Number - alphanumeric. Eg: JM1234567-Z Mobile Number - include country or area code with full mobile number. Eg: +60103772812
End Customer Object

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "transactionFlow": "01",
    "issuer": "Affin Bank",
    "sourceOfFunds": [
        "01"
    ],
    "amount": "10.00",
    "merchant": {
        "productId": "P00000201"
    },
    "merchantName": "Shop Name Sdn Bhd.",
    "merchantReferenceId": "ref12345678",
    "customer": {
        "name": "Walter Mitty",
        "identificationType": "05",
        "identification": "+60123456788",
        "identityValidation": "00"
    }
}

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.
endToEndIdSignature	String	Max length: 1024		Required
End to end id sign using RPP private key.
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet.
paymentMethod	String	Max length: 35		Required
Payer selected payment method: 01 - DuitNow Online Banking / Wallets
End Data Object
message	String	Max length: 1024		Required
Refer to reason codes in the appendix.

Sample Response:

{
    "data": {
        "endToEndId": "20240208M0037091861OBW00000221",
        "endToEndIdSignature": "pGBSF/cSxEx4lsr2TdOblQzwwLsaIXKi1scYGgRUCeryKMapy4yAm+IY93yCEs0qdilyQ7A4zcQSqqpqq+CWnIBcII5e7wed4O30/rwWaWZcYSS0bAs89cy/W0CtBmsq+HV85oxN5hMmCIn5JCsXvcAw4urn1d3kuBOroqMkS2vzs6ud7GiQeqzhf1Smqj7z/Y8/TIljknoC7l043TOw96E63uNZh5aEuiySYogvYON/EUTMbAm9Vpqxf9HzQfCDFOQ9rwwlEaWildZW+YjS/SzKlS+qGcC6yirzeLeqfy1TaDC1b8S8R2diZYMRquE0Nbbo1vV6JlSoUXOmbBbVPA==",
        "issuer": "Affin Bank",
        "paymentMethod": "01"
    },
    "message": "U000"
}    

Webhook: Update Checkout Details

This webhook maps the endToEndId to the checkoutId. This allows the acquirer to relate the endToEndId in the redirect URL back to the checkoutId when the issuer redirects with only the endToEndId in Step 14.

Request

Webhook endpoint will be provided by acquirer during onboarding.

checkoutId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent.
rtpEndToEndId	String	Max length: 35		Required
Unique message identification from RPP. This can be used to reconcile with RPP BackOffice or Reports.
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet.
paymentMethod	String	Max length: 35		Required
Payer selected payment method: 01 - DuitNow Online Banking / Wallets

Sample Request:

{​
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",​
    "rtpEndToEndId": "20240325M0000201861OBW00618197",​​
    "issuer": "Affin Bank",
    "paymentMethod": "01"
}​

Webhook: Update Payment Status

This webhook is to update the acquirer on the status and details of a successful transaction. It will only trigger if the transfer is successful for checkout via WebView.

For corporate flows that have triggered (transactionFlow = “02”), please perform an Enquire Payment Status on the 5th day to confirm the final status of the transaction.

info

If acquirer does not receive this webhook, kindly perform Retrieve Payment Status API to enquire the status of transaction.

Request

Webhook endpoint will be provided by acquirer during onboarding.

checkoutId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent.
endToEndId	String	Max length: 35		Required
Unique message identification from RPP. This can be used to reconcile with RPP BackOffice or Reports.
PaymentStatus Object
payerName	String	Max length: 100		Required
Name of payer from the debiting bank.
code	String	Max length: 4		Required
Please refer to appendix for the list of status codes.
substate	String	Max length: 35		Required
substate: RECEIVED – Pending CLEARED – Successful Credit REJECTED – Rejection from Debiting Agent PENDAUTH – Pending authorization from Debiting Agent
message	String	Max length: 1024		Required
Please refer to appendix for the list of reason codes.
End PaymentStatus Object
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet.
paymentMethod	String	Max length: 35		Required
Payer selected payment method: 01 - DuitNow Online Banking / Wallets

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "endToEndId": "20240119M0000201861OBW00000004",
    "paymentStatus": {
        "payerName": "DMMMYKL3 Test",
        "code": "ACTC",
        "substate": "PENDAUTH",
        "message": "U002"
    },
    "issuer": "Affin Bank",
    "paymentMethod": "01"
}

Once the authorizer approved the payment request and the corporate issuing bank. It will then responded with another webhook of “Update Payment Status” and the substate shall be responding as “CLEARED”.

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "endToEndId": "20240119M0000201861OBW00000004",
    "paymentStatus": {
        "payerName": "DMMMYKL3 Test",
        "code": "ACTC",
        "substate": "CLEARED",
        "message": "U002"
    },
    "issuer": "Affin Bank",
    "paymentMethod": "01"
}

Webhook: Update Payment Status (rejected)

This webhook is to update the acquirer if there is rejection during the authorization of a transaction. If the transaction successful, this webhook will not be triggered.

Request

Webhook endpoint will be provided by acquirer during onboarding.

checkoutId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent.
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
Please refer to appendix for the list of status codes.
substate	String	Max length: 35		Required
substate: RECEIVED – Pending CLEARED – Successful Credit REJECTED – Rejection from Debiting Agent PENDAUTH – Pending authorization from Debiting Agent
message	String	Max length: 1024		Required
Please refer to appendix for the list of reason codes.
End PaymentStatus Object
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet.
paymentMethod	String	Max length: 35		Required
Payer selected payment method: 01 - DuitNow Online Banking / Wallets

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "endToEndId": "20240325M0000201861OBW00618197",
    "paymentStatus": {
        "code": "ACSP",
        "substate": "REJECTED",
        "message": "U000"
    },
    "issuer": "Affin Bank",
    "paymentMethod": "01"
}

Guidance to Perform Payment Enquiry

Scenario example:
If there is missing update checkout details from the webhook, but the debiting agent is redirected and receives the update payment status from webhook, no further enquiry is needed, and the payment is confirmed as successful.

Please refer the table below to understand which suitable action that you may need to perform:

Webhook: Update Checkout Details	Debiting Agent Redirected	Webhook: Update Payment Status	Action
❌	✅	✅	No enquiry required, payment successful.
✅	✅	❌	Perform Enquire Payment Status.
❌	✅	❌	Perform Enquire Checkout Details. If it successful responded, please proceed to perform Enquire Payment Status.
❌	❌	❌