Creating FIAT payment

XAMAX provides the ability to perform end-to-end payments via payment links or via payment forms. To use these solutions, no additional integration into merchant systems is required. All solutions are implemented on the XAMAX side.

• when using the link, XAMAX generates payment details for the country (or currency) of the buyer and provides the merchant with a link or QR code for payment. The merchant can send a link to the buyer for payment
• when using the payment form, the buyer will be redirected to the XAMAX payment form to make a payment

For both methods, XAMAX keeps track of when the buyer makes the payment and notifies the merchant of this. The notification can be received via the callback URL or the payment status can be tracked in the merchant's personal account.

Creating FIAT payment link

Payment links provides a way to easily integrate e-commerce purchases to your online or offline business

Merchant can accept payments through any channel or device. All you need to do is send the Payment link to the customer, and it will take them to a XAMAX's payment form for them to complete the payment. Merchant can send Payment link by email or in text message or can show QR code for payment on any screen!

tip

Links can only be used to accept one-time payments, and expire after 24 hours by default.

Available payment methods

Method	API code of methods
Credit/Debit Card	credit_card
QR code	qr_code
Virtual Account	virtual_account
Virtual Bank Account	virtual_bank_account
Online Banking	online_banking
UPI	upi
E-wallets *	name_ewallet
PayID	pay_id

* - OVO, TrueMoney, MOMO, ZALO, GCASH, GRABPAY, PAYMAYA

Available currencies

Region	API code of country	Currency	API code of currency
World	COL, USA and etc	US dollar	USD
World	FRA, POL and etc	EURO	EUR
Argentine	ARG	Argentine Peso	ARS
Australia	AUS	Australian Dollar	AUD
Brazil	BRA	Brazilian real	BRL
India	IND	Indian Rupee	INR
Indonesia	IDN	Indonesian Rupiah	IDR
Kenya	KEN	Kenyan Shilling	KES
Malaysia	MYS	Malaysian Ringgit	MYR
Mexico	MEX	Mexican Peso	MXN
New Zealand	NZD	New Zealand Dollar	NZD
Nigeria	NGA	Nigerian Naira	NGN
Philippine	PHL	Philippine peso	PHP
Thailand	THA	Thai Baht	THB
Vietnam	VNM	Vietnamese Dong	VND

Every day we are expanding the number of currencies offered.
Actual list of currencies can check with Your account manager

Creating payment through personal area

The merchant can create an account for payment through a personal account:

1. In the Fiat Gateway section, click on New transaction

2. In the new New transaction window, you must fill in the required fields:

• country
• payment currency (filled in automatically)
• payment method, several payment methods may be available for each country
• amount of payment
• e-commerce order number
• payment description

3. XAMAX saves the data and creates a payment link, the merchant needs to check the data, copy the link and send it to the buyer

tip

Payment link example: https://api.xamax.io/fiat/ui/page-f?id=eyJtZXJ...

4. If the user follows the payment link, he will be taken to the XAMAX payment form. The buyer needs to fill in the payment or personal data and complete the payment

5. After creating a payment link, the transaction appears in the list of transactions in the Pending status. Merchant can track all created transactions and their status

6. Merchant can view detailed information on each transaction

Creating payment through API

The merchant can create an payment through a XAMAX API:

Production

POST https://api.xamax.io/fiat/v1/transaction HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "payment_method": "credit_card",
  "amount": 700,
  "country": "THA",
  "currency": "USD",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com",
  "type_of_calculation": "forward_with_fee"
}

Sandbox

POST https://api.sandbox.xamax.io/fiat/v1/transaction HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "payment_method": "credit_card",
  "amount": 700,
  "country": "THA",
  "currency": "USD",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com",
  "type_of_calculation": "forward_with_fee"
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Mandatory	Type	Description	Example
transaction_id	Yes	string	Transaction unique reference identifier	1
payment_method	Yes	string	Payment method for specified country. You can use this methods	credit_card
amount	Yes	number	Amount for transaction	100
country	Yes	string	Country code in ISO 3166-1 Alpha-3 format	THA
currency	Yes	string	Currency code in ISO 4217 Alpha-3 format	USD
description	Yes	string	Destination, merchant's information about payment or purpose of transaction	Purchase#123
success_redirect_url	Yes	string	URL address, where the customer to be redirected after success processing	https://xamax.io/callback
fail_redirect_url	Yes	string	URL address, where the customer to be redirected after failed processing	https://xamax.io/callback
type_of_calculation	Yes	enum	Type of fee calculation. Available values are forward_without_fee, forward_with_fee	forward_without_fee
transaction_type	No	enum	Type of response. Available values are link, custom_form	link

