...IntegrationSelf Hosted PageInitiate Consent

Initiate Consent (Save Payment Method - DuitNow Consent)

This API endpoint streamlines the checkout experience by allowing upfront consent registration from the payer, paving the way for a smoother payment process later. Acquirer can seamlessly integrate directly using the specified specifications and process flow, bypassing PayNet's hosted page. This option empowers merchants to streamline the journey of saving a payment method for future transactions.

Process Flow

Step	Sender	Receiver	Process
1	Payer	Acquirer	Payer initiates a payment via DuitNow Pay.
2	Acquirer	API Gateway	Acquirer request API Gateway to pull the available banks and payment methods.
3	API Gateway	Acquirer	The bank list will be parsing back to acquirer for user to select their preferred payment method.
4	Payer	Acquirer	Payer will select their preferred Online Banking / Wallet (OBW) method to save.
5	Acquirer	API Gateway	Acquirer will initiate the consent API to initiate the RPP consent 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 also 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 authorize consent.
10	Issuing Bank	Payer	Bank will provide the consent details to the payer.
11	Payer	Issuing Bank	Payer will authorize the consent upon verifying the consent details.
12	API Gateway	Acquirer	Consent details 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.

Request

POST /v1/bw/consent

checkoutId	String	Max length: 36		Required
The unique external identifier (uuid v4) provided by the acquirer to PayNet when initiating a payment intent.
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)
Merchant Object
productId	String	Max length: 35		Required
Product identification assigned by PayNet during merchant registration in Developer Portal.
End Merchant Object
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
Consent Object
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

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "issuer": "Affin Bank",
    "sourceOfFunds": [
        "01"
    ],
    "merchant": {
        "productId": "P00000201"
    },
    "merchantReferenceId": "ref12345678",
    "customer": {
        "name": "Walter Mitty",
        "identificationType": "05",
        "identification": "+60123456789",
        "identityValidation": "00"
    },
    "consent": {
        "maxAmount": "100.00",
        "effectiveDate": "2024-01-24",
        "expiryDate": "2024-04-24",
        "frequency": "01"
    }
}

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.
End Data Object
message	String	Max length: 1024		Required
Refer to reason codes in the appendix.

Sample Response:

{
  "data": {
        "endToEndId": "20240208M0037091811OBW00000224",
        "endToEndIdSignature": "f1HfevZrnqp1zBxYVpCV2WnknPCATzv07Ih1d/33O6Ak5VgFq8GvGwGO6FftMdE8EyDSOGIvEqTGZ3VFZep7rpp39MmCGdyRXW4/gw8FhWX3CgaBbKoIpe44JUKO9W2xHvhw5NKn442qQ2xE/ybPN4WHOSr59C0fS6IhDlWHUx/Wvx64mAjRMGq5708wkNTctKHclfoseCoQeJXaCyKoydJtzBcKyspA99AweXg2DmWyE8Zzv10bPdyij3T5hEcGEVXM70MsybrWdA38ko91/yAxlycAEFFV4f1IUSzBkFvkbmBCWApzVlcwl+EovJQspEOLfWy1YyVuDlOyDIc1sA==",
        "issuer": "Affin Bank"
    },
    "message": "U000"
}

UI Requirements for Consent Management

When a customer saves a payment method via consent, the above UI requirements must be adhered to during development. While the color scheme and font can be customized, it is crucial that user guidance remains clear.

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.
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.

info

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.
issuer	String	Max length: 100		Required
Name of payer’s issuing bank / wallet.
ConsentStatus Object
consentId	String	Max length: 35		Required
Consent that is authorized for AutoDebit payment.
code	String	Max length: 4		Required
Please refer to appendix for the list of status codes.
message	String	Max length: 1024		Required
Please refer to appendix for the list of reason codes.
End ConsentStatus Object

Sample Request:

{
    "checkoutId": "a7e2ed2a-b088-4495-8cf4-88da08f644f2",
    "endToEndId": "20240119DMM2MYKL813OBW00000005",
    "consentStatus": {
        "message": "U000",
        "code": "ACSP",
        "consentId": "M00002010012700006"
    },
    "issuer": "Affin Bank"
}

info

With the consent authorized by user on the merchant. Acquirer can request payment by initiating DuitNow AutoDebit.

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.
❌	❌	❌