NAV
python javascript php

Introduction

Welcome to Zeply Business API Documentation.

Endpoints:

SDK or API?

Zeply Business can be integrated into your website in either of two ways:

SDK

Follow these steps to offer crypto payments using Zeply Business SDK:

<script type="text/javascript"
    src="https://static-business.zeply.com/static/js/sdk.js"></script>

<button class="zeply-button"
    data-product="Premium Travel Package"
    data-amount="20"
    data-currency="EUR"
    data-passthrough="Order 12345"
    data-show-payment-url="true">
      Click to buy
</button>

ZeplyBusinessSDK.setup({
    account: '<YOUR_ACCOUNT_ID>',
    profile: '<YOUR_PROFILE_ID>',
    apiEndpoint: 'https://business.zeply.com/',

    // Callbacks
    // onOpen: onNewPayment,
    // onUpdate: onPaymentUpdate,
    // onSuccess: onPaymentSuccess,
    // onIncomplete: onPaymentIncomplete,
    // onCancel: onPaymentCancel
})

// Callback example: 
// function onPaymentOpen(data, code) {
//   console.log(code, data)
// }

Important Note! Never fully rely on JavaScript / client-side data provided in onSuccess, onUpdate and onIncomplete events as it can easily be manipulated. When it comes to transactions data processing you should fully trust only server to server callbacks.

onOpen, onUpdate, onIncomplete, onSuccess, onCancel.

ZeplyBusinessSDK.destroy()

Live SDK example

Try clicking this button:

 

 

 

API Authentication

To sign requests, you can use following code:

import time
import base64
import hashlib
import hmac
import json
import requests

API_URL = 'https://business-api.zeply.com'
API_KEY = 'my_api_key'
API_SECRET = 'my_api_secret'


def encode_hmac(key, msg, digestmod=hashlib.sha256):
    return hmac.new(key.encode(), msg=msg, digestmod=digestmod).hexdigest()

def zeply_api_request(endpoint, payload=None, method='GET'):
    payload_nonce = str(int(time.time() * 1000))
    request_path = '/v1/%s/' % endpoint
    payload = payload or {}
    payload.update({'request': request_path, 'nonce': payload_nonce})

    # Encode payload to base64 format and create signature using your API_SECRET 
    encoded_payload = json.dumps(payload).encode()
    b64 = base64.b64encode(encoded_payload)
    signature = encode_hmac(API_SECRET, b64)

    # Add your API key, encoded payload and signature to following headers
    request_headers = {
        'X-ZEPLY-KEY': API_KEY,
        'X-ZEPLY-PAYLOAD': b64,
        'X-ZEPLY-SIGNATURE': signature,
    }

    # Make request
    response = requests.request(method, API_URL + request_path, headers=request_headers)
    return response.json()

profiles = zeply_api_request('profiles')
print(json.dumps(profiles, indent=2))

const axios = require('axios');
const Base64 = require('js-base64').Base64;
const crypto = require('crypto');

const API_URL = 'https://business-api.zeply.com';
const API_KEY = 'my_api_key';
const API_SECRET = 'my_api_secret';

function encode_hmac(key, msg) {
    return crypto.createHmac('sha256', key).update(msg).digest('hex');
}

function encode_hmac(key, msg) {
    return crypto.createHmac('sha256', key).update(msg).digest('hex');
}

function zeply_api_request(endpoint, payload = {}, method = 'GET') {
    const request_path = '/v1/' + endpoint + '/'
    payload.request = request_path;
    payload.nonce = (new Date).getTime();

    // Encode payload to base64 format and create signature using your API_SECRET
    const encoded_payload = JSON.stringify(payload);
    const b64 = Base64.encode(encoded_payload);
    const signature = encode_hmac(API_SECRET, b64);

    // Add your API key, encoded payload and signature to following headers
    let request_headers = {
        'X-ZEPLY-KEY': API_KEY,
        'X-ZEPLY-PAYLOAD': b64,
        'X-ZEPLY-SIGNATURE': signature,
    };

    return axios({
        method: method,
        url: API_URL + request_path,
        headers: request_headers,
    });
}

zeply_api_request('profiles').then(function (response) {
    console.log(response);
}).catch(function (error) {
    console.log(error);
});

You can obtain API Keys by logging in and creating a key in Settings > API Keys. This will give you both an "API Key" that will serve as your username, and an "API Secret" that you will use to sign messages.

All requests must contain a nonce, a number that will never be repeated and must increase between requests. This is to prevent an attacker who has captured a previous request from simply replaying that request. We recommend using a timestamp at millisecond or higher precision.

PAYLOAD

The payload of the requests must be a JSON object, which will be described in the documentation below. Rather than being sent as the body of the POST request, it will be base-64 encoded and stored as a header in the request.

The following three headers is all that is required to make requests to Zeply Business API:

Header Value
X-ZEPLY-KEY Your Zeply Business API Key
X-ZEPLY-PAYLOAD Base64-encoded JSON payload
X-ZEPLY-SIGNATURE hex(HMAC_SHA256(base64(payload), key=api_secret))

Invoices

Invoices are time-sensitive invoice requests addressed to specific buyers or payers. Invoice has a unique receiving address and fixed price, typically denominated in fiat currency. It also has a Crypto equivalent price, calculated by Zeply Business, with an expiration time of about 15 minutes.

List Invoices

invoices = zeply_api_request('invoices')
print(json.dumps(invoices, indent=2))

zeply_api_request('invoices').then(function(response) {
    console.log(response);
}).catch(function(error) {
    console.log(error);
});

$response = zeply_api_request('invoices');
var_dump($response);

The above command returns JSON structured like this:

{
    "pagination": {
        "num_pages": 1,
        "count": 12,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    },
    "result": [
        {
            "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
            "created_at": "2022-01-17T22:15:05.859322+00:00",
            "confirmed_at": "2022-01-18T14:50:05+00:00",
            "completed_at": null,
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "invoice_currency": "BTC",
            "invoice_amount": "0.00094700",
            "requested_currency": "USD",
            "requested_amount": "9.47000000",
            "address": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g",
            "addresses": {
              "BTC": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g"
            },
            "status": "confirmed",
            "paid_amount": {
              "crypto": {
                "currency": "BTC",
                "amount": "0.00094700"
              },
              "fiat": {
                "currency": "USD",
                "amount": "9.47000000"
              }
            },
            "notes": null,
            "passthrough": "{\"order_id\":1642457702}",
            "transactions": [
              {
                "id": "2ceeeec5-acbf-4fed-98f3-99c364532322",
                "txid": "c5020b9615eaff5586f595655a22e8d61cf64161172811406d9c3801bd1e7b90",
                "amount": {
                  "crypto": {
                    "currency": "BTC",
                    "amount": "0.00094700"
                  },
                  "fiat": {
                    "currency": "USD",
                    "amount": "9.47000000"
                  }
                },
                "currency": "BTC",
                "created_at": "2022-01-17T22:16:03.399328+00:00",
                "confirmed_at": null,
                "url": "https://blockstream.info/testnet/tx/c5020b9615eaff5586f595655a22e8d61cf64161172811406d9c3801bd1e7b90"
              }
            ]
        }
    ]
}

This endpoint retrieves all invoices. Endpoint uses pagination and returns 25 invoices per page. Invoices are sorted by creation time in descending order.

HTTP Request

GET https://business-api.zeply.com/v1/invoices/

Query Parameters

Parameter Default Description
p None Page number.
txid None Filter invoices by txid
address None Filter invoices by receiving address
status None Filter by status. Available values specified in Invoice Statuses.

Get Invoice

invoice = zeply_api_request('invoices/0baa1b12-1d05-4ca1-b0fd-4c391e9d3b9f')
print(json.dumps(invoice, indent=2))

zeply_api_request('invoices/0baa1b12-1d05-4ca1-b0fd-4c391e9d3b9f').then(function(response) {
    console.log(response);
}).catch(function(error) {
    console.log(error);
});

$response = zeply_api_request('invoices/0baa1b12-1d05-4ca1-b0fd-4c391e9d3b9f');
var_dump($response);

The above command returns JSON structured like this:

{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2022-01-17T22:15:05.859322+00:00",
        "confirmed_at": "2022-01-18T14:50:05+00:00",
        "completed_at": null,
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "invoice_currency": "BTC",
        "invoice_amount": "0.00094700",
        "requested_currency": "USD",
        "requested_amount": "9.47000000",
        "address": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g",
        "addresses": {
           "BTC": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g"
        }, 
        "status": "confirmed",
        "paid_amount": {
          "crypto": {
            "currency": "BTC",
            "amount": "0.00094700"
          },
          "fiat": {
            "currency": "USD",
            "amount": "9.47000000"
          }
        },
        "notes": null,
        "passthrough": "{\"order_id\":1642457702}",
        "transactions": [
              {
                "id": "2ceeeec5-acbf-4fed-98f3-99c364532322",
                "txid": "c5020b9615eaff5586f595655a22e8d61cf64161172811406d9c3801bd1e7b90",
                "amount": {
                  "crypto": {
                    "currency": "BTC",
                    "amount": "0.00094700"
                  },
                  "fiat": {
                    "currency": "USD",
                    "amount": "9.47000000"
                  }
                },
                "currency": "BTC",
                "created_at": "2022-01-17T22:16:03.399328+00:00",
                "confirmed_at": null,
                "url": "https://blockstream.info/testnet/tx/c5020b9615eaff5586f595655a22e8d61cf64161172811406d9c3801bd1e7b90"
              }
            ]
    }
}

