Custom Integration APIs and Webhook

Integrate the APIs from AXpay for Business into your own apps!

Steps to Take Before Integration:

Please note: To start integrating APIs, you have to create your app and generate a private key through the web portal first.

Example of what an app looks in the AXpay for Business portal:

Generate a Private Key Through AXpay

A private key will be provided to you when you create a new app in AXpay for Business. This private key should be kept securely. You can generate or regenerate your private key anytime by clicking the Regenerate Private Key button in the platform portal. Once you regenerate a new private key, the old one will be disabled.

API Authentication

APIs are authenticated using dynamic API keys that are generated by signing a piece of data using the private key generated in the previous step. You will need both your private key and Client ID associated with your the App to generate the API key.

Sample NodeJS Code for Generating API Key

const crypto = require("crypto");
// Function to generate API Key
const generateApiKey = ({ privateKey, appClientId }) => {
  const signature = crypto.sign("sha256", Buffer.from(appClientId), {
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_PSS_PADDING
  });
  console.log("api-key: ", signature.toString("base64"));
  return { "api-key": signature.toString("base64") };
};

Making API Calls

Once you have generated your own API key, you can call the following API into your own backend without the need for web token authentication:

Get Transactions by App Client ID

GET https://axpay-api.axiacoin.com/api/appClient/:appClientId/transaction

Path Parameters

Name	Type	Description
appClientId*	String	Client ID of app, can be found in web page

Query Parameters

Name	Type	Description
limit	Number	Limit the number of records returned for pagination
offset	Number	Return record with an offset for pagination
orderId	String	Filter transactions by orderId
rewardType	String	Filter transactions by rewardType, CASH_BACK or LOYALTY_POINT
webhookStatus	String	Filter transactions by webhookStatus
amountGte	Number	Amount greater than or equal to
amountLte	Number	Amount less than or equal to
rewardRateGte	Number	Reward rate greater than or equal to
rewardRateLte	Number	Reward rate less than or equal to
createdAtGte	Number	Created at greater than or equal to in Unix timestamp millisecond
createdAtLte	Number	Created at less than or equal to in Unix timestamp millisecond
fromEmail	String	Filter transactions by fromEmail
orderBy	String	Order the returned transaction by fields of createdAt, amount or rewardRate
order	String	asc or desc

Headers

Name	Type	Description
api-key*	String	api key of app generated by the method above

200: OK Success

{
    "statusCode": 200,
    "message": "Success",
    "data": {
        "appTransactions": {
            "totalCount": 152,
            "limit": 5,
            "offset": 0,
            "data": [
                {
                    "id": "04e75ec0-ec7d-411e-9003-5b036e8b3d38",
                    "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
                    "fromUserId": "1eaa28e8-83e4-40c3-a93f-2dd912994e15",
                    "rewardType": "LOYALTY_POINT",
                    "rewardRate": "0.5",
                    "amount": "5",
                    "paymentTransactionId": "3822c1aa-cff9-4e04-8f46-4b3caf6b97ba",
                    "cashbackTransactionId": null,
                    "earnPointsTransactionId": "a2bfb5de-4489-49e7-b4bf-f48be3a3b09c",
                    "usePointsTransactionId": null,
                    "webhookStatus": null,
                    "webhookStatusCode": null,
                    "orderId": "10086",
                    "fromEmail": "[e-mail]",
                    "appName": "Da Da Store",
                    "createdAt": "2022-05-10T16:14:56.072Z",
                    "updatedAt": "2022-05-10T16:14:56.072Z"
                },
                {
                    "id": "698b6fe3-c5e4-4756-aa68-4a7733ef269a",
                    "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
                    "fromUserId": "1eaa28e8-83e4-40c3-a93f-2dd912994e15",
                    "rewardType": "LOYALTY_POINT",
                    "rewardRate": "0.5",
                    "amount": "1",
                    "paymentTransactionId": "440d2c3f-195c-462d-a6d6-d5109b3329cd",
                    "cashbackTransactionId": null,
                    "earnPointsTransactionId": "c60a8ad3-c094-43cd-8ad7-2f71a2cfa10c",
                    "usePointsTransactionId": null,
                    "webhookStatus": null,
                    "webhookStatusCode": null,
                    "orderId": "145",
                    "fromEmail": "[e-mail]",
                    "appName": "Da Da Store",
                    "createdAt": "2022-04-12T16:37:21.871Z",
                    "updatedAt": "2022-04-12T16:37:21.871Z"
                },
                {
                    "id": "f0bfdcb1-7df6-40d4-920b-713ca75eeb2d",
                    "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
                    "fromUserId": "1eaa28e8-83e4-40c3-a93f-2dd912994e15",
                    "rewardType": "LOYALTY_POINT",
                    "rewardRate": "0.5",
                    "amount": "10",
                    "paymentTransactionId": "46bf4e31-79ce-4411-8f23-c1c7ed4d99c3",
                    "cashbackTransactionId": null,
                    "earnPointsTransactionId": "5187ef37-a50c-4d41-802c-452a0cb680bd",
                    "usePointsTransactionId": null,
                    "webhookStatus": null,
                    "webhookStatusCode": null,
                    "orderId": "145",
                    "fromEmail": "[e-mail]",
                    "appName": "Da Da Store",
                    "createdAt": "2022-04-12T16:16:06.088Z",
                    "updatedAt": "2022-04-12T16:16:06.088Z"
                },
                {
                    "id": "e5c75e1a-7db8-41f2-a505-8264a00eeede",
                    "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
                    "fromUserId": "1eaa28e8-83e4-40c3-a93f-2dd912994e15",
                    "rewardType": "LOYALTY_POINT",
                    "rewardRate": "0.5",
                    "amount": "10",
                    "paymentTransactionId": "e2f04a4e-327c-4771-a93d-c6b9b4a46960",
                    "cashbackTransactionId": null,
                    "earnPointsTransactionId": "371d5720-451d-4223-ac6a-be34b390fb04",
                    "usePointsTransactionId": null,
                    "webhookStatus": null,
                    "webhookStatusCode": null,
                    "orderId": "145",
                    "fromEmail": "[e-mail]",
                    "appName": "Da Da Store",
                    "createdAt": "2022-04-12T16:15:55.365Z",
                    "updatedAt": "2022-04-12T16:15:55.365Z"
                },
                {
                    "id": "b9980be5-af90-4c38-a53b-48e158f1fec6",
                    "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
                    "fromUserId": "1eaa28e8-83e4-40c3-a93f-2dd912994e15",
                    "rewardType": "LOYALTY_POINT",
                    "rewardRate": "0.5",
                    "amount": "10",
                    "paymentTransactionId": "2ad21f1e-8f66-4d13-90a8-58450dc4d270",
                    "cashbackTransactionId": null,
                    "earnPointsTransactionId": "0553dac7-b64f-4225-b16a-9414116b16b4",
                    "usePointsTransactionId": null,
                    "webhookStatus": null,
                    "webhookStatusCode": null,
                    "orderId": "145",
                    "fromEmail": "[e-mail]",
                    "appName": "Da Da Store",
                    "createdAt": "2022-04-12T16:15:39.726Z",
                    "updatedAt": "2022-04-12T16:15:39.726Z"
                }
            ]
        }
    },
    "debug": null
}

