# Introduction ### ​:question:What is Axom Axom Payment Gateway is a solution that enables merchants to accept cryptocurrency payments and initiate withdrawals to customers, providing a seamless experience for both sides. The following API documentation comprises of all currently supported public endpoints. Each separate endpoint is accompanied by a small description together with a few example requests, responses, and code snippets. ### :up: Key Features * **Multiple Deposit Currencies**: Accept payments via the most used crypto currencies and automatically distribute them into one of the supported settlement currencies. * **FIAT Deposits and Withdrawals**: Using our services you can easily decide when you need a quick fiat top-up to any of your business or request a fiat withdrawal. * **Global Reach**: Support for multiple currencies and international payments, helping you reach customers around the world. * **Extensive Reporting**: Access detailed transaction reports in real-time to track your business's performance. * **Easy Integration**: Our API is designed with simplicity in mind, allowing you to integrate quickly and with minimal coding. ### :star: Getting Started with our API To start using the {{COMPANY\_POSSESIVE\_FORM}} API follow these steps: 1. **Get Your API Keys**: After signing up, you will be able to create your API keys, which are necessary for authentication. 2. **Review the Documentation**: Familiarize yourself with the API endpoints, request/response formats, and error codes. 3. **Start Testing**: We will help you test your integration without processing real payments. 4. **Go Live**: Once you’re ready, switch to the live environment and start processing real transactions. ### :blue\_book: Support and Resources If you need help, we're here for you: * **Documentation**: In our API references and guide pages you will find additional information to help you navigate our platform. * **Support Team**: Contact our support team for personalized assistance * Check out our [**Changelog** ](/changelog)to see the newest features released. As you explore the documents and guides, don’t hesitate to reach out if questions arise or assistance is needed. Our dedicated support team are here to ensure your integration is smooth and successful. # Authorization The Axom API's authorization scheme When authorizing against the Axom REST API, one must provide a standard HTTP `Authorization` header in the following format: ```aspnet 'Authorization: FRX-API api-key=, signature=, timestamp=' ``` [API credentials](/authorization/management) consist of an **API key** and an **API secret,** forming a pair together. The key must be passed with each request in the Authorization header’s API-Key component and the **API secret** is used for the generation of the [Signature](/authorization/signature) component.\ The **Timestamp** component must be an integer value representing the current [UNIX epoch time](https://www.unixtimestamp.com/) in milliseconds. {% hint style="info" %} **All requests that require authorization are labelled with this icon 🔒** {% endhint %} # API Keys Management How to create, edit and update API secret/key pairs API credentials can be managed directly from the [Axom Dashboard](https://dashboard.axom.money) by users with the Manager or Admin or custom roles with the relevant permission. To create API credentials go to **"Settings -> API keys"** and click on the **“New Key”** button. Here you can provide a name (alias) for the key/secret pair and select the permissions that are relevant to your use-case. Your 2FA code will also be required as a step of the key creation process.\ \ Due to security concerns, we also require IPs to be whitelisted. If we receive a request from an IP that was not listed for the API pair, we will reject it returning a 403 (Forbidden) HTTP status code. ![](https://3564521227-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FayvBVHqhLmJiaoA9GyTQ%2Fuploads%2Fgit-blob-4f4dbcf383c5f488c5b7103c628abaf781ecd1bb%2Fapi-key.gif?alt=media) Upon successful API credentials creation, you will be provided with the values for the **API key** and **API secret**. At this stage, you **must store the API secret securely**, e.g. by writing it down or copying it in a trusted store as this is the only time the API secret will be displayed.\ \ Once created the API key and secret are immutable, however, the IP white-list and permissions can be edited at any time. {% hint style="danger" %} **If you lose your API secret or it becomes compromised you must delete the API credentials pair immediately and generate a new one. If you find out that the access to the dashboard has been compromised, please contact us immediately.** {% endhint %} # Signature How to generate the authorization signature The Signature component of the Authorization header is an **HMAC-SHA256** digest of the elements described below. | Element | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Request URI | Everything after the base URL, including query parameters if present. | | Timestamp | Current [UNIX epoch time ](https://www.unixtimestamp.com/)in milliseconds | | Request body | A [minified ](https://codebeautify.org/jsonminifier)**JSON**-serialized string of the request body. If a body is not required (e.g. request is of type GET), use an empty string. | # Code snippets Example code snippets fo signing and sending requests {% tabs %} {% tab title="PHP" %} ```php class Axom { private $apiKey; private $apiSecret; private $baseUrl = 'https://payments.axom.money'; public function __construct(string $apiKey, string $apiSecret) { $this->apiKey = $apiKey; $this->apiSecret = $apiSecret; } public function makeRequest($method, $endpoint, array $body = [], array $query = []) { $method = strtoupper($method); $qs = http_build_query($query, '', '&'); $path = ($qs == '') ? $endpoint : $endpoint . '?' . $qs; $ch = curl_init(); $jsonBody = ''; if ($method == 'POST' || $method == 'PUT' || $method == 'PATCH') { $jsonBody = json_encode($body, JSON_UNESCAPED_SLASHES); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody); } curl_setopt_array($ch, [ CURLOPT_URL => $this->baseUrl . $path, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: ' . $this->buildAuthorizationHeaderValue($path, $jsonBody) ] ]); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true); } private function buildAuthorizationHeaderValue($path, $jsonBody = '') { $timestamp = intval(microtime(true) * 1000); $signaturePayload = $path . $timestamp . $jsonBody; $signature = hash_hmac('sha256', $signaturePayload, $this->apiSecret); return "FRX-API API-Key={$this->apiKey}," . "Signature={$signature}," . "Timestamp={$timestamp}"; } } ``` {% endtab %} {% tab title="JS" %} ```javascript "use strict"; const CryptoJS = require("crypto-js"); const fetch = require("node-fetch"); const Headers = fetch.Headers; const API_KEY = process.env.API_KEY; const API_SECRET = process.env.API_SECRET; const BASE_URL = process.env.BASE_URL || "https://payments.axom.money"; function buildAuthorizationHeaderValue(path, jsonBody = "") { let timestamp = Date.now(); let signaturePayload = path + timestamp + jsonBody; let signature = CryptoJS.HmacSHA256(signaturePayload, API_SECRET); return ( `FRX-API API-Key=${API_KEY},` + `Signature=${signature},` + `Timestamp=${timestamp}` ); } function stringifyBody(jsonBody) { if (typeof jsonBody === "string") { if (jsonBody === "") { throw "Body is requried for POST, PATCH, PUT requests."; } jsonBody = JSON.stringify(JSON.parse(jsonBody)); } else { jsonBody = JSON.stringify(jsonBody); } return jsonBody; } function buildRequestOptions(method, path, jsonBody) { let requestOptions = {}; let body = ""; if (method === "POST" || method === "PUT" || method === "PATCH") { body = stringifyBody(jsonBody); requestOptions.body = body; } let authorizatonHeader = buildAuthorizationHeaderValue(path, body); let headers = new Headers(); headers.append("Authorization", authorizatonHeader); headers.append("Content-type", "application/json"); requestOptions.method = method; requestOptions.headers = headers; return requestOptions; } function makeRequest(method, path, jsonBody = "") { let url = BASE_URL + path; let requestOptions = buildRequestOptions(method, path, jsonBody); fetch(url, requestOptions) .then((response) => response.text()) .then((result) => console.log(result)) .catch((error) => console.log("error", error)); } ``` {% endtab %} {% endtabs %} # Environment ### Base endpoints: * Production environment: \*\* Key for checking the authenticity of a Axom [callback](/references/callbacks) on the production environment: ``` MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAugctje1SfC4AbVEvTjYqjOzZwkp4QdbWxhYMSekvDmtsLt2/oCE6eQnpOmLG6shZZ9YdQdD60mis3Q9j3a7YCtLNGWmr5WVaxAvxemZnNy76atH+GoGJaj19/ShMIXRDPj7AkEZfHyQylAVWNQ86LTAYz9uepiB9OUzypj1zLUalDTpzikUNNKyGYGH80UjMgwR9le9trHE7QwICvAZCPxeqq8tNSt3xYNINpVVOLjhNySbMLFJXMjz/lXtFSTbjpFiCf2/d1zEIXHQ2jlNtgHZfl/1agWG8XGKUg2RODkJ1YdDx04a4qK3ee3mYa6zj+eg52xscS0nZTjkMwA+/SE/fnV/efsS6/c+THfCMdLIRTjutQsW05rygMKvpdcBmJci7qvFV2hGDuUCiSYe/eejSFX1cCXRLJEAmTGGtUJOX0gxT46UxMtBEQdTJ+dgWh2nErmJ4mzWxkKP/aHMieUeYK+BDknwTEZoRwFmFmslGGEEo1sXSPsOnlrMid5tH67FwaGA+9ngVyUabXFe0fXaAQrOE95Zepp5gPaeeXxC5tLnZkN6CtK4hAFesrV6WWD2jJyNICZHxYe5n19n6YtnuRYA/2fl2XXAiNOCk47YnUGbRsz81VzHc4VnLpkGy+RVKxk4gz+Tjkk12m/E8KVi+mPcpvdQlfZM5j9xDGpcCAwEAAQ== ``` {% hint style="info" %} All calls to our API should start with this specific URL: **** {% endhint %} # Errors ### Format Both client and server errors are returned in the following format: ```javascript { "timestamp": 1584539613, "httpStatus": 400, "httpError": "Bad Request", "message": "Request failed validation", "path": "/api/v1/path/to/resource", } ``` ### HTTP Status Codes | Code | Meaning | Description | | ---- | ---------------------- | ------------------------------------------------------------- | | 400 | Bad request | Invalid request body or parameters | | 401 | Unauthorized | Invalid authorization token or API credentials | | 403 | Forbidden | Insufficient permissions when accessing the resource | | 404 | Not found | The requested resource doesn't exist | | 405 | Method not allowed | The endpoint does not support the supplied HTTP verb (method) | | 409 | Conflict | The resource cannot be created since it already exists | | 415 | Unsupported media type | The request's payload is not in the supported JSON format | | 500 | Internal server error | There is an issue with handling the request | | 503 | Service unavailable | System is down | # Expired payment 22 Aug 2024 A one-time payment link must have a maximum expiration time as configured by your merchant. If your payment has expired and no transaction has been recorded on the blockchain you should return to the merchant website and create a new payment link. If you have already sent the crypto transaction and are seeing the expired payment message, it might not have been broadcasted on the network. Once processed we will update the payment page as soon as it is reflected. Payments are confirmed after receiving several confirmations from the Blockchain network. The final confirmation time depends on the load on the Blockchain network and the funding you have configured. # Changelog ### 2025-01-25 * Added a rate matching functionality so that stable crypto coin rates can be exactly 1:1 matched with their fiat backing currency. ### 2024-10-19 * Minimum Deposit Processing Amount was introduced to improve the experience in cases where the actual deposit amount is lower than the amount which can effectively be processed. ### 2024-08-06 * Businesses can now choose which specific network they want to allow for any of the deposit currencies. This applies to currencies where multiple deposit networks are supported. ### 2024-07-04 * Added the ability to configure which party is responsible for covering the on-chain fees when sending out a settlement. This can be configured once for all withdrawals created from a given business on each individual withdrawal. ### 2024-05-29 * Added the ability to require an approval from a second user before sending out a withdrawal. This configuration is made once for each organisation and applies to all subsequently sent withdrawals. ### 2024-05-16 * `Solana` has been added as supported network for crypto withdrawals and deposit for `USDC.` Furthermore we also added `SOL` as deposit and withdrawal currency. ### 2024-04-01 * Added the withdrawal approvals feature allowing admin users to have additional control over crypto withdrawals by manually approving or rejecting them. ### 2023-06-16 * Adding statuses to deposits in payments. Changes to the response are visible under [Get payment data](/references/crypto-payments/get-deposit-data). ### 2023-02-09 * Adding a network field as a mandatory one to the post request for whitelist address creation. Currencies and networks pairs available are the same as for our [withdrawals](/references/crypto-withdrawals/initiate-withdrawal-request#supported-networks). ### 2022-09-26 * Introducing deposits through side chains. To take advantage of this new feature changes should be made to either the [Request crypto payment](/references/crypto-payments/initiate-a-crypto-payment-request) or the [Add payment details](/references/crypto-payments/submit-deposit-data) payload. **List of currencies and their supported deposit networks** | Currency | Network | | -------- | -------------------------------------------------------------------- | | USDC | Ethereum chain (ETH), Binance Smart Chain (BSC) and Tron Chain (TRX) | | ETH | Ethereum chain (ETH) and Binance Smart Chain (BSC) | | USDT | Ethereum chain (ETH), Binance Smart Chain (BSC) and Tron Chain (TRX) | | BTC | BTC | | BCH | BCH | | LTC | LTC | | XRP | XRP | | XLM | XLM | | LINK | ETH | ### 2022-08-21 * Changes to the accepted values for the network field for [crypto withdrawals](/references/crypto-withdrawals/initiate-withdrawal-request) * `MAIN` is no longer a valid value for the network field instead, use one of the values described on the Request crypto withdrawal page. * Added a maximum amount the can be withdrawaln depending on the network and the respective cryptocurrency. Information can be found in the [metadata endpoint](/references/crypto-withdrawals/request-withdrawal-metadata). * Different response fields when sending [payment details](/references/crypto-payments/submit-deposit-data). For payments with `LTC` as their `depositCurrency` the response will only include a `walletAddress` field. We are removing the `ltc3Address`field and changing the address type that is returned in the `walletAddress`. * Changes to our [metadata endpoint](/references/crypto-withdrawals/request-withdrawal-metadata). * Added a new field `maxAmount` to the response. It will hold the maximum amount that can be withdrawn in the respective cryptocurrency. * The changes to network names that are described on the [crypto withdrawals](/references/crypto-withdrawals/initiate-withdrawal-request) page will also take affect here (see table below and [example response](/references/crypto-withdrawals/request-withdrawal-metadata)). * Changes to the network field in the [validate address](/references/crypto-addresses/validate-address) endpoint #### List of currencies and their old/new supported withdrawal networks
CurrencySupported networks (From 2022-08-15)Supported networks (To 2022-08-15)
BTCBTCMAIN
BCHBCHMAIN
ETHETH, BSCMAIN, BSC
LINKETHMAIN, BSC
LTCLTCMAIN
USDCETH, BSC, TRXnot supported
USDTETH, BSC, TRXMAIN, BSC, TRX
XLMXLMMAIN
XRPXRPMAIN
### 2022-06-30 #### Reducing the list of supported currencies * Axom will cease processing (deposits and withdrawals) of the following currencies **as of 2022-07-15**: ``` Basic Attention Token (BAT), Bancor (BNT), Civic (CVC), Enjin Coin (ENJ), Mithril (MITH), Metal (MTL), OmiseGo (OMG), Augur (REP) ``` Reason for delisting is low processing volumes and low liquidity on the markets. ### 2022-05-19 * [Withdrawal ](/references/crypto-withdrawals/initiate-withdrawal-request)request body and response body * New supported network - `TRX` ### 2022-05-09 * [Withdrawal ](/references/crypto-withdrawals/initiate-withdrawal-request)request body and response body * New optional field for the request body - `network` * New field in the response body - `network` * [Get cryptocurrency metadata](/references/crypto-withdrawals/request-withdrawal-metadata) * New endpoint that provides metadata for all supported cryptocurrencies * [Validate address](/references/crypto-addresses/validate-address#validate-address-1) * We are deprecating the old endpoint and introducing a new one: * `POST /api/v1/addresses/validate` is being **Deprecated** * `GET /api/v1/currency/:withdrawalCurrency/network/:network/address/:address/valid` - **New** * [Exchange rates](/references/currencies-and-fees/get-exchange-rates-any-currency-to-any-currency) for any currency * New endpoint that provides rates for currencies(fiat and crypto) and supports comma-separated values. ### 2021-11-08 * [Withdrawal callback](/references/callbacks/withdrawal-completed) request body * New status -`BLOCKED` * New field - `txAddressOwner` * [Get business withdrawals ](/references/business/get-business-withdrawals)response * New status - `BLOCKED` * New fields - `addressOwner`, `sourceRiskEntities`, `destinationRiskEntities` # Crypto payments In this section we'll go through the endpoints you'll need to execute crypto payments on your website. You can make use of our hosted checkout experience or spin-off a custom UI. ## Guidelines for checkout integration in Iframe To provide the best user experience, we strongly recommend that you use the following minimum dimensions when displaying our checkout: * Height: 640px * Width: 320px Our checkout uses the clipboard API to allow users to easily copy the Amounts, Addresses and Transaction ID that are displayed on the screen. This action might be prevented by Chrome and other browsers, so to allow the copying of text with a single button simply add the `allow="clipboard-write"` property to your `