API Flow for Subscription Payment (Mandates)

Sign up for a Payex Account #

Ensure that you already have a Payex account. You may register here or checkout our Activation page, if otherwise. Once you’ve registered and provided your business documents, your account will be automatically enabled for integration testing access. 

Create a mandate #

Fire a POST request to /api/v1/Mandates with the required parameters.

// sample request body
[
  {
    "customer_name": "John Doe",
    "email": "user@example.com",
    "contact_number": "0123456789",
    "merchant_reference_number": "string",
    "id_type": "1",
    "id_number": "900825086780",
    "fpx_mode": "01", 
    "fpx_buyer_bank_id": "900825086780",
    "effective_date": "yyyyMMdd",
    "expiry_date": "yyyyMMdd",
    "max_amount": "1000", 
    "initial_amount": "1000", 
    "frequency": "MT" 
    "max_frequency": "1", 
    "purpose": "Monthly Subscription Plan",
    "debit_type": "DD",  
    "return_url": "<any valid domain>",
    "callback_url": "<any valid domain>",
    "accept_url": "<any valid domain>",
    "reject_url": "<any valid domain>",
    "address": "48 Jalan Gembira Taman Desa",
    "postcode": "57100",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "country": "Malaysia",
    "status": "Pending",
    "auto": true, 
    "retry": true, 
    "retry_count": 0 
  }
]

If all inputs validation and general inputs handling are valid, you’ll receive a SUCCESS response from Payex

{
  "status": "00",
  "result":
  [
    {  // create successfully
       "status": "00",
       "reference_number": "<system_generated>",
       "key": "<system_generated>",
       "url": "<system_generated>"
    },
    {  // error occurred
        "status": "99",
        "error": "<error_description>"
    },
    ...
  ],
  "message": "Success"
}

What to take note #

• You only have to provide one callback url and we will send different responses to it
• ‘txn_type’ is used to differentiate between different callback responses. List of available ‘txn_type’ for callback as below:
  • Mandate – Authorization
  • Auto Debit – Authorization
  • Mandate – Approval
  • Malaysian Debit Card
  • Malaysian Credit Card
  • Foreign Card
• Direct Debit mandate: There’s two callbacks, first callback is for customer authorization and second callback is for bank approval
  • If the customer did not click the payment link, status will be “Pending“
  • If the customer clicks the payment link and fills out relevant information and click “Proceed” customer will receive email notification on authorisation.
  • Upon successful collection of 1st payment, customer will receive another email notification.
• Auto Debit mandate: There’s only one callback for authorization and approval at the same time.
  • If the customer clicks the payment link, the 1st instalment will be collected on the effective date.
  • If you wish to instantly charge customer the 1st instalment during authorisation, include the ‘initial_amount’ parameter.
• There will be a one-time charge of RM 1 (via bank account) for the purpose of account verification and it takes 1 working day to be approved by RHB
• There will be no charge (via local / foreign cards) for the purpose of account verification and it is instant approval by Visa/Mastercard
• Once it has been approved by RHB or Visa/Mastercard then you can start collecting payment from your customers.

What to do next (for success case) #

1. Send mandate link to your customer for authorization
2. Customer fills out relevant information and submits (Day t)
3. Wait for Mandate Authorization Callback (Day t)

Direct Debit #

Callback for customer authorization

Mandate - Authorization Callback Response (Day t)

{ 
    "amount": "1.00",  
    "currency": "MYR",
    "customer_name": "Test Customer",
    "description": "Monthly Subscription Plan",
    "mandate_reference_number": "MN10000011621583965",
    "payment_intent": "b96165b897c746c0a2a42032e8bfafea",
    "collection_id": "owbnr7xq",
    "invoice_id": "",
    "txn_id": "PX10000011627008035",
    "external_txn_id": "2009151119230241",
    "response": "Approved",
    "auth_code": "00",
    "auth_number": "15733223",
    "txn_date": "20210723104035",
    "fpx_mode": "01",
    "fpx_buyer_name": "N@me()/ .-_,&Buyer'`~*;:",
    "fpx_buyer_bank_id": "TEST0021",
    "fpx_buyer_bank_name": "SBI BANK A",
    "card_holder_name": null,
    "card_number": null,
    "card_brand": null,
    "signature": "3b0806197e8b948a81b2faff2839b3194b9f52707a336e5039a522
04a2591abfbd5d4e5aceec4381b15cf0431e02aa6e2c9d17c255e6e7083e47ccfe
c182cbaa",
    "txn_type": "Mandate - Authorization", 
    "nonce": "lenKjMY3VInjYHmtSX398aT2socMZGCOkLIQ8OPPeIaerXSVRW0A
rzd33dLnd5M8"
}