400: Bad Request Invalid query params example

{
    "statusCode": 400,
    "message": "Invalid order by",
    "data": null,
    "debug": false
}

401: Unauthorized Authorization fail if api-key does not match with appClientId

{
    "statusCode": 401,
    "message": "Unauthorized: App authentication failed",
    "data": null,
    "debug": null
}

Generate Payment Link

You can generate an instant payment link through the AXpay for Business platform. To integrate this function into your own app, you need to use the app-specific private key to create the signature. The supported currencies include: "AXC", "CAD", "USD", "EUR", "CNY", "AUD", "JPY", "HKD", "GBP", "INR". The user will be deducted equivalent amount of AXC when they create the transaction.

// Example NodeJS code for generating payment link
const moment = require("moment")
const crypto = require("crypto")

// You should copy paste the exact same private key from AXpay Business web page here
const privateKey = "-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDAqCZ9dY5tBPb+\nnED3ZVBlz9wxRJ+7foaFon2umUY4GJ9tFIOBr+oOMJhqdrwS7usWCo0TXklFMqyC\nLafndh70TBt8L7jbe/RnG+IUZF+PsC7YuHRJ5LdPT+HYbuHqPtog3qjma+fg6Wok\nBMMT3dB2KfyyCl4PxYBNGPto4cFRQnABo4K29mlFwln9l00QC/+fPzDPdg7Fjygi\nZ77MC7yiWrTtxmFjsMOzuw9oaYr1kEDxdsmVRd4/XB4xRe8lEw60B91l/navBCkW\n2h2xYuQr7LXctdvBnfPIOQK9VofRoYEjKQB8z3V3W4nSciMmYawJnGlLAEjw1nOH\nXbzoRgVlAgMBAAECggEALK+T5eu7clwBckMJ6pgsUsEowKC7MAED8MEkx7ezitVj\nPSjR6+XCszHgWGlb7ERQcNdXq5NmCU/cpYEzfcNvIJj6kw56oSYaJURZZwN1Ct4B\nr7DxACa1wga0SsBFVFDpxU//+xoyOX/KZ7pXCSec75uDikRPVvcncDqILeaXMWKB\nSvIxWM6QCUhsv2jn2AIGqsmuMitNfgZBqP9AjFBqbpmsgDExNsMTHYDZXc4TXhMY\nyuOgiYTdfZH4VUU/0nhvqrqiqqHf0sVbYdl+DufJBGINeBBOzaQBsqKTVRG3gGDp\nMG9E4RcGo6587U0tPYccKf0s09lp1041AKfzkZoiYQKBgQDvSZvDefTSchjmhCaQ\nozl+ta34q2wNLbyubZ4I/iYRV3th1+Fq+DVy4hauBJDks2yX29hL790LPGyoC/BN\n0bJIK5YeEB8OV/PSwKUlcdNsUsjpMZyVY4TjOMybz0b0ZG6dm/nmwu0tORZWaL/w\nQVr/Yk1VTXOXoLm6TCnbxzsPKQKBgQDOHMxx54ony/UzjHn+i1chw40gkN/CA0Wf\nZF+nOi90K+8ExvLvC1Ti+OHaLfKZOIyIF9oVe2sHwAkCzDxd+7denwozyVNRBXMF\n3fKM5aYjL4hxm2xrzlRbLAGlxQkMfrCL90UbPFpLs1jG018hQBAGwE/juUWpmsAt\nVdzbsmtX3QKBgAmsBwDCuDOdawY+RzTHdDZ773lCrI5nz92ZDq88XpuK1rDgwfrJ\n55cqLlKAWr7zxarptvdyzZN7sMSmHuN2W2dxY5L5gdfZlEBriwFVdX9GZVqPp82e\nBSwOCq8tlKeiO5phSJucO2v9h7qcZ021xpDWD1woUkjJtVgjZfm9NtTpAoGALBlR\nTNWjY5xp3BukRmf9voWefmdA2Lvme5H4PUlfudVkkHsYozijcuSZPhsymsHUn5Gq\n4YnEfqYBx413JQykUSRqBGaA4wbtc0XnjWndQA39fYEpk29T8SXbPGKJ6xh4IZpI\nOOmS0DuRNQkog263fxpKfYi4dO9dStXiKUdlXCkCgYAaOYRlXUe2TrueTCwevIQB\nnyFpI/3ixgiTbkDRar1NZtRZupPSXRZ4pHZ93Ke8gNgHYdxICCjhpEBVlJXo8wjt\nvo1MM6FjCCBUxc5BUqf1a52CYI+PSAyNh5dBmcL7tzl8tlLJCGt/bSlxnyeH/W0V\npoMt2RW9e1G570lJjxj0cw==\n-----END PRIVATE KEY-----\n";