Response example

{
  "type": "link",
  "ex_rate": 84.6,
  "value": {
    "link": "https://api.xamax.io/fiat/ui/page-w?id=eyJ0cmFuc2FjdGlvbl9pZCI6IjE3NyIsIm1lcmN"
  }
}

tip

After the payment processing is completed, XAMAX sends a notification to the merchant if the callback URL is set in the settings. You can set the callback URL in payment settings of your personal account

Creating card payment through API (merchant's own card payment form)

In case, if the merchant has a own form (only for card (FIAT to FIAT) payment), can be used next flow
(Available check with Your account manager)

1. Create transaction with method POST /fiat/v1/transaction

Production

POST https://api.xamax.io/fiat/v1/transaction HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "payment_method": "credit_card",
  "amount": 700,
  "country": "THA",
  "currency": "USD",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com",
  "type_of_calculation": "forward_with_fee",
  "transaction_type": "custom_form"
}

Sandbox

POST https://api.sandbox.xamax.io/fiat/v1/transaction HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "payment_method": "credit_card",
  "amount": 700,
  "country": "THA",
  "currency": "USD",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com",
  "type_of_calculation": "forward_with_fee",
  "transaction_type": "custom_form"
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Mandatory	Type	Description	Example
transaction_id	Yes	string	Transaction unique reference identifier	123
payment_method	Yes	string	Payment method for specified country. You can use this methods	credit_card
amount	Yes	number	Amount for transaction	124.50
country	Yes	string	Country code in ISO 3166-1 Alpha-3 format	VNM
currency	Yes	string	Currency code in ISO 4217 Alpha-3 format	USD
description	No	string	Description, merchant's information about payment or purpose of transaction	Purchase#123
success_redirect_url	No	string	URL address, where the customer to be redirected after success processing	https://xamax.io/callback
fail_redirect_url	No	string	URL address, where the customer to be redirected after falied processing	https://xamax.io/callback
type_of_calculation	No	enum	Type of fee calculation. Available values are forward_without_fee, forward_with_fee	forward_with_fee
transaction_type	No	enum	Type of response. Available values are link, custom_form	custom_form

2. Receive response by method POST /fiat/v1/transaction

{
  "transaction_id": 123131333,
  "amount_charged": 100,
  "currency": "USD",
  "type": "custom_form",
  "ex_rate": 1
}

Parameter	Type	Description	Example
transaction_id	string	Unique transaction identifier of the merchant (platform)	123
amount_charged	string	Amount, which should to show the payer on merchant's form	124.50
currency	string	Currency of payment	USD
type	string	Type of transaction	custom_form
ex_rate	string	Exchange rate from local currency to USD	1

3. Send request with method POST /fiat/v1/transaction/submit

Production

POST https://api.xamax.io/fiat/v1/transaction/submit HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "card_number": "4917484589897107",
  "card_expiry_month": "09",
  "card_expiry_year": "29",
  "card_cvv": "123",
  "first_name": "Joe",
  "last_name": "Doe",
  "country": "USA",
  "state": "Florida",
  "city": "Miami",
  "postcode": "291923",
  "address": "Some Fake Address 123",
  "phone": "998900858585",
  "email": "some@example.com"
}

Sandbox

POST https://api.sandbox.xamax.io/fiat/v1/transaction/submit HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "transaction_id": "1",
  "card_number": "4917484589897107",
  "card_expiry_month": "09",
  "card_expiry_year": "29",
  "card_cvv": "123",
  "first_name": "Joe",
  "last_name": "Doe",
  "country": "USA",
  "state": "Florida",
  "city": "Miami",
  "postcode": "291923",
  "address": "Some Fake Address 123",
  "phone": "998900858585",
  "email": "some@example.com"
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Mandatory	Type	Description	Example
transaction_id	Yes	string	Transaction unique reference identifier, which was used at POST /fiat/v1/transaction	100
card_number	Yes	string	Credit/Debit card number	42424242424242
card_expiry_month	Yes	string	Credit/Debit card expiry month	11
card_expiry_year	Yes	string	Credit/Debit card expiry year	2027
card_cvv	Yes	string	Credit/Debit card CVV or CVC. It is 3 or 4 digit number at the back of the card	123
first_name	Yes	string	User's first name appears on his/her Credit/Debit Card	James
last_name	Yes	string	User's last name appears on his/her Credit/Debit Card	Toni
country	Yes	string	User 2 Character country code	US
state	Yes	string	User state or province	California
city	Yes	string	User city	Los Angeles
postcode	Yes	string	User resident postcode	654213
address	Yes	string	User resident address	4013 Loving Acres Road
phone	Yes	string	User active mobile number	7767545432
email	Yes	string	User's active email address. This essential information ensures seamless communication and enables access to personalized features and updates	info@xamax.io

