REST API Overview

HeroPay provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their HeroPay account. Using the HeroPay API, clients can create and manage invoices, and much more.

Concepts

Api Contracts

HeroPay considers the following types of API changes to be non-breaking and backwards-compatible:

exposing a new resource type adding a new method to an existing resource type adding an optional property to an existing resource type adding an optional query parameter to an existing resource method deprecating an existing resource method and providing an alternative

Environments

There are two environments available for merchants to use the following API.

To access these APIs, merchants need to combine the base URL + endpoint and make sure to have API credentials for the corresponding environments.

Environment	Base URL	API Credentials
Test	`https://test.pay.hero.io`	test account
Production	`https://pay.hero.io`	production account

API Tokens

Each API call must be accompanied by an API Token which grants access to the requested capability. You can generate multiple API tokens, each with different capabilities, that may grant broad or narrow privileges.

Access Control

To use any non-public API endpoint a token will need to be sent with the API request. You can generate a token via the Settings -> API Tokens page.

Making Requests

Requests to the HeroPay REST API follow a RESTful convention using standard HTTP verbs against various HeroPay resources to return JSON formatted responses.

Each request should include in the HTTP headers:

Content-Type: application/json

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

token (like mentioned above, obtained in your web panel)

For more information about specific resource URIs, please visit the resource documentation.

REST API Resources

Invoices

Resource

Example of invoice resource:

{
  "data": {
    "id": "1Ba89hBacPtLgQ3Cqu7aR8"
    "url": "https://pay.hero.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
    "status": "confirmed",
    "price": 20,
    "currency": "USD",
    "orderId": "INV-202201001",
    "createdStamp": 1670556426,
    "redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
    "expireStamp": 1670560026,
    "paymentWallet": "Trust Wallet",
    "paymentCurrency": "BTC",
    "paymentAmount": "0.001214",
    "paymentAddress": "bc1qxy2kgdygjraqtzq2n0yrf2593p83kkfjhx0wlh",
    "exchangeRates": {
        "BTC": {
            "USD": "22853.530000"
            }
        }, 
    "transactions": [{
        "txid": "6f8dc09bac7127eaa7845b400f35fb045ba43bd71c41c832f87d38fa120d8e5c",
        "vout": "6",
        "amount": "0.001214",
        "confirmations": 1
        }],
    "exceptionStatus": false,
    "paymentTotals": "0.001214",
    "underpayAllowed": false,
    "overpayAllowed": false,
    "amountPaidInvoicingCurrency": "20.00",
  }
}

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by HeroPay, at a locked exchange rate for an expiration time set by merchant.