-> Wait for Mandate Approval Callback (Day t + 1 – Next working day after submission)

Callback for bank approval

Mandate Approval Callback Response

{  
    "application_type": "01",
    "approval_status": "00",
    "approval_date": "20210721",
    "txn_id": "PX10000171626952548",
    "reference_number": "MN10000171626860885",
    "record_number": "E-20210721Q964879",
    "fpx_mode": "01",
    "fpx_buyer_name": "N@me()/ .-_,&Buyer'`~*;:",
    "fpx_buyer_bank_name": "SBI BANK A",
    "fpx_buyer_bank_account": "********1234",
    "signature": "68f21dfb966f264dbd996ad809828b8e763bc5798fbefb5ada434af3
c6a87873d525f7066c5b9e9963ef676f2e672d2835779bc59b09522
3a43058dc935b04f3",
    "txn_type": "Mandate - Approval"
}

-> Create Collection Settings for next collection at Day t + 2

Auto Debit #

Auto Debit - Authorization Callback Response (Day t)

• If ‘initial_amount‘ > RM1.00

{ 
    "amount": "88.00", 
    "currency": "MYR",
    "customer_name": "Test Customer",
    "description": "Monthly Subscription Plan",
    "reference_number": "MN10000011621583965",
    "payment_intent": "b96165b897c746c0a2a42032e8bfafea",
    "collection_id": "owbnr7xq",
    "invoice_id": "",
    "txn_id": "PX10000011627008035",
    "external_txn_id": "2009151119230241",
    "response": "Approved",
    "auth_code": "00",
    "auth_number": "15733223",
    "txn_date": "20210723104035",
    "fpx_mode": null,
    "fpx_buyer_name": null,
    "fpx_buyer_bank_id": null,
    "fpx_buyer_bank_name": null,
    "card_holder_name": "N@me()/ .-_,&Buyer'`~*;:",
    "card_number": "411111******1111",
    "card_brand": "VISA",  
    "card_on_file": "761d35566422d504c96a0f28f3637eeea0d9808a73897f533b5
3dd9850e4dfbb", 
    "signature": "3b0806197e8b948a81b2faff2839b3194b9f52707a336e5039a522
04a2591abfbd5d4e5aceec4381b15cf0431e02aa6e2c9d17c255e6e7083e47ccfe
c182cbaa",
    "txn_type": "Malaysian Debit Card",  
    "nonce": "lenKjMY3VInjYHmtSX398aT2socMZGCOkLIQ8OPPeIaerXSVRW0A
rzd33dLnd5M8"
}

-> System created Collection Settings for you automatically at Day t

• If ‘initial_amount‘ < RM1.00

{ 

    "amount": "1.00", 
    "currency": "MYR",
    "customer_name": "Test Customer",
    "description": "Monthly Subscription Plan",
    "reference_number": "MN10000011621583965",
    "payment_intent": "b96165b897c746c0a2a42032e8bfafea",
    "collection_id": "owbnr7xq",
    "invoice_id": "",
    "txn_id": "PX10000011627008035",
    "external_txn_id": "2009151119230241",
    "response": "Approved",
    "auth_code": "00",
    "auth_number": "15733223",
    "txn_date": "20210723104035",
    "fpx_mode": null,
    "fpx_buyer_name": null,
    "fpx_buyer_bank_id": null,
    "fpx_buyer_bank_name": null,
    "card_holder_name": "N@me()/ .-_,&Buyer'`~*;:",
    "card_number": "411111******1111",
    "card_brand": "VISA",  
    "card_on_file": "761d35566422d504c96a0f28f3637eeea0d9808a73897f533b5
3dd9850e4dfbb", 
    "signature": "3b0806197e8b948a81b2faff2839b3194b9f52707a336e5039a522
04a2591abfbd5d4e5aceec4381b15cf0431e02aa6e2c9d17c255e6e7083e47ccfe
c182cbaa",
    "txn_type": "Auto Debit - Authorization",  
    "nonce": "lenKjMY3VInjYHmtSX398aT2socMZGCOkLIQ8OPPeIaerXSVRW0A
rzd33dLnd5M8"
}

-> Create Collection Settings for next collection at Day t