Initiate Payment Intent (Save Payment Method - DuitNow Consent)
Acquirer may also reuse the same initiate payment intent endpoint by parsing dataType=02 to save payment method via the DuitNow Consent. When user authorizing DuitNow Consent, they are essentially granting permission for the specified transactions to occur in a regular or on demand basis.
Process Flow
Step | Sender | Receiver | Process |
---|---|---|---|
1 | Payer | Acquirer | Payer initiates to save payment method. |
2 | Acquirer | API Gateway | Acquirer triggers save payment method request by parsing required information into API Gateway. For save payment method, dataType shall be passed with the value of “02”. |
3 | API Gateway | Acquirer | API Gateway validated the information and response the redirectUrl with the sessionId back to acquirer with the required information to redirect into PayNet save payment method page. |
4 | Acquirer | DuitNow Pay | Acquirer opens the redirectUrl to load PayNet save payment method page. |
5 | DuitNow Pay | API Gateway | DuitNow Pay request API Gateway to pull the available banks and payment methods. |
6 | API Gateway | DuitNow Pay | The bank list and available payment methods will be parsing back to DuitNow Pay for user to select their preferred payment method. |
7 | Payer | DuitNow Pay | Payer will select their preferred Online Banking / Wallet (OBW) method to save. |
8 | DuitNow Pay | API Gateway | DuitNow Pay will trigger internal consent API which initiating RPP consent request. |
9 | API Gateway | DuitNow Pay | API Gateway will be sending acknowledgement to DuitNow Pay with the redirect for the respective bank for authorization. |
10 | API Gateway | Acquirer | API Gateway will be sending the mapping of checkout details back to acquirer. |
11 | Acquirer | API Gateway | Acquirer shall provide an acknowledgement back to API Gateway. |
12 | Payer | Issuing Bank | Payer will login with the bank credentials to authorize consent. |
13 | Issuing Bank | Payer | Bank will provide the consent details to the payer. |
14 | Payer | Issuing Bank | Payer will authorize the consent upon verifying the consent details. |
15 | API Gateway | Acquirer | Consent details will be parsed to acquirer as part of the webhook. |
16 | Acquirer | API Gateway | Acquirer shall provide an acknowledgement back to API Gateway. |
17 | Issuing Bank | Acquirer | Issuing Bank will redirect back to acquirer from the redirect URL that configured during the onboarding process. |
Send the payment intent request
POST /v1/payment/intent
Request
dataType | String | Max length: 2 | Required | |||
Service that a user would like to initiate: 01 - Payment (redirect to checkout WebView) 02 - Save payment method (redirect to save payment method WebView) **Use 02 for for the intention of saving payment method via DuitNow Consent. | ||||||
checkoutId | String | Max length: 36 | Required | |||
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent. | ||||||
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) | ||||||
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. | ||||||
Merchant Object | ||||||
productId | String | Max length: 35 | Required | |||
Product identification assigned by PayNet during merchant registration in Developer Portal. | ||||||
End Merchant Object | ||||||
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 | ||||||
Consent Object (below can leave empty, it only applicable if dataType=02 for saving payment method) | ||||||
maxAmount | String | Max length: 18 | Required | |||
Maximum payment amount in two decimals. eg: 10.00 | ||||||
effectiveDate | String | Max length: 10 | Required | |||
Consent effective date in YYYY-MM-DD format. | ||||||
expiryDate | String | Max length: 10 | Required | |||
Consent expiry date in YYYY-MM-DD format. | ||||||
frequency | String | Max length: 2 | Required | |||
Frequency mode: 01 - Unlimited 02 - Daily (00:00:00 until 23:59:59) 03 - Weekly (Monday 00:00:00 until Sunday 23:59:59) 04 - Monthly (first day of the calendar month until end of the calendar month) 05 - Quarterly (first day of the calendar quarter until end of the calendar quarter) 06 - Yearly (first day of the calendar year until end of the calendar year) | ||||||
End Consent Object | ||||||
language | String | Max length: 2 | Required | |||
Select the preferred language to redirect into DuitNow Pay: en - English bm - Bahasa Malaysia |
Sample Request:
{
"dataType": "02",
"checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
"sourceOfFunds": [
"01"
],
"merchantName": "Shop Name Sdn Bhd.",
"merchantReferenceId": "ref12345678",
"merchant": {
"productId": "P00000201"
},
"customer": {
"name": "Walter Mitty",
"identityValidation": "00",
"identificationType": "05",
"identification": "+60123456789"
},
"consent": {
"maxAmount": "500.00",
"effectiveDate": "2024-01-24",
"expiryDate": "2024-04-24",
"frequency": "01"
},
"language": "en"
}
Response
Data Object | ||||||
id | String | Max length: 100 | Required | |||
Session ID that is created by PayNet for the redirect URL. | ||||||
redirectUrl | String | Max length: 140 | Required | |||
Acquirer can use the redirect URL to open the page directly which will land on DuitNow Pay or Save Payment Method Webview depending on the dataType submitted in the request. | ||||||
End Data Object | ||||||
message | String | Max length: 1024 | Required | |||
Response with "OK" if successful. Otherwise, please refer to the reason codes in the appendix. |
Sample Response:
{
"data": {
"id": "4950369a-5ad4-403f-8d8a-675990011b56",
"redirectUrl":"https://duitnow-pay.uat.inet.paynet.my:8443/?sessionId=4950369a-5ad4-403f-8d8a-675990011b56"
},
"message": "OK"
}
Consent Management
When saving a payment method with dataType=02, if any fields within the consent object are not provided, PayNet will display a consent management page to guide users through setting up the consent details. The page below will render the fields not parsed in the API for user selection.
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 17.
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. | ||||||
consentEndToEndId | String | Max length: 35 | Required | |||
Unique message identification from RPP. This can be used to reconcile with RPP BackOffice or Reports. | ||||||
consentId | String | Max length: 35 | Required | |||
Consent that is authorized for AutoDebit payment. | ||||||
issuer | String | Max length: 100 | Required | |||
Name of payer’s issuing bank / wallet. |
Sample Request:
{
"checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
"consentEndToEndId": "20240325M0000201861OBW00618197",
"consentId": "M00002010012700006",
"issuer": "Affin Bank"
}
Webhook: Update Consent Details
This webhook is to update the acquirer when a save payment method is initiated. It will return the consentId with the status.
If acquirer does not receive this webhook, kindly perform Retrieve Saved Payment Registration Status API to enquire the status of consent.
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. | ||||||
ConsentStatus Object | ||||||
consentId | String | Max length: 35 | Required | |||
Consent that is authorized for AutoDebit payment. | ||||||
code | String | Max length: 4 | Required | |||
Please refer to the list of status codes. | ||||||
message | String | Max length: 1024 | Required | |||
Please refer to the list of acceptable reason codes. | ||||||
End ConsentStatus Object | ||||||
issuer | String | Max length: 100 | Required | |||
Name of payer’s issuing bank / wallet. |
Sample Request:
{
"checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
"endToEndId": "20240119DMM2MYKL813OBW00000005",
"consentStatus": {
"message": "U000",
"code": "ACSP",
"consentId": "M00002010012700006"
},
"issuer": "Affin Bank"
}
With the consent authorized by user on the merchant. Acquirer can request payment by initiating DuitNow AutoDebit.
Alternatively …
Acquirer is encouraged to optimize the payment journey by combining saving payment method (DuitNow Consent) and trigger payment (DuitNow AutoDebit) into one single journey to provide a seamless payment experience.
How …
Acquirer will initiate payment intent starting with saving payment method flow (dataType = 02) which DuitNow Consent will be triggered and authorised. Post authentication and authorization, acquirer can directly initiate DuitNow AutoDebit to perform a real time payment in one single journey.
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 consent details 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 Consent Details | Action |
---|---|---|---|
❌ | ✅ | ✅ | No enquiry required, consent registered successful. |
✅ | ✅ | ❌ | Perform Enquire Payment Method Details. |
❌ | ✅ | ❌ | Perform Enquire Checkout Details. If it successful responded, please proceed to perform Enquire Payment Method Details. |
❌ | ❌ | ❌ |