Name	Type
`id` Invoice resource id	`string`
`url` Web address of invoice	`string`
`status` Invoice status can have the following values: "new": An invoice starts in this state. When in this state and only in this state, payments broadcasted by purchasers will be applied to the invoice (there is a window until invoice expire timestamp for the purchaser to send a payment from their crypto wallet). If an invoice has received a partial payment, it will still reflect a status of new to the merchant. From a merchant system perspective, an invoice is either paid or not paid, partial payments are automatically refunded by HeroPay to the consumer. "paid" As soon as payment is received it is evaluated against the invoice requested amount. If the amount paid is equal to or greater than the amount expected then the invoice is marked as being paid. To detect whether the invoice has been overpaid consult the invoice exception status (exceptionStatus parameter). The overpaid amount on an invoice is automatically refunded by HeroPay to the consumer. "confirmed": This status can be used by merchants in order to fulfill orders placed by the consumer. Invoice is changed to "confirmed" status when all crypto transactions reach 1 confirmation. "completed": When an invoice has the status complete, it means that HeroPay has credited the merchant account, in the currency indicated in the settlement settings. For instance, with invoices paid in Bitcoin (BTC), 6 confirmation blocks on the bitcoin network are required for an invoice to be complete, this takes on average 1 hour. "expired": An invoice reaches the expired status if no payment was received and the payment window has elapsed. "invalid" An invoice is considered invalid when it was paid, but the corresponding cryptocurrency transaction was not confirmed within 1 hour on the corresponding blockchain. It is possible that some transactions can take longer than 1 hour to be included in a block. If the transaction confirms after 1 hour, HeroPay will update the invoice state from "invalid" to "complete" (6 confirmations for transactions on the bitcoin network for instance). invoice	`string`
`price` Fixed price amount for the checkout, in the "currency" of the invoice object.	`string`
`currency` ISO 4217 3-character currency code. This is the currency associated with the price field.	`string`
`orderId` Can be used by the merchant to assign their own internal Id to an invoice. If used, there should be a direct match between an `orderId` and an invoice `id`	`string`
`createdStamp` UTC timestamp (in seconds) of invoice creation	`number`
`redirectUrl` The shopper will be redirected to this URL when clicking on the Return button after a successful payment or when clicking on the Close button. Make sure you include "http://" or "https://" in the url.	`string`
`expireStamp` UTC timestamp (in seconds) of invoice expiration	`number`
`paymentWallet` Name of the wallet, that shopper has selected he is doing payment from.	`string`
`paymentCurrency` This field will be populated with the cryptocurrency selected to pay the HeroPay invoice, current supported values are "BTC".. If not yet selected, this field will not be returned. This is the currency associated with the "paymentAmount" field.	`string`
`paymentAmount` The amount in cryptocurrency the shopper is supposed to pay to fulfill the invoice. This is associated with "paymentCurrency" field.	`string`
`paymentAddress` The crypto address that shopper is supposed to send funds to.	`string`
`exchangeRates` Currency exchange rates that were used to calculate payment amount from invoice price.	`object`
`transactions` Initially empty when the invoice is created. This array will be populated with the crypto currency transactions linked to the invoice.	`array`
↳ `txid` Crypto transaction hash.	`string`
↳ `vout` Crypto transaction Vout.	`string`
↳ `amount` Amount.	`string`
↳ `confirmations` Number of confirmations.	`number`
`exceptionStatus` Exception status can have the following values: false: No exception, exact amount was paid "paidOver": Client sent more money than reuqested, this invoice is overpaid. "paidPartial": Client sent less money than requested, this invoice is underpaid.	false or `string`
`paymentTotals` The total amount paid on this invoice. If invoice is paid in full with exact amount, this should be the same as `paymentAmount`	`string`
`underpayAllowed` Whether underpay was allowed on this invoice.	`boolean`
`overpayAllowed` Whether overpay was allowed on this invoice.	`boolean`
`amountPaidInvoicingCurrency` If underpay or overpay was allowed and underpay or overpay happened (see field exceptionStatus), this will be total amount that client has sent in the invoicing currency.	`string`

Create an invoice

This endpoint creates an invoice.

HTTP Request

curl -X POST \
-H "Content-Type: application/json" \
--url "https://pay.hero.io/api/invoices" \
-d @- <<'EOF'
{
"currency": "USD",
"price": 20,
"orderId": "INV-202201001",
"notificationUrl": "https://merchant.com/shop/notifications",
"redirectUrl": "https://merchant.com/shop/return",
"token": "CP.tUt3MJFzfDSeuK1UGeVNa59q",
"email": "[email protected]"
}
EOF

<?php

$resourceUrl = 'https://pay.hero.io/api/invoices';

$postData = json_encode([
    'currency' => 'USD',
    'price' => 20,
    'orderId' => 'INV-202201001',
    'notificationUrl' => 'https://merchant.com/shop/notifications',
    'redirectUrl' => 'https://merchant.com/shop/return',
    'token' => 'CP.tUt3MJFzfDSeuK1UGeVNa59q',
    'email' => '[email protected]'
]);

$curlHandle = curl_init($resourceUrl);

curl_setopt($curlHandle, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlHandle);
$resultData = json_decode($result, TRUE);
curl_close($curlHandle);

echo $resultData;

?>

POST https://pay.hero.io/api/invoices

Body

