Block ExplorerGitHubRun a NodeMigration Guide

Vendor API

The Instant Payment API enables fast, secure ETN payments with instant notifications via webhooks and simple integration for online and ePOS systems.

Getting API Access

Log in to your my.electroneum.com dashboard and click on VENDOR SETTINGS in the menu. Click ENABLE BETA ACCESS to get started! There's no delay; you'll have instant access.

This allows you to accept ETN as payment through online e-commerce or retail ePOS (electronic point-of-sale) with assurance that a payment has been made.

An instant notification will be created on your account, accessible via the mobile app, allowing you to receive confirmation that a payment is on its way.

Using HTTP RESTful features, our API can additionally send a signed webhook instantly when a payment is made to you. You authenticate this by confirming the signature of the webhook. Alternatively, our API can respond to a request on the status of a payment.

Support is available via our community forum at Electroneum API Developers; you will need to log in to your electroneum.com account to see the discussion thread.

All PHP example code snippets in this guide are compatible with PHP version 7.1 and above. It may work in lower versions.

Create Account

Having created your user account, register for access to our vendor program.

Those successful will receive email notification when it has been enabled.

Complete Vendor Account

Before you can use the Vendor API, you must complete your legal entity details and add your first vendor outlet. Each outlet is a place (a website or a retail shop) where you will accept ETN as payment.

When creating your outlet, enter a friendly brand name as the Outlet Name & upload a logo; this is shown to customers to identify you at checkout and in their transaction history. Use it to differentiate between shops in different towns or between a shop and a website.

Once you have added your first outlet, you will have access to your API keys and have the option to add your webhook URL (if you want to receive a signed webhook). The webhook URL must use valid HTTPS and is where we will send the instant payment notification & details.

It is important that you keep the API Secret secure. Never share it. Never send it. If you feel this is compromised, generate new API keys from your user vendor area of your user account and update your webhook listener accordingly.

Vendor Payment

Accepting payments as a vendor is a three-step process:

  1. Generate the payment string.

  2. Allow the customer to use the payment string.

  3. Check for confirmation that payment has been made.

There is a maximum spend limit on all transactions of €500.00. The vendor API will reject any transaction over this amount.

Step 1: Generate Payment String

The payment string is made up of the following parameters:

{vendor-address}/{payment-id}/{amount}

Parameters:

ParameterDescriptionFormatExample

vendor-address

Identifier for your outlet; starting " etn-it- " followed by the Outlet Id from your user vendor page.

string(20)

etn-it-0 abc123def456

payment-id

Unique (to you) identifier for the transaction.

hexadecimal(10)

7ce25b4dc0

amount

The amount to be charged in ETN, converted from your local currency, correct to two decimal places with no thousandth separator.

decimal

1234.56

Example: These example values would generate the string: etn-it-0abc123def456/7ce25b4dc0/1234.56

More Information

Vendor Address

This is made of etn-it- followed by your 13 digit Outlet Id and can be found on your user vendor page or when editing an outlet.

Payment Id

We recommend this is generated from cryptographically secure pseudo-random bytes, but this can be part-filled with a transaction reference from your existing vendor system.

This can be done with PHP as follows: $paymentId = bin2hex(random_bytes(5));

Amount

We provide exchange rates for all major currencies at https://supply.electroneum.com/app-value-v2.json.

CurrencyJSON Key

Argentina Peso

price_ars

Australia Dollar

price_aud

Bangladesh Taka

price_bdt

Brazil Real

price_brl

Bitcoin

price_btc

Canada Dollar

price_cad

DR Congo Franc

price_cdf

Switzerland Franc

price_chf

Chile Peso

price_clp

China Yuan Renminbi

price_cny

Colombian Peso

price_cop

Czech Republic Koruna

price_czk

Denmark Krone

price_dkk

Egypt Pound

price_egp

Euro

price_eur

United Kingdom Pound

price_gbp

Ghana Cedi

price_ghs

Hong Kong Dollar

price_hkd

Hungary Forint

price_huf

Indonesia Rupiah

price_idr

Israel Rupee

price_ils

India Rupee

price_inr

Japan Yen

price_jpy

Cambodian Riel

price_khr

Korea Won

price_krw

Mexico Peso

price_mxn

Malaysia Ringgit

price_myr

Nigeria Naira

price_ngn

Norway Krone

price_nok

New Zealand Dollar

price_nzd

Philippines Peso

price_php

Pakistan Rupee

price_pkr

Poland Zloty

price_pln

Romania Leu

price_ron

Russia Ruble

price_rub

Sweden Krona

price_sek

Singapore Dollar

price_sgd

Thailand Baht

price_thb

Turkey Lire

price_try

Taiwan New Dollar

price_twd

Ukraine Hryvnia

price_uah

United States Dollar

price_usd

Venezuela Bolívar Soberano

price_ves

Vietnam đồng

