Heropayments API deposits/payouts flow

Here you can find the workflow and detailed explanation of API requests that let you process crypto payments on your platform.

We are partnered with cashiers like:

Devcode/Payments IQ: https://payments-iq.com

Praxis: https://praxis.tech

And others like Corefy, FXbo and etc.

If you have any questions or you want to test our solution, feel free to reach out to us via support@heropayments.io

Authentication

To use Heropayments API, you should do the following:

Import our collection of API methods in Postman;

Insert API keys in Postman;

Send a request.

DO NOT SHARE YOUR API/SECRET KEY WITH ANY 3RD PARTIES!

Recommended integration flow

DEPOSIT FLOW

A user wants to top up the account:

UI - Add a "top up with crypto" method to your platform;

UI - Ask your user to choose a cryptocurrency for the deposit and specify the amount to create a deposit transaction in the user's account currency (transaction amount is optional);

API - To get estimated deposit amount for the selected cryptocurrency use GET "Get estimated price" and to get minimum deposit amount use GET "Minimum payment amount (V2)';

UI - Display the minimum deposit amount to your user and inform them that a lower amount won't be processed;

API - To create the transaction for deposit and to generate a deposit address call the POST "Create a deposit (V2)" / "Create a deposit (Custody)";

UI - Show the generated deposit address to your user and ask to send the payment there. Once Heropayments accepts the deposit, it will be automatically converted into your balance currency and credited to your Merchant's account in our system.

API - Get the transaction status either via our callbacks or manually via GET "Payment status check by id (V2)" / "Payment status check by id (Custody)";

All deposits are accumulated on your Merchant's account USDT wallet in our system. Call GET "Get balance" method to check the balance. You can get a settlement upon the request.

Our multiple deposit processing feature increases the conversion rate of deposits. It will let your users pay twice or more to the same deposit address without visiting the cashier.

The list of possible API errors - https://docs.google.com/spreadsheets/d/16R_DIBU_3TIwKG7j6e2Iq6smyWXvSK5kWRYPpyPwym4/edit?gid=0#gid=0

WITHDRAWAL FLOW (PAYOUTS TO USERS)

First, you can view the available balance using GET “Get balance (V2)” / "Get balance (Custody)".

To create a withdrawal, use POST “Create a withdrawal (V2)" / "Create a withdrawal (Custody)" request method. Specify the address, currency and amount for the withdrawal.

You can monitor transaction status via our callbacks or manually, using GET "Payment status check by id (V2)" / "Payment status check by id (Custody)".

UI - Add the withdrawal with crypto option to your platform;

UI - Ask your user to choose a cryptocurrency for withdrawal;

API - Get the estimated amount for the selected currency by using POST "Get estimated price" and minimum withdrawal amount by using "Minimum payment amount (V2)";

UI - Display the minimum withdrawal amount to your user and make clear that a lower amount won't be processed;

UI - Ask the user to specify a crypto wallet address to receive a withdrawal;

API - Call POST "Create a withdrawal (V2)" / "Create a withdrawal (Custody)";

API - Get the transaction status via our callbacks or manually, by calling GET "Payment status check by id (V2)" / "Payment status check by id (Custody)" method to receive actual information about the withdrawal request.

Daily withdrawal limits:

To elaborate on this, withdrawal limits are made to prevent situations when a merchant's account might accidentally run out of funds or overpay to a particular user.

We have 2 types of daily limits:

Merchant withdrawal limit – for the entire merchant account per day

Customer withdrawal limit – for each customerID per day

To set up the limits, reach us via partners@heropayments.io or contact your personal account manager.

The list of possible API errors -

https://docs.google.com/spreadsheets/d/16R_DIBU_3TIwKG7j6e2Iq6smyWXvSK5kWRYPpyPwym4/edit?gid=0#gid=0

API Request signing