// the order of the object has to be exactly same like this
const payload = {
  appClientId: "tmoXdF4gUAi4SEcA2Z6pZx",
  amount: 5,
  orderId: "123",
  expiredDate: "Tue, 24 May 2022 17:50:35 GMT",
  currency: "CAD"
};

const generatePaymentLink = async ({ privateKey, payload }) => {
  const DATE_RFC2822 = "ddd, DD MMM YYYY HH:mm:ss [GMT]";
  const currentTime = moment().format();
  const unixTimeStamp = moment(currentTime).format("X");
  const RFCTime = moment(currentTime).utc().format(DATE_RFC2822);
  const requestBody = JSON.stringify(payload);
  const hashString = crypto.createHash("sha256").update(requestBody).digest("hex");
  const nonceString = await randomString(32);
  const canonicalString = `POST,application/json,/api/app/${payload.appClientId}/transaction,${hashString},${nonceString},${unixTimeStamp}`;
  const signature = crypto.sign("sha256", Buffer.from(canonicalString), {
    key: privateKey,
    padding: crypto.constants.RSA_PKCS1_PSS_PADDING
  });
  const paymentLink = `https://axpay.axiacoin.com/pay?type=ONLINE_APP&signature=${signature.toString(
    "base64"
  )}&nonceString=${nonceString}&date=${RFCTime}&appClientId=${payload.appClientId}&amount=${
    payload.amount
  }&orderId=${payload.orderId}&expiredDate=${payload.expiredDate}&currency=${payload.currency}`;
  return { paymentLink: encodeURI(paymentLink) };
};

const randomString = async (length) => {
  let result = "";
  let characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  let charactersLength = characters.length;
  for (let i = 0; i < length; i++) {
    result += characters.charAt(Math.floor(Math.random() * charactersLength));
  }
  return result;
};

//Run function to generate link
generatePaymentLink({privateKey, payload})

Webhook URL

For each app, you can define a Webhook URL and a corresponding API key through the AXpay for Business portal. Once a transaction is completed for the corresponding app, the system will call the Webhook URL to notify you through your own customized application.

Request Example

The following example shows how a Webhook URL is called by AXpay for Business:

curl --location --request POST 'https://yourWebhookUrl' \
--header 'api-key: yourAPIKey' \
--header 'Content-Type: application/json' \
--data-raw '{
 {
   "id": "5884c2b4-b380-465f-8c1a-b5aa17a49f25",
   "appId": "543bb062-1090-485a-a03c-47cebeb613b8",
   "rewardType": "CASH_BACK",
   "rewardRate": "0.5",
   "amount": "2",
   "usePointsAmount: "
   "orderId": "132",
   "fromEmail": "[e-mail]",
   "appName": "AXIA Business Demo Store",
   "createdAt": "2022-03-30T22:02:29.582Z",
   "updatedAt": "2022-03-31T15:16:36.449Z"
 },
}'

Webhook Status

AXpay for Business will call the Webhook URL through 5 attempts (5 seconds per attempt until successful) for each transaction. If a status code of 200 is received, the Webhook status will be COMPLETED. If it does not succeed within 5 attempts, the Webhook status will show that it has FAILED. The "webhookStatusCode" field records the response status code for each attempt.