Name	Type	Presence
`currency` ISO 4217 3-character currency code. This is the currency associated with the price field	`string`	`M`
`price`	`number`	`M`
`orderId` Can be used by the merchant to assign their own internal Id to an invoice. If used, there should be a direct match between an `orderId` and an invoice `id`	`string`	`O`
`notificationUrl`	`string`	`O`
`redirectUrl`	`string`	`O`
`email` The email of user can be assigned by merchant. In this case, HeroPay will not be asking customer to enter his email during the checkout but will use this email provisioned by merchant.	`string`	`O`

HTTP Response

{
  "data": {
    "id": "1Ba89hBacPtLgQ3Cqu7aR8"
    "url": "https://pay.hero.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
    "status": "new",
    "price": 20,
    "currency": "USD",
    "orderId": "INV-202201001",
    "createdStamp": 1670556426,
    "redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
    "expireStamp": 1670560026,
  }
}

On the right side, you will find an example of the invoice object returned in the response you will get from the HeroPay server. A description of all invoice fields is available in the resource section.

Retrieve an invoice

This endpoint retrieves an invoice.

HTTP Request

curl -X GET \
-H "Content-Type: application/json" \
--url "https://pay.hero.io/api/invoices/1Ba89hBacPtLgQ3Cqu7aR8?token=CP.yOhKIHdof5bvNKCibE6MNgREeysr4"

<?php

$resourceUrl = "https://pay.hero.io/api/invoices";
$invoiceId = "1Ba89hBacPtLgQ3Cqu7aR8";
$token = "CP.yOhKIHdof5bvNKCibE6MNgREeysr4";

$curlHandle = curl_init($resourceUrl . '/' . $invoiceId . '?token=' . $token);

curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$result = curl_exec($curlHandle);
$resultData = json_decode($result, TRUE);
curl_close($curlHandle);

echo $resultData;

?>

GET https://pay.hero.io/api/invoices/:invoice-id

HTTP Response

{
  "data": {
    "id": "1Ba89hBacPtLgQ3Cqu7aR8"
    "url": "https://pay.hero.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
    "status": "confirmed",
    "price": 20,
    "currency": "USD",
    "orderId": "INV-202201001",
    "createdStamp": 1670556426,
    "redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
    "expireStamp": 1670560026,
    "paymentWallet": "Trust Wallet",
    "paymentCurrency": "BTC",
    "paymentAmount": "0.001214",
    "paymentAddress": "bc1qxy2kgdygjraqtzq2n0yrf2593p83kkfjhx0wlh",
    "exchangeRates": {
        "BTC": {
            "USD": "22853.530000"
            }
        },
    "transactions": [{
        "txid": "6f8dc09bac7127eaa7845b400f35fb045ba43bd71c41c832f87d38fa120d8e5c",
        "vout": "6",
        "amount": "0.001214",
        "confirmations": 1
        }],
    "exceptionStatus": false,
    "paymentTotals": "0.001214",
    "underpayAllowed": false,
    "overpayAllowed": false,
    "amountPaidInvoicingCurrency": "20.00",
  }
}

Notifications

Currently, HeroPay makes notifications in the form of webhooks (HTTP POST callbacks). The primary purpose of payment notification is to alert the merchant’s ecommerce server that the status of a resource (invoice) has changed. The messages are sent to the notificationUrl field when creating the invoice. The body of the payment notifications sent by HeroPay is a JSON-formatted string (Content-Type: application/json).

Handling

The payment notification shall be used as a trigger to verify the status of a specific invoice. This can be done by fetching the corresponding invoice, since invoice id is provided in the body of the payment notification.
The HeroPay server expects an HTTP 200 response with an empty body. Any other HTTP response is considered by HeroPay as a failed delivery. The HeroPay server attempts to send payment notifications multiple times until the send is either successful or the HeroPay server gives up.
Make sure to not rely on whitelisting HeroPay’s sending IP addresses, as these IP addresses are subject to change without notice.
Make sure to use HTTPS for your notificationUrl.

Invoices

Headers

Header	Value
`Accept`	`application/json`
`Content-Type`	`application/json`

Example of webhook notification:

{
  "id": "1Bmjx2cap7jmaG4AipSHjv"
}

Body

Name	Type
`id` HeroPay invoice id	`string`