4. Await response

XAMAX can return at response redirect_url, if required 3Ds

{
  "response_type": "3ds_redirect",
  "redirect_url": "https://api.xamax.io/fiat/ui/waiting/eyJ0cmFuc2FjdGlvbl9pZCI6IjUwN2RhOGIzLWQyNWEtNDRlMS1hZjliLTIxM2ZjYTI3MGFjOSJ9",
  "message": "You need to confirm your payment"
}

4. Success payment

Afer success payment from payer side, XAMAX will send callback by the transaction to merchant callback_url

Getting list of transactions

Production

GET https://api.xamax.io/fiat/v1/transactions HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

Sandbox

GET https://api.sandbox.xamax.io/fiat/v1/transactions HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

SwaggerAPI documentationHow to get access tokenContact to support

Request contains query parameters

Parameter	Type	Description	Default value	Example
order_direction *	string	Direction of sorting. Available values : asc, desc	asc	asc
order	string	Order by field		status
page *	string	Page number		1
per_page *	string	Number of transactions on one page	20	20
status	string	Filter by status. Available values : transaction_status_pending, transaction_status_confirmed, transaction_status_failed, transaction_status_waiting		transaction_status_waiting
payment_method	string	Filter by payment methods. Available values : virtual_account, qr_scan, online_bank_transfer, credit_card, wire, paymay_ewallet, grabpay_ewallet, gcash_ewallet, ewallet, online_banking, mobile_money, upi, upi2, we_chat_pay, ali_pay, cup, p2p, cash, cards, agent, momo_ewallet, zalo_ewallet, virtual_bank_account, qr_code, truemoney_ewallet, upi_ewallet, ovo_ewallet, go_pay_ewallet, promptpay		go_pay_ewallet
since	string	Filter from creating transaction's date
till	string	Filter to creating transaction's date

* - Required parameter

Response example

{
  "transactions": [
    {
      "id": 1,
      "merchant_id": 12,
      "amount": 700,
      "amount_charged": 720,
      "transaction_id": 123,
      "currency": "NGN",
      "status": "transaction_status_pending",
      "description": "Deposit payin",
      "additional_currency": "USD",
      "rate_merchant_final": 675,
      "created_at": "2023-06-02T07:07:51.000000Z",
      "payment_method": "cards"
    }
  ]
}

Getting detailed information of transaction

Production

GET https://api.xamax.io/fiat/v1/transaction?transaction_id={ID} HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

Sandbox

GET https://api.sandbox.xamax.io/fiat/v1/transaction?transaction_id={ID} HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

SwaggerAPI documentationHow to get access tokenContact to support

Request contains query parameters

Parameter	Type	Description	Default value	Example
transaction_id *	string	Transaction's Identifier		100

* - Required parameter

Response example

{
  "transaction_id": 1,
  "created_at": "2023-05-30T14:23:55.000000Z",
  "updated_at": "2023-05-30T14:23:55.000000Z",
  "amount_delivered": 700,
  "currency": "NGN",
  "country": "NGA",
  "descriptions": "Deposit",
  "payment_method": "cards",
  "status": "transaction_status_pending",
  "type_of_fee_calculate": "forward_without_fee",
  "link": "https://api.xamax.io/fiat/ui/page-a?id=eyJtZXJjaGFudF9pZCI6IjEiLCJhbW91bnQiOjczNi44NCwiY291bnRyeSI6IlRIIiwicHJvZHVjdCI6IjEiLCJjdXJyZW5jeSI6IlRIQiIsInRyYW5zYWN0aW9uX2lkIjoiMSIsInBheW1lbnRfbWV0aG9kIjoicXJfY29kZSJ9",
  "merchant_fee_fix": 230.3,
  "merchant_fee_percent": 2,
  "additional_currency": "USD",
  "rate": 756
}