Quick start for Fiat Gateway

Payment Gateway get opportunitty to receive FIAT payments from merchant's customers.

At this moment we're working with next currencies:

• Thai Bat (THB)
• Vietnamese Dong (VND)
• Malaysian Ringgit (MYR)
• Indonesian Rupiah (IDR)
• Indian Rupee (INR)
• Philippine Peso (PHP)
• Nigerian Naira (NGN)
• Brazilian Real (BRL)
• Argentine Peso (ARS)
• US dollar (USD)
• EU Euro (EUR)
  and etc

XAMAX allows you to integrate payments into your business. Customers can pay for purchases and services directly from their mobile device or through the XAMAX payment form. The client chooses a convenient payment method, and the business receives and withdraws funds to convenient wallets. XAMAX implements payment gateway to receive money from the client and send it to the business using the settlement network.

This is GUIDE of integration with XAMAX by API and create Your 1st invoice with us at Payment Gateway solution

Step 1: Sign up and Authenticate to XAMAX

Merchant signs up to XAMAX personal account.

Important links of XAMAX

Personal account
Production https://my.xamax.io
Sandbox https://my.sandbox.xamax.io (we recommended begin with it)

Account signed up at Sandbox can be used at Production and veci versa

API endpoint
Production swagger
Sandbox swagger (we recommended begin with it)

Step 2: Gets API keys

Generate Your own API KEY at personal area, in INTEGRATION - API KEY (Production) / (Sandbox)
You can select 3 differents API KEYs:

• for invoicing: with the KEY You can create invoicing transactions, but cannot do withdrawals and exchanging
• for withdrawal: with the KEY You can create withdrawal transactions, but cannot do invoicing
• for invoice and withdrawal: the KEY provide to You opportunitty create invoicing and withdrawal transactions

You should use this API KEYs for geting payment token (access_token) from "Step 4"

Step 3: Set up callback URL

To create and automatically process the transactions, you need to set up a callback-url to receive the status of completed transactions. You can do this in personal account at Production / personal account at Sandbox or via API.
If You want to do that in personal account:

1. Open INTEGRATION - CALLBACK
2. Indicate callback URL at field CALLBACK

• CALLBACK URL for Payment Gateway (Production) / (Sandbox)

CALLBACK URL

We separated callbacks, because for each product You can used different servers or domains.
If URL the same for each product, please, indicate the same URL for each fields

Read more about merchant settings in Payment Gateway settings

Step 4: Gets payment token

To start working and creating Your first invoice you should get payment token (access_token)

1. Send request https://auth.xamax.io/v1/auth/refresh with param "refresh_token" which is Your API KEY, You got at "Step 2" of this guide.
2. Response return to You "access_token", which You'll be used for creating invoice and work with the XAMAX
3. The lifetime of each payment token is 5 minutes
4. Merchant can set up periodic renewal of payment tokens by refresh token procedure. Or update tokens immediately before creating a new invoice. Refresh token is valid for 30 days.

Production

POST https://api.xamax.io/v1/auth/refresh HTTP/1.1
Content-Type: application/x-www-form-urlencoded

refresh_token=%API_KEY%

Sandbox

POST https://api.sandbox.xamax.io/v1/auth/refresh HTTP/1.1
Content-Type: application/x-www-form-urlencoded

refresh_token=%API_KEY%

SwaggerAPI documentationHow to get access tokenContact to support

Read more in Getting API token

Step 5: Create invoice

To create a transaction, you need to use the request /fiat/v1/transaction (Production or Sandbox).

An example of a request to create an invoice

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": "qr_code",
  "amount": 700,
  "country": "THA",
  "currency": "THB",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com"
}

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": "qr_code",
  "amount": 700,
  "country": "THA",
  "currency": "THB",
  "description": "Payment name",
  "success_redirect_url": "https://example.com",
  "fail_redirect_url": "https://example.com"
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Type	Description	Example
transaction_id*	string	Unique end-to-end transaction identifier of the merchant (platform). Used to map a transaction in XAMAX to a transaction in the merchant system	100
payment_method*	string	Payment method, which will be use for payment of transaction	qr_code
amount *	string	Amount of transaction	1000
country*	string	Country of merchant or customer	THA
currency*	string	Currency of transaction, which was selected at merchant side	THB
desctription	string	Information field for transaction	Payment by order #100
success_redirect_url	string	URL for success payment, when will redirect customer after payment	https://success.test.io/
fail_redirect_url	string	URL for fail payment, when will redirect customer after payment	https://fail.test.io/

* - Required parameter

Read more in Creating payment

Step 6: Customer payment

After creating an transaction, the XAMAX returrn payment link for payment. The client must open the link (or automatically redirect to URL link), fill the fields and follow the instructions. By default, an payment link is valid for 30 minutes, after which you will need to create a new transaction.

Example of created invoice
https://api.xamax.io/fiat/ui/page-w?id=eyJ0cmFuc2FjdGlvbl9pZCI6IjE3NyIsIm1lcmN

Read more in Creating payment

Step 7: Changes the status

When the transaction changes the status, XAMAX will send a POST request to the merchant's callback.

Final transaction statuses:

• confirmed - the transaction was successfully completed
• approve_requred - requires manual approval if enabled in settings
• expired - the invoice is no longer valid.
• failed - the transaction wasn't paid from customer side
• cancelled - the transaction was declained from customer side

Example body of callback

{
    "amount": "201",
    "country": "IND",
    "created_at": "2024-01-10 14:47:55",
    "currency": "INR",
    "status": "transaction_status_confirmed",
    "merchant_transaction_id": "231106",
    "message": "",
    "payment_method": "upi"
}    

Parametres

1. amount - Amount of transaction from merchant
2. country - Country of merchant or customer
3. created_at - Date and time of created of transaction
4. currency* - Currnecy of transaction
5. merchant_transaction_id - Unique transaction identifier of the merchant (platform)
6. status - Currently status of transaction
7. payment_method - Payment method of transaction

* It may different between currency of transaction and currency of payment

Step 7: Set up payment settings

For flexible management of wallets and transactions, you can use various settings through the API or through personal account at Production / personal account at Sandbox

Read more in Fiat Gateway settings