Our Instant Payment Vendor API allows users to act as vendors and receive instant notification of a payment.

This allows you to accept EXO as instant payment through online e-commerce, retail ePOS (electronic point-of-sale) or our mobile app with assurance that a payment is on its way.

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 optionally send a signed webhook when a payment is made to you. You authenticate this by confirming the signature of the webhook.

You can sign up for an Exohood user account at my.exohood.com/register and apply for a vendor account at my.exohood.com/user/vendor.

Let us know when your integration is live, we’d love to share the news! You can share images & videos on Twitter, Instagram or on the Discord.

This API is currently in BETA phase. During this phase, we accept no responsibility for any false notifications nor affirm the identity of any vendors.

There is a maximum spend limit of €500.00 per transaction; this figure is converted to EXO at a regular interval based on market data. Please do not try to present a QR code to users above this limit as the transaction will fail.

The composer version should used should be beta during this phase.

All released changes will be documented in this section.

• First beta release of the Exohood Vendor PHP API

Community support is available at community.exohood.com.

Further documentation on data structures (useful to create your own integration or to create the QR code yourself) and our Vendor API can be found at community.exohood.com.

The following are required for using the Vendor API:

• Exohood user account with Vendor API enabled
• PHP v5.4.0 or later with the extensions:
  • ext-bcmath (optional, recommended)
  • ext-ctype
  • ext-curl (or enable allow_url_fopen)
  • ext-json

You can download the latest PHP API from github.com/exohood/exohood-vendor-api.

Unpack the API and include the Exohood vendor class:

require_once 'src/vendor.php';

Using composer, you can easily install with:

composer require exohood/exohood-vendor-api dev-beta

Alternatively, you can add the following to your composer.json:

"require": {
    "exohood/exohood-vendor-api": "dev-beta"
},
"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/exohood/exohood-vendor-api"
    }
],

This is a quick guide on using our Vendor API with PHP.

Generate a QR code for the customer:

// Create the Vendor object.
$vendor = new \exohood\Vendor\vendor(
    'key_live_1234567890abcdefghijklm',
    'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj'
);

// Create a QR code, passing the amount to charge, currency & outlet id.
$qrImgUrl = $vendor->getQr(9.95, 'GBP', '0abc123def456');
$paymentId = $vendor->getPaymentId();

Listen for a webhook confirming the payment:

// Get the payload and signature from an incoming webhook.
$payload = @file_get_contents('php://input');
$signature = @$_SERVER['HTTP_EXO_SIGNATURE'];

// Verify the signature.
if ($vendor->verifySignature($payload, $signature)) {
    http_response_code(200);

    // Process the transaction.
    $payload = json_decode($payload);
    ...
} else {
    http_response_code(401);
}

Simply create a Vendor() object. You don't need to pass any variables unless you are verifying a webhook signature or polling for payment confirmation (see below):

$vendor = new \exohood\Vendor\vendor();

To accept a vendor instant payment notification, you present a QR code with the necessary information for your customer to scan using the Exohood app on their mobile device.

You can create this using the getQr($amount, $currency, $outlet, $paymentId = null) method of the Vendor object with the following parameters:

• $amount
  The amount to charge in your local currency (accepted currencies available below).
• $currency
  Your local currency code (from the list below).
• $outlet
  The id of the outlet from your user vendor account, available from your user vendor account.
• $paymentId
  The unique identifier of this transaction. If not provided, this will be automatically generated.

The getQr() method will return a Google Chart URL of the QR code image.

The $currency must be one of the following three-digit codes:

The paymentId will be stored in the vendor object. You can retrieve this value using the getPaymentId() method if this is automatically generated for you.

For example:

$qrImgUrl = $vendor->getQr(9.95, 'GBP', '0abc123def456');
$paymentId = $vendor->getPaymentId();

If you are an online vendor, you may want to use our Vendor Payment Widget which will take the string returned from getQr() and display it as a QR code to scan or a clickable link. THis is useful if someone visits your online store on their mobile device. Please refer to our API Guide for more details.

If you have provided a webhook URL in your user vendor account, a signed webhook will be sent to this URL.

The user-agent sending the webhook will indicate the API version, the URL to the integration guide for the API and will always start Exohood/. For example Exohood/1.0 (+https://Exohood.com/instant-payments).

The payload will be sent in the request body and will include the event type and the event details. The event will be either a payment or a refund.

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

To verify the signature of a payload, you need to create the Vendor object with your API key & secret:

$vendor = new \exohood\Vendor\vendor(
    'key_live_1234567890abcdefghijklm',
    'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj'
);

You can then verify a payload calling verifySignature() which will return a boolean response:

$payload = @file_get_contents('php://input');
$signature = @$_SERVER['HTTP_EXO_SIGNATURE'];
$verify = $vendor->verifySignature($payload, $signature);

To prevent replay attacks, the verifySignature() method will verify that the timestamp is recent, within the last 5 minutes, to allow for inaccurate clock synchronisations and for the customer to complete the payment process.

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.

If you receive a valid webhook signature, you are clear to proceed with the transaction in the safe knowledge that the payment for the specified amount in the payload has been sent.

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 the webhook successfully and that it is valid.

Any error should return a 4XX code, for example 401.

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

To avoid receiving multiple webhooks, ensure your listener is idempotent and that you return a successful HTTP response as soon as possible.

Once you have set up your vendor account, you will have the availability to generate a test webhook from your user vendor account.

This will generate a random webhook payload and valid signature with which you can test your receiver using a REST client like Insomnia REST Client. We do not push the payload & signature to your webhook URL for this test.

If you are unable to open your network or ePOS to receive a webhook notification, then you can alternatively poll our server to confirm if a payment has been sent.

You will need to send your payment id and vendor address in JSON. A signature of the payload will be creating using your secret key already available in your vendor object:

$result = $vendor->checkPaymentPoll(json_encode([
    'payment_id' => '7ce25b4dc0',
    'vendor_address' => 'EXO-it-0abc123def456'
]));

The resulting JSON will include:

• status
0 Payment not sent
  1 Payment sent
• message
  If the status is 0, an error message will be returned.
• amount
  If the status is 1, an amount will returned of EXO paid by the customer.

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