This endpoint retrieves a specific invoice.

HTTP Request

GET https://business-api.zeply.com/v1/invoices/<ID>/

URL Parameters

Parameter Description
ID The ID of the invoice to retrieve.

Create Invoice

import json

payload = {
    "requested_currency": "USD",
    "requested_amount": "10",
    "invoice_currency": "BTC",
    "profile_uuid": "deb23315-1eae-46fe-929f-6f3067292493",
    "passthrough": json.dumps({"order_id": 1642457702}),
    "notes": "this is demo"
}
invoice = zeply_api_request('invoices', payload, 'POST')
print(json.dumps(invoice, indent=2))

var payload = {
    "requested_currency": "USD",
    "requested_amount": "10",
    "invoice_currency": "BTC",
    "profile_uuid": "deb23315-1eae-46fe-929f-6f3067292493",
    "passthrough": JSON.stringify({"order_id": 1642457702}),
    "notes": "this is demo"
}
zeply_api_request('invoices', payload, 'POST').then(function(response) {
    console.log(response);
}).catch(function(error) {
    console.log(error);
});

$payload = array(
    'requested_currency' => 'USD',
    'requested_amount' => '10',
    'invoice_currency' => 'BTC',
    'profile_uuid' => 'deb23315-1eae-46fe-929f-6f3067292493',
    'passthrough' => json_encode(array('order_id' => 1642457702)),
    'notes' => 'this is demo',
);
$response = zeply_api_request('invoices/0baa1b12-1d05-4ca1-b0fd-4c391e9d3b9f');
var_dump($response);

JSON response for Create Invoice endpoint:

{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2022-01-17T22:15:05.859322+00:00",
        "confirmed_at": "2022-01-18T14:50:05+00:00",
        "completed_at": null,
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "invoice_currency": "BTC",
        "invoice_amount": "0.00094700",
        "requested_currency": "USD",
        "requested_amount": "9.47000000",
        "address": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g",
        "addresses": {
          "BTC": "tb1qcq9ne8jjgnss4xyt2cdn37g674ngmfy07yum2g"  
        },
        "status": "confirmed",
        "paid_amount": {
          "crypto": {
            "currency": "BTC",
            "amount": "0"
          },
          "fiat": {
            "currency": "USD",
            "amount": "0"
          }
        },
        "notes": null,
        "passthrough": "{\"order_id\":1642457702}",
        "transactions": []
    }
}

This endpoint creates an invoice. Response is identical to Get Invoice endpoint response.

HTTP Request

POST https://business-api.zeply.com/v1/invoices/

Payload Parameters

Parameter Description Required
profile_uuid Profile ID to use for settings, callback and wallet address generation. Yes
requested_currency Currency for the specified invoice amount. Available values: EUR, GBP, USD. Yes
requested_amount Quoted decimal invoice amount. Yes
invoice_currency Currency for the specified invoice amount. Available values: BTC. Yes
passthrough String. Meta-data you wish to store with the invoice. Will be sent alongside all callbacks associated with the invoice. No
notes Can be product or service name or any other notes. Visible in dashboard and in public invoice link. No

Invoice Statuses

Status Description
new A new invoice has been created and a deposit address has been generated for the client to send their Crypto.
pending Transactions are found and are awaiting confirmations.
converting The Crypto amount received is within the accepted threshold and the conversion of the Crypto to FIAT has been initiated.
canceled_ The invoice has been manually set to canceled by the user.
completed Invoice conversion has finished and invoice is now complete.
complete_ The invoice has been manually set to complete by the user.
incomplete A Crypto deposit was made by the client, but the received amount is below the accepted threshold.
overpay A Crypto deposit was made by the client, but the received amount is above the accepted threshold.
address_reuse A Crypto deposit has been made to a wallet address that was used on a previously completed invoice. It will require manual handling. This will only occur on profiles that do not allow address re-use.
conversion_failed Conversion from crypto to fiat has failed. Requires manual handling.

Invoice Callbacks

Callbacks provide same exact response format as in Get Invoice API endpoint in result field plus three extra fields specified in Callbacks Documentation.

You can view history of callbacks (if any) in Zeply Business in Invoice detail view.

Invoice Callback Statuses

Status Description
invoice_pending Invoice matches requested amount, has zero confirmations on blockchain (BTC only).
invoice_converting Invoice is received and it matches requested amount, conversion process from crypto into fiat has started.
invoice_complete Conversion has finished and invoice is now complete.
invoice_incomplete Invoice amount doesn't match profile "Allowed Difference" range. Requires manual handling.
invoice_address_reuse Already previously complete invoice address receives a new transaction and "Address Reuse" parameter for related profile is not enabled. Requires manual handling.
invoice_conversion_failed Conversion from crypto to fiat has failed. Requires manual handling.
python javascript php