Payment Intents API Endpoints

Create Payment Forms Request #

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.

Body Parameter	Type	Validation	Description	Example
amount required	integer	Minimum: 100	Actual amount of the transaction. Decimal places support up to two decimal places. If the amount is not inputted upfront, the corresponding payment method will accept any amount as payment (open-ended amount).	Values should be in cents. For example, MYR 10.00 should be inputted as 1000. Maximum of MYR 30,000.00 for FPX, and MYR 1,000,000.00 for FPX Corporate.
currency required	string	Default is MYR	Three-letter code of the transaction’s currency. Will be auto-filled as MYR.	MYR
collection_id	string		Default collection id will be used if not provided	DWcUMile
capture conditional	boolean	Default is true	Default is “true” to capture the payment immediately.  Set to “false” to authorize payment to be captured at a later date, using the /api/v1/Transactions/Capture endpoint. Note: To try this, do ensure your account is enabled with pre-authorisation	true
customer_name required	string	maxLength = 50	Name of the customer	John Doe
email	string ($email)	maxLength = 50	Email of the customer	john@email.com
contact_number	string	maxLength = 20	Contact number of the customer	0123456789
address	string	maxLength = 200	Address of the customer	48 Jalan Gembira Taman Desa
postcode	string	maxLength = 10	Postcode of the customer	57100
city	string	maxLength = 50	City of the customer	Petaling Jaya
state	string	maxLength = 50	State of the customer	Selangor
country	string	maxLength = 50	Country of the customer	Malaysia
shipping_name	string	maxLength = 50	Name of the customer for delivery	John Doe
shipping_email	string ($email)	maxLength = 50	Email of the customer for delivery	john@email.com
shipping_contact_number	string	maxLength = 20	Contact number of the customer for delivery	0123456789
shipping_address	string	maxLength = 200	Address of the customer for delivery	48 Jalan Gembira Taman Desa
shipping_postcode	string	maxLength = 10	Postcode of the customer for delivery	57100
shipping_city	string	maxLength = 50	City of the customer for delivery	Petaling Jaya
shipping_state	string	maxLength = 50	State of the customer for delivery	Selangor
shipping_country	string	maxLength = 2	Country of the customer for delivery	Malaysia
description	string	maxLength = 200	Free-text field for any additional information during payment creation. Will be null if none is provided.	beauty product
reference_number	string	maxLength = 40		80TJCFJeOpPh4r7f1
items			Any data as long as in the form of array of dictionaries
metadata			Any data as long as in the form of array of dictionaries
payment_type	string	Enum: [ card, fpx, ewallet, instalment ]	Authorized values for merchant can be retrieved using the /api/v1/Merchants/TransactionTypes endpoint.	card
payment_types	string	Enum: [ card, fpx, ewallet, instalment ]	Customize payment types that are visible to users for each transaction. Defaults to all “payment_types” enabled for merchant if not specified.	card
show_payment_types	boolean		When “payment_type” is specified, use this flag to determine whether all payment types are visible to users, or just the specified “payment_type“. Default when “payment_type” is specified is “false“, while default when “payment_type” is unspecified is “true“.	false
tokenize	boolean		“true” if Merchant wants to tokenize customer’s card details, else, omit parameter	true
card_on_file	string		Type of “credential-on-file” / “card-on-file” payment for subsequent usage. Indicates future card-on-file usage where customer can save the card for future checkout. When “tokenize” is checked, a “card_on_file” will be returned to Merchant at the end of the transaction, that ID must then be stored by Merchant in order to reuse CARD ON FILE functionality.
return_url	string	maxLength = 150	Upon payment, customers can click on a button. Return_url is the link where you want the customer to go back to after clicking the button.	<any valid domain>
callback_url	string	maxLength = 150	URL to your server for Payex to update on response	<any valid domain>
accept_url	string	maxLength = 150	Redirect URL upon accepted payment. If not provided, return_url will be used. Note: This is for merchants who manually create payment link directly from Payex portal i.e. after payment is successful → accept_url is where they want customers to be redirected to.	<any valid domain>
reject_url	string	maxLength = 150	Redirect URL upon rejected payment. If not provided, return_url will be used. Note: This is for merchants who manually create payment link directly from Payex portal i.e. after payment is rejected → reject_url is where they want customers to be redirected to.	<any valid domain>
nonce	string	maxLength = 80	Unique identifier to be returned during payment response
source	string		Custom field to specify source of transaction
send_email	boolean		“true” to email payment intent link to recipient as specified by “email” parameter	false
single_attempt	boolean		“true” if payment intent can only be attempted once and will be deactivated after the attempt regardless of payment status. “false” if payment intent can be reattempted multiple times and will only be deactivated once “expiry_date” of payment intent has passed	false
expiry_date	string ($email)		Expiry date of the payment intent, after which the payment intent will no longer be valid. Parameter should be in UTC time zone, following the format of the example. Default is 2 day after creation.	yyyy-MM-ddTHH:mm:ssZ
splits amount required	integer	minimum: 100	This section is required if you need to split transactions to other accounts such as marketplace use case. Values should be in cents. For example, MYR 10.00 should be inputted as 1000, or if 1.00% should be inputted as 100	1000
split_type required	string	Enum: (“abs”, “pct”)	Whether split should be absolute amount or percentage amount	abs
destination required	string		Payex Registered Merchant email for transaction split to	contact@payex.io
type required	string		Type of split	platform
description	string		Description of split	Platform commission fees

