The Payex API is organized around REST to make it clearer and easier to understand. All our API responses return JSON, including errors.

API Environment Summary

There are two servers for our API, one for sandbox and the other for production environments. You may test with sandbox endpoints before going into production, which doesn’t affect your live data or interact with live banking networks. 

The secret API key you use to authenticate the request determines whether the request is sandbox mode or production mode. Do not use Production Secret in the Sandbox Environment, or vice versa, as it will fail. API requests without authentication will also fail. 

You may get your API secret from Payex Portal links below. The login credentials are sent to the registered merchant email, titled “Account Set Up Successful” by Payex (contact@payex.io):

• Sandbox Environment: https://sandbox-payexportal.azurewebsites.net/
• Production Environment: https://portal.payex.io/

Note: To access the Sandbox portal, merchant to login with your registered email address and default password = “Password“

Before you start

Go to https://portal.payex.io/Home/Register to sign up as a merchant. 

Submit all required documents as shown in the merchant portal and get approval from our processing team. If you need more assistance, please contact us at merchantsupport@payex.io

Go to Payex Merchant Portal > Settings > Copy to Secret

Go to Payex API > Select the environment > Click “Authorize”

Follow Authorization Steps

Authentication Step 01: Basic (http, Basic)

1. Under Username, input registered merchant email with Payex.
2. Under Password (change to Secret), input Secret from Payex Merchant Portal.
3. Click “Authorize” again. The “Authorize” button should be replaced with the “Logout” button.

Authentication Step 02: Bearer (http, Bearer)

1. Go to /api/Auth/Token
2. Click “Try it out” > Click “Execute” > Access token will be returned

1. Copy the Token
2. Input the token in the Bearer section under Value in the same Authorize screen.
3.  Click “Authorize” again

With that, you now have access to the rest of the APIs.

To make it easier to get familiar with Payex Authentication, we’ve published a sample payment flow through Swagger and Postman. Related video:

Payment Request through Swagger

Payment Request through Postman

This endpoint provides the following functionalities:

• Initializes the payment/capture process for FPX, Cards, E-wallets and Subscription Payments (Direct Debit/Auto Debit).
• Payment forms allow merchants to accept online payments through Payex web applications.
• Customers can enter payment details or select e-wallet / installment options to complete the payment process from their smartphones and website.

Create Payment Forms Response

A successful Payment Request creation returns a HTTP 200 status code with the following response parameters.

• This API allows you to manage, search and view Transactions and Settlement.
• This API is equivalent to the “Transactions” and “Settlements” tab from Payex dashboard. See payex.io/docs on how to use transaction and settlement tabs in Payex dashboard.

Get transaction by Transaction ID

Request this endpoint to get specific transaction details by ‘id’ as required parameter below.

Successful response returns parameters below with status code 200

Get all transactions

Request this endpoint to get all transactions from a date range using ‘start_date’ and ‘end_date’, or get transactions using specific identifiers like ‘payment_intent’, ‘txn_id’, ‘reference_number’, etc. Use ‘search_text’ if unsure of the actual identifier.

Note: Limit is how many rows to get, for example, 10 limit means will return up to 10 rows, and 10 limit and page 2, means rows 11 to 20 of the results

Get transactions settlements

Request this endpoint to get transaction settlements by ‘start_date’ and ‘end_date’ as required parameters.

Note: Limit is how many rows to get, for example, 10 limit means will return up to 10 rows, and 10 limit and page 2, means rows 11 to 20 of the results

Void transaction by Transaction ID

Request this endpoint to cancel pre-authorized transactions with ‘id’ as required parameter.

A successful request returns a HTTP 200 status code with the following response parameters.

A bad request returns a HTTP 400 status code with the following response parameters.

Refund transaction by Transaction ID

Request this endpoint to refund transactions with ‘id’ and ‘amount’ as required parameters.

• All payment types can be refunded via this endpoint except for Online Banking (FPX).
• Card transactions that have been made on the same day can only be refunded completely.
• Refunded amounts will either be automatically deducted from merchant upcoming settlement, or a payment link will be generated to prompt merchant for manual payment before transaction can be refunded.

A successful request returns a HTTP 200 status code with the following response parameters.

A bad request returns a HTTP 400 status code with the following response parameters.

Capture pre-authorized transactions by Transaction ID

Request this endpoint to capture pre-authorized transactions with ‘id’ and ‘amount’ as required parameters.

A successful request returns a HTTP 200 status code with the following response parameters.

A bad request returns a HTTP 400 status code with the following response parameters.

Get FPX Bank List

Request this endpoint to get FPX Bank List with ‘type’ as required parameter.

