Login

Introduction Last updated: 09 Feb 2024 01:33:26 PM

Welcome to the token payments documentation, below show cases all the available API requests are documented below.

Pre-Payout Token Registration

Before initiating a payout, it's essential to ensure your token is registered and configured within our platform. Please visit the Token Management Panel to define your token. This process involves inputting the token's contract address, selecting its network, and specifying its decimals. Once submitted, you will receive a token_id, which is crucial for proceeding with payouts for that specific token.

After completing the token registration, visit the Payout Management Panel to find your wallet identity. You will need to provide this address as wallet_identity, which will be used to send the token to the receiver's wallet. Ensure your wallet is loaded with the appropriate token and the native coin (BNB/ETH/MATIC) to cover transaction fees. This setup is a one-time process, simplifying future payments.

Initiate Payout

This endpoint allows you to initiate a payout transaction to transfer tokens to a specified receiver address.

URL

https://tokenpayments.app/api/initiate-payout?wallet_identity=wallet_address&token_id=token_id&to_address=receiver_address&amount=amount

Method

GET

Authentication

Key: API Key

Secret: API Secret

Query Parameters

Parameter Description
wallet_identity The wallet address initiating the payout.
token_id The identifier of the token being transferred.
to_address The receiver's wallet address.
amount The amount of tokens to transfer. 
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://tokenpayments.app/api/initiate-payout?wallet_identity=wallet_address&token_id=tokenID&to_address=receiver_address&amount=amount',
  'headers': {
    'key': 'key',
    'secret': 'secret'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests

url = "https://tokenpayments.app/api/initiate-payout?wallet_identity=wallet_address&token_id=tokenID&to_address=receiver_address&amount=amount"

payload = {}
headers = {
  'key': 'key',
  'secret': 'secret'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://tokenpayments.app/api/initiate-payout?wallet_identity=wallet_address&token_id=tokenID&to_address=receiver_address&amount=amount',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'key: key',
    'secret: secret'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

{"response":"success","reference_id":"reference_id"}

Get Payout Status

This endpoint makes an HTTP GET request to retrieve the status of a payout using the provided reference ID. It provides detailed information about the payout, including the transaction hash, amount, receiver's address, and more.

URL

https://tokenpayments.app/api/get-payout-status?reference_id=your_reference_id

Method

GET

Authentication

Key: Your API Key

Secret: Your API Secret

Request Parameters

Parameter Type Description
reference_id string The reference ID of the payout.

Response Structure

The response will include details of the payout status as follows:

{
    "response": "Response Message",
    "reference_id": "1234567890",
    "transaction_hash": "0x...",
    "amount": 100,
    "receiver_address": "0x...",
    "status": 1,
    "verified": 1,
    "token_address": "0x...",
    "token_name": "TokenName",
    "network": "Ethereum"
}

Notes on Response Fields and Security

Status and Verified Fields:

  • Status = 0: Pending transaction. The transaction is awaiting processing.
  • Status = 1: Transaction processed on-chain. Indicates the transaction was successfully executed on the blockchain.
  • Status = 2: Transaction unable to proceed due to lack of gas fees or insufficient token balances.
  • Verified = 0: Corresponds to a pending transaction (status is 0).
  • Verified = 1: Indicates the transaction processed on-chain was successful.
  • Verified = 2: Transaction failed on-chain due to errors or exceptions.

Transaction Hash: The transaction_hash field may be null if the transaction is still pending or the hash is not yet available.

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://tokenpayments.app/api/get-payout-status?reference_id=1234567890',
  'headers': {
    'key': 'key',
    'secret': 'secret'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests

url = "https://tokenpayments.app/api/get-payout-status?reference_id=1234567890"

payload = {}
headers = {
  'key': 'key',
  'secret': 'secret'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://tokenpayments.app/api/get-payout-status?reference_id=1234567890',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'key: key',
    'secret: secret'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

{
    "response": "",
    "reference_id": "",
    "transaction_hash": null,
    "amount": 0,
    "receiver_address": "",
    "status": 0,
    "verified": 0,
    "token_address": "",
    "token_name": "",
    "network": ""
}