In order to authenticate API requests, you will have to use your API Key & API Secret (which can be found in your admin panel - https://app.heropayments.io/api or https://my.heropayments.io/settings/api-keys to calculate the request signature using the HMAC-SHA512 algorithm.

You have to pass the request body as the data parameter and your API Secret as secretKey parameter. After calculating the signature, you have to attach it to the x-api-sign header.

POST

For all requests with body - you should sign body and specify it to x-api-sign header.

GET

For all GET requests - you should sign query string without question mark(?). For example:
https://api.heropayments.io/v2/method?foo=bar should be signed string foo=bar

If a request doesn't have a query string, you should sign an empty string:

yourSigningFunction('')

Then specify it to x-api-sign header.

PLEASE NOTE

To make sure you calculate the correct signature, you have to normalize the JSON data:

it should not contain any spaces or newlines in it

it should not have any zero-padded numbers (from both sides) unless they're quoted strings (e.g. 001.10 is invalid, "001.10" is valid)

Easiest way to do this automatically with Javascript:
JSON.stringify(JSON.parse(yourJsonString))

You can check if the created signature is valid or not via our signature validation tool - https://codepen.io/ethan-reynolds-9823/full/jEOVRbV

Examples

Postman pre-request script (V2):

typescript

const crypto = require('crypto-js');
let payload = '';
const secret = pm.environment.has('api-secret')
    ? pm.environment.get('api-secret')
    : pm.variables.has('api-secret')
        ? pm.variables.get('api-secret')
        : pm.globals.has('api-secret')
            ? pm.globals.get('api-secret')
            : pm.collectionVariables.has('api-secret')
                ? pm.collectionVariables.get('api-secret')
                : console.error(new Error('api-secret is missing'));
try {
    switch (pm.request.method) {
        case 'POST': 
            payload = JSON.stringify(JSON.parse(pm.request.body.toString()));
            break;
        case 'GET':
            payload = pm.request.url.query.toString();
            break;
    }
} catch {
    console.error(new Error('Cant decode JSON body'))
}
console.log('payload', payload);
const sign = crypto.HmacSHA512(payload, secret).toString();
pm.request.headers.upsert({
    key: 'x-api-sign',
    value: sign,
});

Postman pre-request script (Custody):

typescript

const crypto = require('crypto-js');
let payload = '';
const secret = pm.environment.has('api-secret-custody')
? pm.environment.get('api-secret-custody')
: pm.variables.has('api-secret-custody')
? pm.variables.get('api-secret-custody')
: pm.globals.has('api-secret-custody')
? pm.globals.get('api-secret-custody')
: pm.collectionVariables.has('api-secret-custody')
? pm.collectionVariables.get('api-secret-custody')
: console.error(new Error('api-secret-custody is missing'));
try {
payload = JSON.stringify(JSON.parse(pm.request.body.toString()));
} catch {
console.error(new Error('Cant decode JSON body'))
}
const sign = crypto.HmacSHA512(payload, secret).toString();
// console.log(secret, sign);
pm.request.headers.upsert({
key: 'x-api-sign',
value: sign,
});

An example in node.js (backend):

typescript

import crypto from 'crypto';
function calculateSignature (data: string | Buffer, secretKey: string | Buffer): string {
    return crypto
      .createHmac('SHA512', secretKey.toString())
      .update(data.toString())
      .digest('hex');
}

An example in C#:

csharp

using System;
using System.Security.Cryptography;
using System.Text;
public class HmacHelper
{
    public static string CalculateSignature(object data, object secretKey)
    {
        byte[] dataBytes;
        byte[] secretKeyBytes;
        if (data is string dataString)
        {
            dataBytes = Encoding.UTF8.GetBytes(dataString);
        }
        else if (data is byte[] dataBuffer)
        {
            dataBytes = dataBuffer;
        }
        else
        {
            throw new ArgumentException("Data must be a string or byte array");
        }
        if (secretKey is string secretKeyString)
        {
            secretKeyBytes = Encoding.UTF8.GetBytes(secretKeyString);
        }
        else if (secretKey is byte[] secretKeyBuffer)
        {
            secretKeyBytes = secretKeyBuffer;
        }
        else
        {
            throw new ArgumentException("Secret key must be a string or byte array");
        }
        using (var hmac = new HMACSHA512(secretKeyBytes))
        {
            var hashBytes = hmac.ComputeHash(dataBytes);
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }
    public static void testStrings()
    {
        string data = "example data";
        string secretKey = "your-secret-key";
        string signature = CalculateSignature(data, secretKey);
        Console.WriteLine("Signature: " + signature);
    }
    public static void testBytes()
    {
        byte[] data = System.Text.Encoding.UTF8.GetBytes("example data"); // Data in buffer form
        byte[] secretKey = System.Text.Encoding.UTF8.GetBytes("your-secret-key"); // Key as a buffer
        string signature = CalculateSignature(data, secretKey);
        Console.WriteLine("Signature: " + signature);
    }
    public static void Main()
    {
        testStrings();
        testBytes();
    }
}

An example in PHP:

php

$apiKey = 'YOUR_KEY';
  $apiSecret = 'YOUR_SECRET';
  $apiUrl = 'https://api.heropayments.io/v2/payments';
  $message = json_encode(
    array(
        'payCurrency' => 'trx',
        'priceCurrency' => 'usd',
        'priceAmount' => '1000',
        'customerId' => '123',
        'customerEmail' => 'test@test.com',
        'externalOrderId' => '100500',
        'callbackUrl' => 'https://example.com/callback?orderId=100500'
    ),
    JSON_UNESCAPED_SLASHES
  );
  $sign = hash_hmac('sha512', $message, $apiSecret);
  $requestHeaders = [
    'x-api-key:' . $apiKey,
    'x-api-sign:' . $sign,
    'Content-type: application/json'
  ];
  $ch = curl_init($apiUrl);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $message);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $requestHeaders);
  $response = curl_exec($ch);
  curl_close($ch);
  var_dump($response);

An example in Python:

python

#Python 3.8
import requests
import json
import hashlib
import hmac
url = "https://api.heropayments.io/v2/payments"
def generate_signature(data):
  key = "YOUR_SECRET" 
  key_bytes= key.encode() 
  data_bytes = data.encode()
  return hmac.new(key_bytes, data_bytes, hashlib.sha512).hexdigest()
