Skip to main content

Quick start for FIAT Gate

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)

More information about registration, You can find in GUIDE: Registration and Authenticate

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"

More information about API KEYs, You can find in GUIDE: API KEY

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

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

More information about callbacks, You can find in GUIDE: Callbacks or in 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.
POST https://api.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

More information about payment token, You can find in GUIDE: Getting API token

To create a payment link, you need to use the request /v1/payment-link (Production or Sandbox).
It is enough to specify the reference identifier payment_link_id from the merchant system. You may not specify the currency code currency, the amount amount, successURL, failURL

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

{
  "payment_link_id": "1",
  "amount": 700,
  "currency": "THB",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "webhook_url": "https://example.com"
}
Parameters
  • payment_link_id ← Unique transaction identifier of the merchant (platform); (mandatory)
  • amount ← Amount of payment link from merchant; (optional)
  • currency ← Currency on payment link; (optional)
  • success_url ← URL address, where the customer to be redirected after success processing; (optional)
  • fail_url ← URL address, where the customer to be redirected after failed processing; (optional)
  • webhook_url ← URL address, where should be sended callback by transaction; (optional)

XAMAX will return, in response, the URL to PayLink, where need to redirect the customer for choose payment method and payment.

Response​

{
  "type": "link",
  "value": {
    "link": "https://api.xamax.io/fiat/ui/plink/eyJwYXltZW50TGlua0lkIjoiMTMwOTIwMjQyIiwibWVyY2hhbnRJZCI6M30"
  }
}
Parameters
  • type ← Type of PayLink;
  • value:link ← URL address of PayLink https://plink.xamax.io/…;

More information about PayLink is here

In case, if You don't need to use PayLink and You want to create transaction directly, You can use information from this page page

Step 6: Customer payment​

Customer choose the available payment methods and pay the transaction on XAMAX side. The XAMAX will be inform the merchant about all changes with the status of transaction through callbacks.

Step 7: Get callback with status​

XAMAX will send a POST request to the merchant's callback URL, after each changes of transaction statuses.

Example body of callback

{
  "merchant_transaction_id": "140820241",
  "amount": 642.18,
  "status": "transaction_status_confirmed",
  "status_description": "Transaction is confirmed",
  "substatus": "complete",
  "substatus_description": "Complete",
  "currency": "INR",
  "country": "IND",
  "payment_method": "upi",
  "created_at": "2024-08-14 13:13:41",
  "message": "",
  "ex_rate":""
}
Parametres
  1. merchant_transaction_id - Unique transaction identifier of the merchant (platform);
  2. amount - Amount of transaction from merchant;
  3. status - Current status of transaction;
  4. status_description - Descriptions of current status
  5. substatus - mid status of transaction;
  6. substatus_description - Descriptions of current substatus;
  7. currency* - Currency of transaction;
  8. country - Country of merchant or customer
  9. payment_method - Payment method of transaction
  10. created_at - Date and time of created of transaction
  11. message - Additional information about transaction
  12. ex_rate - Exchange rate of PayLink currency to payment currency
* It may different between currency of transaction and currency of payment

List of final statuses:

  • transaction_status_confirmed - the transaction was successfully paid
  • transaction_status_cancelled - transaction was cancelled from payer side
  • transaction_status_failed - the transaction wasn't paid from payer side
  • transaction_status_refunded - the transaction was back to payer
  • transaction_status_expired - the transaction was not paid within a certain period of time

More information about statuses and status models

Step 8: 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 or GUIDE: Account Setting

Last updated on