Create Payment Forms Response #

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

Body Parameter	Type	Validation	Description	Example
status	string	Enum: [ 00, 99 ]	Status of payment	Approved
result status key url error	string string string string	Enum: [ 00, 99 ] {api_environment}/Payment/Form/{key}.	Payment Intent ID Redirect to URL returned to access payment form
message	string			Success

Body Parameter	Type	Validation	Description	Example
amount	string		Actual amount of the transaction. Decimal places support up to two decimal places. If the amount is not inputted upfront, the corresponding payment method will accept any amount as payment (open-ended amount).	Values should be in cents. For example, MYR 10.00 should be inputted as 1000. Maximum of MYR 30,000.00 for FPX, and MYR 1,000,000.00 for FPX Corporate.
currency	string		Three-letter code of the transaction’s currency. Will be auto-filled as MYR.	MYR
customer_name	string		Name of the customer	John Doe
description	string		Free-text field for any additional information during payment creation. Will be null if none is provided.	beauty product
reference_number	string	maxLength: 40	You may input any reference number here	80TJCFJeOpPh4r7f1
mandate_reference_number	string		Refers to reference number for mandate generated by Payex	MN10000011621583965
payment_intent	string		This refers to Payment Intent endpoint for creating payment forms.	b96165b897c746c0a2a42032e8bfafea
collection_id	string		Collection ID	owbnr7xq
invoice_id	string
txn_id	string		Transaction ID	PX10000011627008035
txn_date	string($yyyyMMddHHmmss)		Transaction Date	20210723104035
external_txn_id	string		External Transaction ID	2009151119230241
response	string		Payment status description. Unique to each payment type
auth_code	string		Payment response code. ’00’ – Successful, ’09’ – Pending, ’99’ – Pending when FPX, everything else – Failed. For detailed descriptions of each response code, please refer to reference table sheet at the top of the documentation
auth_number	string		Authorization Number	15733223
fpx_mode	string	Enum: [ 01, 02 ]		01 – retail, 02 – corporate
fpx_buyer_name	string		Name of FPX buyer	N@me()/ .-_,&Buyer’`~*;:
fpx_buyer_bank_id	string		Bank code of FPX buyer	Refer to list of FPX buyer bank code
fpx_buyer_bank_name	string		Bank name of FPX buyer	CIMB Bank
card_holder_name	string			N@me()/ .-_,&Buyer’`~*;:
card_number	string			************1111
card_expiry	string			03/27
card_brand	string		Can be any of “VISA”, “MASTERCARD”, “UNIONPAY”	VISA
card_on_file	string	64 alphanumeric key length	Type of “credential-on-file” / “card-on-file” payment for subsequent usage. Indicates future card-on-file usage where customer can save the card for future checkout.	761d35566422d504c96a0f28f3637eeea0d9808a73897f533b53dd9850e4dfbb
signature	string		SHA512(secret + | + txn_id)	3b0806197e8b948a81b2faff2839b3194b9f52707a336e5039a52204a2591abfbd5d4e5aceec4381b15cf0431e02aa6e2c9d17c255e6e7083e47ccfe c182cbaa
txn_type	string		Used to differentiate between different transaction type	FPX FPX CCA FPX B2B FPX CCA B2B Direct Debit Mandate – Authorization Mandate – Approval Mandate – Maintenance Mandate – Termination Malaysian Debit Card Malaysian Credit Card Foreign Card Card – Foreign Currency Auto Debit – Authorization GrabPay PayLater by Grab Postpaid PayLater by Grab Instalment Touch ‘n Go eWallet ShopeePay Riipay Split Unpaid
nonce	string			lenKjMY3VInjYHmtSX398aT2socMZGCOkLIQ8OPPeIaerXSVRW0Arzd33dLnd5M8