payload = {
    "payCurrency":"trx",
    "priceCurrency":"usd",
    "priceAmount":1000,
    "customerId":"123",
    "externalOrderId":"100500",
    "customerEmail":"test@test.com",
    "callbackUrl":"https://example.com/callback?orderId=100500",
    "fiat": True,
}
payload = json.dumps(payload, separators=(',', ':'))
headers = {
  'x-api-key': 'YOUR_KEY',
  'Content-Type': 'application/json',
  'x-api-sign': generate_signature(payload)
}
response = requests.request("POST", url, headers=headers, data=payload)

An example in browser:

typescript

import hmacSHA512 from 'crypto-js/hmac-sha512';
function calculateSignature (data: string | Buffer, secretKey: string | Buffer): string {
    return hmacSHA512(data.toString(), secretKey.toString());
}Also you can use Postman pre-request script:

Callbacks

Callbacks are used for notifications when transaction status is changed. To use them, you should complete the following steps:

Get the secret key in "API" section at the admin panel;

When you call POST "Create a deposit (V2)" / "Create a deposit (Custody)" or POST "Сreate a withdrawal (V2)" / "Create a withdrawal (Custody)" request, insert your URL address in "callbackUrl" field to get notifications.

You will receive all the parameters at the URL address you specified in (2) by POST request. The POST request will contain x-api-sign parameter in the header. The body of the request is similar to GET “Payment status check by id (V2)” / "Payment status check by id (Custody)" response body, but not identical;

Convert the response body to string using JSON.stringify;

Sign a string with a secret key with HMAC-SHA512 algorithm;

Compare the signed string from the previous step with the x-api-sign stored in the header of the callback request. If these strings are identical, the system works properly. Otherwise, contact us via support@heropayments.io to solve the problem.

Callback notification example

Examples of the responses::

V2 conversion flow: GET "Payment status check by id (V2)”

Custody flow: GET "Payment status check by id (Custody)"

Fallbacks

We strongly recommend you to back up callback services by using GET "Payment status check by id (V2)” / "Payment status check by id (Custody)" to receive the same info about payments as you get from the callback notification.

Payment Statuses - (V2 flow)

The transaction's status describes what is happening to the funds at any given moment and their current state.

For the detailed description of the statuses, please refer to the GET "Payment status check by id (V2)” method.

Deposit statuses

In progress:

waiting

confirming

exchanging

hold

Failed or unsuccessful (suspend the transaction on your end):

failed

refunded

expired

Successful (complete the deposit on your end by updating the balances, etc.):

sending

finished

Withdrawal statuses

In progress:

waiting

confirming

exchanging

hold

sending

expired

Failed or unsuccessful (suspend the transaction on your end):

failed

refunded

Success (complete the withdrawal on your end by updating the balances, etc.):

finished

Payments statuses - (Custody flow)

For the detailed description of the statuses, please refer to the GET "Get custody payment status” method.

Deposit statuses

In progress:

pending

processing

hold

Failed or unsuccessful (suspend the transaction on your end):

failed

expired

Success (complete the withdrawal on your end by updating the balances, etc.):

finished

Withdrawal statuses

In progress:

pending

processing

hold

Failed or unsuccessful (suspend the transaction on your end):

failed

refunded

Success (complete the withdrawal on your end by updating the balances, etc.):

finished

Multiple deposit processing

In case a customer deposits to the same payAddress twice or more, it will still be processed.

Each customer’s transfer is a new payment. As soon as each payment has to have its own unique externalOrderId, we add a new field "sequence" to differentiate the subsequent payments.

The initial payment receives an original externalOrderId and the "sequence" field remains unchanged.

For the subsequent payments, "sequence" field gets a value.

Example for the first payment:

externalOrderID: 1254435345456456

sequence: original

Example for the second and further payments:

externalOrderID: 1254435345456456

sequence: 4fb7defa35a056ecc64fc74ea97ef90f (new unique ID)

A customer may save the deposit address on their side and send the funds without going through the process all over again.

In cases of multiple deposits, callbacks are sent to the callbackUrl of the initial payment. Our support may also notify you in case of multiple deposits.

Deposit status:

A new generated deposit-transaction remains in the status “waiting” for 4 hours (TTL) after the creation. If the transaction is not completed within this period, it receives status “expired”. If there is no new empty “waiting” transaction, we will generate a multi-deposit for an incoming payment.

Action required: adjust your system to field sequence to handle the callbacks of multiple deposits.

Static deposit address per each customer

Methods to generate a deposit transaction:

V2 flow: v2/payments, v2/payments-address

Custody flow: custody/deposit

We generate a deposit address for each unique customerId. The next time you create a deposit, your customer will receive the same deposit address.

To make the feature work, we will need to update your account settings. Please contact your personal account manager or reach us via support@heropayments.io

If a customer sends a deposit without creating an order on your side, it will still be processed, but considered as a multiple deposit.