A successful request returns a HTTP 200 status code with the following response parameters.

Splits transaction to other merchant accounts

Request this endpoint to splits transaction to other merchant accounts with ‘id’ as required parameter.

A successful request returns a HTTP 200 status code with the following response parameters.

A bad request returns a HTTP 400 status code with the following response parameters.

This endpoint provides the following functionalities:

• Subscriptions payment via online banking (bank account and credit card).
• Subscriptions payment via Visa/Mastercard (credit card, debit card, foreign card).

Create Mandates Response

A successful Mandate Request creation returns a HTTP 200 status code with the following response parameters.

Create Mandate Response Codes

• For mandate authorization, refer to Response Codes with Type = ‘FPX’ for Direct Debit and Response Codes with Type = ‘Card’ for Auto Debit
• For auto debit collection, refer to Response Codes with Type = ‘Card’
• For direct debit collection, refer to Response Codes with Type = ‘BILLING’

Authorization Callback Response (Mandate Authorization Completion)

This refers to callback response upon mandate authorization completion (for both Direct Debit and Auto Debit) which will be sent via webhook to the specified callback_url. We will be using the charged by cards (Auto Debit) example below:

Approval Callback (Mandate Approval for Direct Debit only)

This refers to response upon mandate approval completion which will be sent via webhook to the specified callback_url. There’s two callback for Direct Debit, as first callback is for customer authorization while second callback is for bank approval.

Get Mandate Response

This endpoint allows you to retrieve the details of mandate payment by the following parameters (optional fields):

Note: Limit is how many rows to get, for example, 10 limit means will return up to 10 rows, and 10 limit and page 2, means rows 11 to 20 of the results

If successful, this endpoint returns HTTP 200 status code with the following response parameters.

Update Mandates Request

This endpoint allows you to update mandates (only in Draft status) that have been created using ‘reference_number’ as the request parameter below (required field):

‘reference_number’ refers to reference number for mandate generated by Payex (e.g. MN10000171626860885)

A successful Update Mandate Request will return a HTTP 200 status code with the following response parameters.

Delete Mandates Request

This endpoint allows you to delete mandates using reference_number as the request parameter below (required field):

‘reference_number’ refers to reference number for mandate generated by Payex (e.g. MN10000171626860885)

Note: reference_number is the required parameter for this endpoint and it refers to a list/array of reference numbers for mandate generated by Payex. You may choose to delete multiple mandates at a time and the parameter format will be [“MNxxxx”,”MNxxxx”].

A successful Delete Mandates will return a HTTP 200 status code with the following response parameters.

Update Mandate Collection Settings Request

This endpoint allows you to update mandate collection settings with ‘reference_number’ as required parameter:

‘reference_number’ refers to reference number for mandate generated by Payex (e.g. MN10000171626860885)

A successful Update Mandate Collection Settings Request will return a HTTP 200 status code with the following response parameters.

Create Collections Request

This endpoint allows you to create collection request upon authorisation of mandate by your customers.

A successful Create Collection Request will return a HTTP 200 status code with the following response parameters.

Collection Callback

Response upon mandate collection completion which will be sent via webhook to the specified callback_url.

Read Collections Response

This endpoint allows you to read collections by the following parameters (optional fields):

Delete Collections Response

This endpoint allows you to delete collections with ‘collection_number’ as the required parameter below:

A successful Delete Collection will return a HTTP 200 status code with the following response parameters.

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

i) For this example, we will pretend to be a merchant that wants to collect a fixed amount for the first 23 months, followed by collection of different amount only for the final month.

• I have created a Direct Debit mandate for 24 months, where each month collection is fixed at RM300.00.
• Now I need to collect only RM150.50 for the final month. How can I update it for the final month via Payex API?

Few ways to do it via Update Mandate Collection Settings Request endpoint /api/v1/mandates/collectionSettings/reference_number:

Option 1: Mandate setting for auto collection to ‘false’

• If auto = false, Payex will wait for your instructions before next deduction
• You would need to create one mandate and 24 collections
• Create collections for 23 months for RM300.00, and final month RM150.50

Option 2: Mandate setting for auto collection to ‘true’

• If auto = true, system will auto collect every month
• After 23rd month collection or before 24th month collection, you need to change collection amount to RM150.50

Option 3: Mandate setting for auto collection to ‘true’

• If auto = true, system will auto collect every month
• Create collection for the 24th month for RM150.50, then Payex auto collection schedule will skip the 24th month when the time comes
• For example, if mandate’s effective date 1st Jan 2024, for 24 months period the last collection will be 1st Dec 2025. So, you need to create collection for 1st Dec 2025 as RM150.50, the rest of months will follow auto collection schedule.