price_vnd

South Africa Rand

price_zar

Requesting against this JSON with your local currency and the amount in that currency, you can calculate the amount in ETN. A PHP example may look like:

phpCopy code// Set the request.
$currency = "GBP";
$amount = 9.95;

// Get the JSON conversion data.
if (!$json = file_get_contents('https://supply.electroneum.com/app-value-v2.json')) {
    die("Could not load currency exchange JSON");
}

// Check the JSON is valid.
$arr = json_decode($json, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    die("Could not load valid currency exchange JSON");
}

// Get the conversion rate.
if (!$rate = $arr['price_' . $currency]) {
    die("Currency exchange rate not found");
}

// Check the rate is valid or more than zero.
if (floatval($rate) <= 0) {
    die("Currency conversion rate not valid");
}

// Calculate the amount of ETN.
$etn = number_format(floatval($amount) / $rate, 2, '.', '');

As per our terms and conditions, you must not add any fee to this number and must be a clean calculation based on our exchange rates. Step 2: Customer Payment

The customer will need to access the payment string to send you their payment.

ePOS

If using an ePOS (traditional retail point-of-sale), you can simply display the payment string as a QR code for the customer to scan using the Electroneum app on their mobile device. You can do this dynamically or via a third party like Google Charts QR Code.

Online

If you are selling via a website, we recommend using our Vendor Payment Widget from https://github.com/electroneum/vendor-payment-widget.

This accepts your payment string and displays it as both a QR code (for the customer to scan) and as a clickable link (for the customer to pay via our website).

Simply add a div to your checkout HTML page containing your payment string in the data-etn-vendor attribute and, optionally, a two-digit language string (defaulting to English):

htmlCopy code<script src="widget.js"></script>
<div data-etn-vendor="{paymentString}" data-etn-lang="{language}"></div>

Example:

htmlCopy code<script src="widget.js"></script>
<div data-etn-vendor="etn-it-0abc123def456/7ce25b4dc0/1234.56" data-etn-lang="en"></div>

Step 3: Payment Confirmation

There are three alternate methods to confirm that a payment has been made.

Option 1: Webhook

We will send a webhook notification to the webhook URL in your user vendor settings (if provided) when a payment has been made.

The user-agent sending the webhook will indicate the API version, the URL to the integration guide for the API and will always start Electroneum/. For example:

Electroneum/0.1.0 (+https://electroneum.com/instant-payments)

You may want to prevent this user-agent from being falsely filtered by firewalls or you may want to filter incoming webhooks by user-agent.

The webhook will be signed (to confirm that it has come from us and has not been altered after being created) and will contain a payload with details of the payment.

This is our suggested method. It is the most secure and is the fastest confirmation of payment that we provide.

Signature

We sign the webhook so that you know it came from us and can be trusted.

The signature is sent in the ETN-SIGNATURE HTTP header with the webhook and is calculated using the SHA256 hash of the JSON payload using your API Secret.

Example code using PHP may look like:

phpCopy code// Your API Secret from your user vendor settings
$api_secret = 'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj';

// The payload and signature from the webhook
$payload_json = @file_get_contents('php://input');
$payload_arr = json_decode($payload_json, true);
$signature = $_SERVER['HTTP_ETN_SIGNATURE'];

if ($signature !== hash_hmac('sha256', $payload_json, $api_secret)) {
    // Invalid webhook signature
    http_response_code(401);
} elseif (strtotime($payload_arr['timestamp']) < strtotime('-5 minutes')) {
    // Expired webhook
    http_response_code(400);
} else {
    // Valid webhook signature
    http_response_code(200);
    // Process the transaction ...
}

If you receive a valid webhook signature, you are safe to trust the payload.

We advise you to check against duplicate webhooks by making your event processing idempotent; log a payment as processed so that if you get a duplicate webhook payment id you can immediately ignore it.

Payload

The webhook payload is sent with an HTTP POST request and the body contains the following JSON:

ParameterDescriptionFormatExample

event

The type of payment; either "payment" or "refund".

string

payment

payment_id

The payment id provided by you, to identify the transaction. If the event is refund, the payment_id refers to the original transaction the refund is made against.

string(10)

7ce25b4dc0

amount

The amount of ETN paid by the customer, to two decimal places.

decimal

1234.56

key

Your vendor API Key.

string(32)

key_live_1234567890abcdefghijklm

timestamp

The datetime of the payment in ISO 8601 format.

string

2018-06-11T11:02:31+01:00

customer

The customer's email addresses associated with their ETN account.

string

customer@example.com

ref

Our reference for the payment.

string(13)

1234567890abc

WARNING: You should confirm that the API Key matches your credentials, that the timestamp is recent (we recommend no more than 5 minutes old), that the payment_id hasn't already been processed by your system, and that the amount is the value you expected to be paid.

To prevent replay attacks, whereby an attacker will capture and resend a payload, you should verify the timestamp is recent, within a threshold of your choosing. We recommend a period less than 5 minutes is valid for the customer to complete the transaction and to allow for inaccurate clock synchronizations.

Response Code

You must return a valid HTTP response code when receiving a webhook. To prevent our webhook timing out, you should return an HTTP response as soon as possible.

A success must return a 2XX code, for example 200. This will let us know that you have received it successfully. Any error should return a 4XX code, for example 401.

Failed Webhooks / Retries

Any response to our webhook that is not a successful code (not a 2XX) will alert us that we should retry said webhook. Webhooks are retried every hour for three days, after which they will not be retried.

Generate Test Webhook

You can generate a valid payload and signature to test against your webhook listener from your user vendor account.

Please note that the payload generated by the test webhook is formatted for ease of reading when displayed in the browser. You may want to decode & encode to ensure this is formatted before validating a signature; see our Vendor PHP library on how this can be handled.

Using a REST client like Insomnia REST Client will allow you to test against a number of requests. We do not push the payload & signature to your webhook URL for this test.

Option 2: Electroneum App Notification

A notification will appear in the mobile app for your vendor user account when an instant payment has been made to you.

WARNING: You should confirm the amount paid is correct.

Option 3: API Poll

You can send the payment id to our API for us to confirm if it has been received.

We do not recommend this method due to its frequency restrictions but it exists should you not be able to open your network or ePOS systems to receive a webhook.

Post your outlet id and payment id, signed with your API Secret, to our API and we'll return whether the request for payment has been made and, if so, how much has been paid.

Signing your request with your API Secret means only you can request the status of your payments.

Payload

Post a JSON with the following parameters in this order:

ParameterDescriptionFormatExample

payment_id

The payment id of the transaction you want to check.

string(10)

7ce25b4dc0

vendor_address

Your vendor address, made of "etn-it" and your outlet id.

string(20)

etn-it-0abc123def456

Signature

Sign the payload by SHA-256 hashing the JSON using your API Secret. If using PHP, this may look like:

phpCopy code// Your API Secret from your user vendor settings
$api_secret = 'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj';

// The payload to be sent.
$payload = [
    'payment_id' => '7ce25b4dc0',
    'vendor_address' => 'etn-it-0abc123def456'
];

// Generate the signature
$signature = hash_hmac('sha256', json_encode($payload), $api_secret);

HTTP POST

You can then HTTP POST the JSON to https://poll.electroneum.com/vendor/check-payment including the signature in the header ETN-SIGNATURE.

If using PHP, this may look like:

phpCopy code// Post the request.
$ch = curl_init('https://poll.electroneum.com/vendor/check-payment');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'ETN-SIGNATURE: ' . $signature
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

// Decode the JSON result into an array.
$result = json_decode($result);

// Check the result.
if ($result['status'] === 1) {
    // Payment made.
    echo "Payment made for " . $result['amount'] . " ETN";
} elseif ($result['status'] == 0) {
    // Payment not made.
} else {
    // Invalid request (e.g. invalid signature).
}

The API will return a JSON array of:

ParameterDescriptionFormatExample

status

The result of the request:<br />0 Payment not sent by customer<br />1 Payment sent by customer

int(1)

1

message

An error message (only present if status=0)

string

Vendor address unknown

amount

The amount paid (only present if status=1)

decimal

123.45

To avoid being blocked by our API, please restrict your poll to no more than one request per second.

WARNING: You should confirm that the amount is the value you expected to be paid.

PHP API

We have provided a PHP library to help you integrate with our API as efficiently as possible https://github.com/electroneum/vendor-php.

This contains a README.md file with full details and demonstration integration code in the /example directory. Example usage may look like:

phpCopy code// Generate the URL for a QR image for Outlet Id 0abc123def456 and for 9.95 GBP.
$vendor = new \Electroneum\Vendor\Vendor($apiKey, $apiSecret);
$qr = $vendor->getQr(9.95, 'GBP', '0abc123def456');

// Verify a received webhook is valid.
$payload = @file_get_contents('php://input');
$signature = @$_SERVER['HTTP_ETN_SIGNATURE'];
$isValid = $vendor->verifySignature($payload, $signature);

// Check if a payment is sent.
$payload = [
    'payment_id' => '0abc123def456',
    'vendor_address' => 'etn-it-0abc123def456'
];
$result = $vendor->checkPaymentPoll(json_encode($payload));

Brand Assets

We have brand assets available at https://electroneum.com/brand-assets/ to show users that you accept ETN as payment.

Integration Complete

Once your integration is live, you should update the outlet in your vendor account to enable how users can spend ETN. There are two options; one for websites and one for ePOS (retail stores).

Let us know when your integration is live, we'd love to share the news! You can share images & videos on Twitter, Facebook or on the community forum.

PreviousSet up Ledger + Metamask

Last updated