ii) For this example, we will pretend to be a merchant that wants to collect a different amount only for the first month, followed by a fixed amount for the next 11 months.

Few ways to do it via Create Mandate Request endpoint /api/v1/Mandates:

Option 1: Mandate for auto collection to ‘false’

• Call create mandates endpoint to authorise (max amount = RM300, auto=false)
• Call create collection endpoint to collect RM100 for 1st month
• Call create collection endpoint to collect RM300 for 2nd to 12month

Option 2: Mandate for auto collection to ‘true’

• Call create mandates endpoint to authorise (max amount = RM300, auto=true)
• Call create collection endpoint to collect RM100 for 1st month
• RM300 collection will be auto created for 2nd to 12month

Option 3: Mandate for auto collection to ‘true’

• Call create mandates endpoint to authorise (max amount = RM300, auto=true)
• Call payment intent endpoint to collect RM100 for 1st month using one time payment
• RM300 collection will be auto created for 2nd to 12month

Scenario B: Terminate collection halfway through

For this example, we will pretend to be a merchant that wants to stop all collection from the customer who has decided to pay down all dues / early settle the outstanding amount

• I have created a Direct Debit mandate for 60 months, where each month collection is fixed at RM300.00.
• Customer started paying for January and in February decides to pay down all outstanding amount. Which API can I use to instruct Payex to stop collecting funds from my customer in March onwards?

Option 1: Use Update Mandate Collection Settings Request endpoint

/api/v1/mandates/collectionSettings/reference_number

curl --location --request PUT '/api/v1/Mandates/CollectionSettings/MNxxxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
    "active": false
}'

• Note: Reference number is path instead of query param

Option 2: Use Delete Mandates Request endpoint

/api/v1/Mandates

• If delete mandate then all collections under the mandate will be deactivated
• You can still delete mandates although some collections are active
• Delete mandate endpoint will need customer to authorise the termination link

Scenario C: Collect at varying dates for different customers

For this example, we will pretend to be a merchant that wants to initiate two types of subscription plan depending on the customer’s subscription start date

• Subscription Plan A: When customer subscribes on any date between 1st to 29th April; the next payment i.e. 2nd payment = 1st May
• Through Payex API
  • Set the param “day” to whichever day of month as anchor day, so if 1st of May then set day=1
  • Effective date can remain as any date from 1st to 29th April (e.g. 20240415). So next billing will be 1st of every month.
  • Once setup, Payex system will automatically charge the customer if the setting for auto=true
  • Alternatively if auto=false, then you can send collection request to Payex on whichever date and Payex will process accordingly

• Subscription Plan B: When customer subscribes on 30th April (last day of the month); the next payment i.e. 2nd payment = 1st June
  • Option 1: You will have to call Payex API to make “inactive” the mandate and activate again on 1st June
  • Option 2: For these types of non-standard collection schedule, will be better to use your own schedule (set auto=false)

See more:

• Mandates API endpoint
• How to Create Manual Collection via Mandate Link for Subscription Payment

FPX

Card

Note: This is applicable for one-time card payment, credit card instalment payment and auto debit (subscription payment).

GrabPay

TNGD

Shopee

Riipay

Split

Batch (For Collection)

Note: This is applicable batch collection status under subscription payments.

BILLING (For Direct Debit)

ENRP

Mandate

Note: This is applicable for both direct debit and auto debit subscription payments.

POST https://api.payex.io/api/v1/PaymentIntents

[
    {
        "amount": "200000",
        "currency": "MYR",
        "customer_name": "Test 123",
        "contact_number": "0123456789",
        "email": "test@gmail.com",
        "description": "Test",
        "reference_number": "test 123",
        "payment_type": "instalment",
        "payment_confirm": true,
        "payment_type_data": {
            "provider": "mbb_06"
        }
    }
]

Below are the bank codes, please use format “bank codes” + “_” + tenure (06/12/18/24/36/48/60) for parameter “provider”, do follow the available combinations of banks and tenures. For example 48/60 months are only available for CIMB etc

abb
ambb
cimb
hlbb
hsbc
mbb
ocbc
pbb
rhb
scb
uob

If the goal is to be able to capture the instalment info, that info is actually provided in the callback param “txn_type”, so if customer chooses bank and tenure on payex page, you will still be able to tell which bank and tenure after the transaction.

Payment Simulation

Card

“card_holder_name”: “TEST CARD”,
“card_number”: “5453 0100 0009 5323”,
“card_expiry”: “0822”,
“card_cvc”: “123”,