Overview

Welcome to GBL's API! You can use this API to integrate cryptocurrencies into your application.

API Endpoint

http://127.0.0.1/

This API provides the ability to perform the following merchant activities:

• Create and view users
• Generate addresses for users to deposit funds to
• Withdraw funds from the wallet's balance to an external address
• Consume notifications of events
• Determine the risk associated with an address or transaction
• Manage settings and configuration

To get the best experience out of the examples provided, we strongly recommend filling out your credentials in the provided fields at the top of the navigation bar.

Recommended Resources

• https://en.bitcoin.it/wiki/Help:FAQ
• https://en.bitcoin.it/wiki/Cold_storage
• https://en.bitcoin.it/wiki/Change
• https://en.bitcoin.it/wiki/Coin_analogy

Conventions

Dates and Times

All timestamps will include a date and time in UTC expressed according to the simplified extended ISO 8601.

Unique Identifiers

Throughout this documentation we will be using universally unique identifiers (UUIDs). All entities (e.g. User, Address) can be identified by a Version 4 (random) UUID.

Errors

All failed requests will include a response body indicating that the request was unsuccessful and a brief description of the error.

{
  "success": false,
  "error": "<error text>"
}

The API uses the following HTTP status codes:

It is worth noting that GBL employs IP restrictions on requests made to our API. If you are encountering consistent errors, consider reaching out to a support specialist to confirm your IP has been allowed.

Changelog

[1.4.0] - 2022-01-27

• Added new currency - ETH

[1.3.0] - 2021-01-26

• Notifications -> Structure
  • added a new optional notification header field meta:{tenantId:}
  • added a guide to Validate a Postback message

[1.2.0] - 2020-05-31

• monitoring
  • added a new optional feature, real-time transaction monitoring
• notifications
  • added a new notification, deposit.trusted

[1.1.0] - 2020-03-25

• notifications
  • moved sample notifications messages from Consumer section to Notifications section
  • added a new Postback section

[1.0.0] - 2020-03-12

Changed

• message header structure
  • changed version type number form integer to semantic version string
  • changed correlationId from null to uuid

Integration

Before integrating with the API, you must make the decision regarding how users in your system will be identified in GBL PAY Crypto.

You have two options:

1. Rely solely on the User identifiers GBL PAY Crypto generates (managed internally and referred to as User IDs) ; or
2. Provide your own User identifiers (referred to as User References) which link back to your own system's User records.

Many APIs which handle user-based activity (deposits, withdrawals and refunds) offer two modes of invocation; it is up to you to choose one mode or the other, and use this mode for the lifetime of your application.

¹parameters listed here are a subset of those required by the API, and are simplified for brevity; refer to their individual documentation sections for a full explanation.

In GBL PAY Crypto, a User ID will always be a UUID v4.

With your own system, whatever you provide as a User Reference must simply represent "user uniqueness" in your own system; it could be a UUID, or a username, or an email address as long as it is consistent, and used consistently as a User Reference with every GBL PAY Crypto API invocation.

In all situations where either a User ID (internally-generated by GBL PAY Crypto) or a User Reference (created and managed by you) must be provided, you must provide one or the other (based on your initial integration decision), but not both.

Currencies

In the context of these APIs a currency refers to a supported cryptocurrency, like Bitcoin. The 3-4 character currency code is often used in place of the full name of the currency.

Supported Currencies

Coins sent from unsupported block-chain will be lost/inaccessible.

Retrieve Available Currencies

curl -u username:password -X GET \
  http://127.0.0.1/wallet/currencies

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/currencies'
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "currencies": [
      {
        "name": "Bitcoin",
        "code": "BTC"
      },
      {
        "name": "Ethereum",
        "code": "ETH"
      },
      {
        "name": "USD Coin",
        "code": "USDC"
      },
      {
        "name": "Tronix",
        "code": "TRX"
      },
      {
        "name": "Tether USD",
        "code": "USDT"
      }
    ]
  }
}

Retrieves all available currencies.

HTTP Request

Parameters

n/a

Responses

User

A user is a unique entity belonging to a tenant, and a user can have a set of deposit addresses for each available currency. Deposits and withdrawals will be linked back to a user and currency.

When integrating GBL PAY Crypto for the first time, you must choose either to work with GBL PAY Crypto's internally-generated User IDs, or your own User References; see Integration for details.

Create a User

curl -u username:password -X POST \
  http://127.0.0.1/wallet/user \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/x-www-form-urlencoded'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'POST',
  url: 'http://127.0.0.1/wallet/user',
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/x-www-form-urlencoded'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "user": {
      "id": "1234abcd-123a-4abc-8123-123456789abc",
      "tenantId": "01234567-890a-4cde-8012-34567890abcd",
      "createdAt": "2019-01-01T12:00:00.000Z",
      "updatedAt": "2019-01-01T12:00:00.000Z"
    }
  }
}

Creates a single User.

HTTP Request

Parameters

Responses

Retrieve a User

curl -u username:password -X GET \
  http://127.0.0.1/wallet/user?userId=fedcba98-7654-3210-8012-34567890abcd \
  -H 'X-Tenant-Key:01234567-890a-4cde-8012-34567890abcd'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/user',
  qs: {
    userId: 'fedcba98-7654-3210-8012-34567890abcd'
  },
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "user": {
      "id": "1234abcd-123a-4abc-8123-123456789abc",
      "tenantId": "01234567-890a-4cde-8012-34567890abcd",
      "createdAt": "2019-01-01T12:00:00.000Z",
      "updatedAt": "2019-01-01T12:00:00.000Z"
    }
  }
}

Retrieves information about a single user.

HTTP Request

Parameters

* Either parameter is required (but not both)

Responses

Deposit

A deposit address is owned by a user and associated to a single currency. A user's address specifies the destination to send funds to from an external wallet.

Addresses are automatically generated for users as needed. These addresses may rotate after usage depending upon the configured rotation strategy. This means that a user may have multiple addresses associated with their account at any given time.

Retrieve a deposit address

curl -u username:password -X POST \
  'http://127.0.0.1/wallet/deposit' \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'userReference=PLR-7654-3210-8012-34567890abcd&currency=BTC'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'POST',
  url: 'http://127.0.0.1/wallet/deposit',
  form: {
    userReference: 'PLR-7654-3210-8012-34567890abcd',
    currency: 'BTC'
  },
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "address": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
    "currency": "BTC"
  }
}

Retrieves the current deposit address for a single user and currency. A new user will be created if the provided userReference does not exist.

HTTP Request

Parameters

* Either parameter is required (but not both)

Responses

Transactions

Uniqueness

Uniqueness of records retrieved from the API may be observed either by a record's own "id" field, or by the union of its representation of data on the Blockchain, i.e. txid, toAddress and vout.

Retrieve Blockchain Transactions

curl -u username:password -X GET \
  http://127.0.0.1/wallet/transactions?currency=BTC&transactionType=send&limit=25&offset=0&userId=fedcba98-7654-3210-8012-34567890abcd \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/transactions',
  qs: {
    currency: 'BTC',
    transactionType: 'send',
    limit: 25,
    offset: 0,
    userId: 'fedcba98-7654-3210-8012-34567890abcd'
  },
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "4321abcd-123a-4abc-8123-123456789abc",
        "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "amount": 1.0,
        "currency": "BTC",
        "confirmations": 6,
        "fromAddress": "1abcdefghijklmnopqrstuvwzyzGFEDCBA",
        "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
        "vout": 0,
        "transactionType": "Send",
        "processState": "Succeeded",
        "userId": "1234abcd-123a-4abc-8123-123456789abc",
        "userReference": "PLR-7654-3210-8012-34567890abcd",
        "createdAt": "2019-01-01T12:00:00.000Z",
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "trusted": true,
        "risk": "unknown"
      }
    ],
    "pageInfo": {
      "limit": 25,
      "offset": 0,
      "totalEntries": 100,
      "totalPages": 4
    }
  }
}

Retrieves a list of blockchain transactions. These results represent the current state of the transactions and may be subject to change.

We only track confirmations for deposits up to a maximum of 6 confirmations, depending on what the maximum ConfirmationRequirement value is set to in the DB. Once a transaction has reached or exceeded this amount of confirmations we no longer update the record.

Transactions can be uniquely identified by a combination of the toAddress and txid. It is necessary to look at both fields to determine uniqueness since multiple deposits/withdrawals can be a part of the same blockchain transaction and thus share the same txid.

Third-party guarantee of the transaction is indicated by the trusted field; a value of "true" indicates trust, and a value of "false" indicates the third-party provider has insufficient information on the transaction to be able to guarantee risk of double-spend or other fraudulent activity.

HTTP Request

Parameters

Responses

Withdrawals

Withdrawals allow a user to move funds to an external wallet address. These transactions will be prioritized by miners on the network according to the fees set and will take some amount of time to process.

Fees

Fees are generally used to influence the likelihood that block-miners on the blockchain will pick up a transaction in a desired amount of time. Fees for withdrawals, by default, are paid by the wallet-owner. For alternate fee structures, contact the administrator for your installation.

Create a Withdrawal

curl -u username:password -X POST \
  http://127.0.0.1/wallet/withdraw \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'userId=fedcba98-7654-3210-8012-34567890abcd&currency=BTC&amount=0.1&toAddress=1abcdefghijklmnopqrstuvwzyzABCDEFG'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'POST',
  url: 'http://127.0.0.1/wallet/withdraw',
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    userId: 'fedcba98-7654-3210-8012-34567890abcd',
    currency: 'ETH',
    amount: '0.1',
    toAddress: '0x04375D8b98feF8E140932Edf6259Fc2f11De19e9'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "withdraw": {
      "id": "12345678-abcd-4321-8765-abcdef123456",
      "toAccountId": "fedcba98-7654-3210-8012-34567890abcd",
      "currency": "ETH",
      "amount": 0.1,
      "toAddress": "0x04375D8b98feF8E140932Edf6259Fc2f11De19e9",
      "createdAt": "2019-01-01T12:00:00.000Z",
      "updatedAt": "2019-01-01T12:00:00.000Z"
    }
  }
}

HTTP Request

Parameters

*¹ Either parameter is required (but not both)

² If the amount is represented in a currency other than the currency specified in the request.\ *Ex: if the user wants to withdraw 200 USD worth of Bitcoin, they should put the amount as 200 and fromCurrency as USD. This will convert 200 USD to BTC and withdraw the amount as for the exchange rate of BTC**

Responses

Refunds

Refunds allow a user to return funds to an external wallet address. These transactions will be prioritized by miners on the network according to the default fees set and will take some amount of time to process. It is assumed that the tenant will pay the transaction fee to process the refund.

Create a Refund request

curl -u username:password -X POST \
  http://127.0.0.1/wallet/refund \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'userId=fedcba98-7654-3210-8012-34567890abcd&currency=BTC&amount=0.1&toAddress=1abcdefghijklmnopqrstuvwzyzABCDEFG'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'POST',
  url: 'http://127.0.0.1/wallet/refund',
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    userId: 'fedcba98-7654-3210-8012-34567890abcd',
    currency: 'BTC',
    amount: '0.1',
    toAddress: '1abcdefghijklmnopqrstuvwzyzABCDEFG'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "refund": {
      "id": "12345678-abcd-4321-8765-abcdef123456",
      "toAccountId": "fedcba98-7654-3210-8012-34567890abcd",
      "currency": "BTC",
      "amount": 0.1,
      "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
      "createdAt": "2019-01-01T12:00:00.000Z",
      "updatedAt": "2019-01-01T12:00:00.000Z"
    }
  }
}

HTTP Request

Parameters

* Either parameter is required (but not both)

Responses

Confirmations

TransactionsCreate sent to a user's address will only be marked as completed after a certain number of block confirmations. After reaching the configured number of confirmations the funds can be considered available for use by the user.

Retrieve Confirmation Requirements

curl -u username:password -X GET \
  http://127.0.0.1/wallet/confirmationRequirement?currency=BTC \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/confirmationRequirement',
  qs: {
    currency: 'BTC'
  },
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "confirmationRequirement": [
      {
        "currency": "BTC",
        "maximumAmount": 0.125,
        "minimumConfirmations": 1,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      },
      {
        "currency": "BTC",
        "maximumAmount": 0.25,
        "minimumConfirmations": 2,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      },
      {
        "currency": "BTC",
        "maximumAmount": 0.5,
        "minimumConfirmations": 3,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      },
      {
        "currency": "BTC",
        "maximumAmount": 1,
        "minimumConfirmations": 4,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      },
      {
        "currency": "BTC",
        "maximumAmount": 2,
        "minimumConfirmations": 5,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      },
      {
        "currency": "BTC",
        "maximumAmount": 4,
        "minimumConfirmations": 6,
        "updatedAt": "2019-01-01T12:00:00.000Z"
      }
    ]
  }
}

HTTP Request

Parameters

Responses

Update Confirmation Requirements

When updating confirmation requirements the full list (default 6 entries) must be provided.

# To remove all confirmation requirements, send an empty array:
curl -u username:password -X PUT \
  http://127.0.0.1/wallet/confirmationRequirement \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "BTC",
    "confirmationRequirement": []
}'

# To update confirmation requirements:
curl -u username:password -X PUT \
  http://127.0.0.1/wallet/confirmationRequirement \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "BTC",
    "confirmationRequirement": [
        {
            "maximumAmount": 0.125,
            "minimumConfirmations": 1
        },
         {
            "maximumAmount": 0.25,
            "minimumConfirmations": 2
        },
         {
            "maximumAmount": 0.5,
            "minimumConfirmations": 3
        },
         {
            "maximumAmount": 1,
            "minimumConfirmations": 4
        },
         {
            "maximumAmount": 2,
            "minimumConfirmations": 5
        },
         {
            "maximumAmount": 4,
            "minimumConfirmations": 6
        }
    ]
}'

var request = require('request');

// To remove all confirmation requirements, send an empty array:
var confirmationRequirement = [];

// To update confirmation requirements:
confirmationRequirement = [
  {
    maximumAmount: 0.125,
    minimumConfirmations: 1
  },
  {
    maximumAmount: 0.25,
    minimumConfirmations: 2
  },
  {
    maximumAmount: 0.5,
    minimumConfirmations: 3
  },
  {
    maximumAmount: 1,
    minimumConfirmations: 4
  },
  {
    maximumAmount: 2,
    minimumConfirmations: 5
  },
  {
    maximumAmount: 4,
    minimumConfirmations: 6
  }
];

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'PUT',
  url: 'http://127.0.0.1/wallet/confirmationRequirement',
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/json'
  },
  body: {
    currency: 'BTC',
    confirmationRequirement: confirmationRequirement
  },
  json: true
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "confirmationRequirement": [
      {
        "maximumAmount": 0.125,
        "minimumConfirmations": 1,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      },
      {
        "maximumAmount": 0.25,
        "minimumConfirmations": 2,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      },
      {
        "maximumAmount": 0.5,
        "minimumConfirmations": 3,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      },
      {
        "maximumAmount": 1,
        "minimumConfirmations": 4,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      },
      {
        "maximumAmount": 2,
        "minimumConfirmations": 5,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      },
      {
        "maximumAmount": 4,
        "minimumConfirmations": 6,
        "updatedAt": "2019-01-01T12:00:00.000Z",
        "currency": "BTC"
      }
    ]
  }
}

HTTP Request

Parameters

Responses

Notifications

The application communicates stateful changes to various entities it tracks (deposits, withdrawals, refunds, wallets, etc) in an asynchronous manner by enqueuing notifications, which consumers may inspect and utilize as they see fit.

{
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.12,
  "confirmations": 1,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "fromAddress": ["1cdrdefghipmlmnopordtuvwzyzGHIJKL"],
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "currency": "BTC",
  "exchangeRateValue": {
    "USD": 62301.74,
    "EUR": 53778.16
  },
  "transactionTypeId": 2,
  "transactionTypeName": "Receive",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "vout": 0
}

{
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.12,
  "confirmations": 0,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "fromAddress": ["1cdrdefghipmlmnopordtuvwzyzGHIJKL"],
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": "1",
  "currency": "BTC",
  "exchangeRateValue": {
    "USD": 62301.74,
    "EUR": 53778.16
  },
  "transactionTypeId": "2",
  "transactionTypeName": "Receive",
  "processStateId": "7",
  "processStateName": "Monitoring",
  "trusted": true,
  "vout": 0
}

{
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.12,
  "confirmations": 1,
  "confirmedAt": "2022-01-01T12:00:00.000Z"
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "fromAddress": ["1cdrdefghipmlmnopordtuvwzyzGHIJKL"],
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "currency": "BTC",
  "exchangeRateValue": {
    "USD": 62301.74,
    "EUR": 53778.16
  },
  "transactionTypeId": 2,
  "transactionTypeName": "Receive",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "risk": "high",
  "vout": 0
}

      {
        "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "amount": 0.12,
        "confirmations": -1,
        "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
        "userId": "1234abcd-123a-4abc-8123-123456789abc",
        "userReference": "PLR-7654-3210-8012-34567890abcd",
        "currencyId": "1",
        "currency": "BTC",
        "trusted": false,
        "vout": 0,
        "transactionTypeId": "2",
        "transactionTypeName": "Receive",
        "processStateId": "4",
        "processStateName": "Failed",
        "wallet": []
      }
      

severe,high,medium,low

high,low,unknown,unavailable

{
    "txid": "50ae0287bd2c5f088a79828bce032852afa0545b9c8b7b626d127dc4bdbb97a1",
    "toAddress": "2N1dE8xqwcdLAPpBdJu9dkdTjx2uhmpBqDL",
    "currencyId": 1,
    "currency": "BTC",
    "newRisk": "high",
    "oldRisk": "low",
    "riskUpdatedAt": "2021-09-15T14:06:34.595Z"
  }

{
    "txid": "50ae0287bd2c5f088a79828bce032852afa0545b9c8b7b626d127dc4bdbb97a1",
    "toAddress": "2N1dE8xqwcdLAPpBdJu9dkdTjx2uhmpBqDL",
    "amount": 4.0,
    "currency": "BTC",
    "currencyId": 1,
    "maxAmountInUSD": 20000,
    "warning": "amount is more than the configured amount for Real-Time-Monitoring (RTM) and thus cannot be monitored, skipping this tx"
  }

{
   "id": "65c8c5f0-1dfe-4b81-a206-b434bc2c31a5",
   "userId": "1234abcd-123a-4abc-8123-123456789abc",
   "userReference":"PLR-7654-3210-8012-34567890abcd",
   "currencyId": 1,
   "currency": "BTC",
   "amount": 0.25
}

{
  "id": "65c8c5f0-1dfe-4b81-a206-b434bc2c31a5",
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.25,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "fee": 0.002,
  "currency": "BTC",
  "transactionTypeId": 1,
  "transactionTypeName": "Send",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "risk": "high"
}

{
  "id": "65c8c5f0-1dfe-4b81-a206-b434bc2c31a5",
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.25,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "confirmations": 6,
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "fee": 0.002,
  "currency": "BTC",
  "transactionTypeId": 1,
  "transactionTypeName": "Send",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "risk": "high"
}

{
  "id": "65c8c5f0-1dfe-4b81-a206-b434bc2c31a5",
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference":"PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "currency": "BTC",
  "amount": 0.25
}

{
  "id": "65c8c5f0-1dfe-4b81-a206-b434bc2c31a5",
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.25,
  "fee": 0.002,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "currency": "BTC",
  "transactionTypeId": 7,
  "transactionTypeName": "Refund",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "risk": "unavailable"
}

{
  "walletBalance": 1011.7996198,
  "excessBalance": 11.1996198,
  "walletType":"send",
  "walletName":"send",
  "currencyId": 1,
  "currency": "BTC"
}

{
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "amount": 0.12,
  "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
  "userId": "1234abcd-123a-4abc-8123-123456789abc",
  "userReference": "PLR-7654-3210-8012-34567890abcd",
  "currencyId": 1,
  "currency": "BTC",
  "transactionTypeId": 1,
  "fee": 0.002,
  "transactionTypeName": "Send",
  "walletType": "send",
  "walletName": "send",
  "processStateId": 3,
  "processStateName": "Succeeded",
  "risk": "unavailable"
}

{
  "walletBalance": 1011.7996198,
  "balanceShortfall": -11.1996198,
  "walletType": "receive",
  "walletName": "receive",
  "currencyId": 1,
  "currency": "BTC",
}

{
  "error": "XYZ config seems to be invalid"
}

{
  "error": "error message"
}

{
  "error": "error message",
  "reason": "insufficient funds",
  "details": {
    walletName: 'send',
    currency: 'BTC',
    currencyId: 1,
    id: '1234abcd-123a-4abc-8123-123456789abc',
    walletBalance: 15,
    amountRequested: 16,
    raw: null
  }
}

Consumers

Consumers may interact with enqueued notifications by inspecting (i.e. "peek") them without marking them as consumed, as well as explicitly acknowledging (i.e. "ack") their consumption.

A consumer would typically adopt the following queue-consumption logic:

1. "Peek" at one or more notifications every N seconds, starting at oldest-first.
2. For each notification returned, process it.
3. Mark the batch of notifications (the size determined in step #1) as "acknowledged".
4. Repeat steps 1 through 3.

While this approach makes two calls to the notification-hosting system, it enables the consuming application to achieve fault-tolerance by only marking notifications as "complete" after being processed successfully.

Postback

The application can alternatively be configured to make an HTTP request to a postback URL. Please contact support to configure such URLs.

Configuring postback URLs will help the consumer to act upon some activity instead of continuously peeking new messages from an endpoint.

• retries: The Application is able to retry message postbacks when the HTTP response is not 200. By default this is configured to a total of eight attempts over 30-45 minutes
• delay: Postback system is designed to send postback as soon as a notification is generated but due to some retries and scheduling priority a postback may be delayed
• message sequence/order: Postback consumer must consider the timestamp field available in the message header for the message sequencing and not the order of the postback
• change URLs: Contact support to change postback URLs, but note that a postback message is bound to the configured URL at the time of creation. We advise monitoring both URLs for a brief period while altering this configuration.

Structure

Every notification follows a singular format, and can be destructured to determine various information about the notification.

{
  "header": {
    "id": "a17e8c66-c9e8-4cad-91ae-058fdcc7c221",
    "type": "event",
    "topic": "entity.verb",
    "meta": {
      "tenantId": "620822e2-fa31-4bab-92ef-b3598e15278d"
    },
    "correlationId": "520822e2-fa31-4bab-92ef-b3598e15278d",
    "token": null,
    "version": "1.0.0",
    "timestamp": "2019-01-01T12:00:00.000Z"
  },
  "body": {
  }
}

* optional

Notification Body Values

Uniqueness

Uniqueness of notifications received either via polling or postback may be observed either by a notification's header "id" field, or (in the case of Bitcoin-related notifications) the union of txid, toAddress and vout.

Validation

In order to validate notification payload, keep below things in mind:

• Always ignore any extra keys that is not been used in current integrated version. At times it may be possible to receive an updated version of notification message that has an additional keys which are not important for the features enabled for your setup.

Validate Postback hashing

#verify SHA256 digest with Bash

PAYLOAD="${isoTime}${deterministicString}"
echo -n "${PAYLOAD}" | openssl dgst -sha256 -hmac "${PASSPHRASE}"

'use strict';

const crypto = require('crypto');
// package to convert object into Deterministic text
const  stringify  = require('json-stable-stringify');

/**
 format of data:
 {
  "header": {
    "id": "a17e8c66-c9e8-4cad-91ae-058fdcc7c221",
    "type": "event",
    "topic": "entity.verb",
    "meta": {
      "tenantId": "620822e2-fa31-4bab-92ef-b3598e15278d"
    },
    "correlationId": "520822e2-fa31-4bab-92ef-b3598e15278d",
    "token": null,
    "version": "1.0.0",
    "timestamp": "2019-01-01T12:00:00.000Z"
  },
  "body": {
  }
}
 */

function createDigest({
                        data,
                        algorithm,
                        passphrase,
                        timestamp,
                        digestFormat
                      }) {
  // ISO 8601 formatted string
  const isoTime = new Date(timestamp).toISOString();

  // Deterministic JSON-to-text
  const deterministicString = stringify(data);

  // One-way hash using ISO 8601 timestamp  + deterministicString
  return crypto
    .createHmac(algorithm, passphrase)
    .update(`${isoTime}${deterministicString}`)
    .digest(digestFormat)
    .toString();
}

If opted for postback hashing (HMAC message authentication) then a secret passphrase, an algorithm (e.g sha256, sha512), a header key (e.g Digest),and a format of hash (e.g. base64, hex) will be shared with you upon activation. Follow below steps to verify received hash

1. convert header.timestamp to ISO 8601 (isoTime) formatted string
2. Create Deterministic^* JSON-to-text (deterministicString) of the payload object
3. Create One-way hash using isoTime + deterministicString and using the passphrase in the shared format
4. Compare generated hash with the one found in the header, if mismatched return an error code 400 with proper error message

Deterministic* string: We consider deterministic string means alphanumerically sort keys of JSON object before its stringification

Interact with Queued Messages

ENTITY=deposit; # one of the entities listed in the table 'Available Entities'
curl -u username:password -X POST \
  http://127.0.0.1/notifications/queue/$ENTITY \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'count=1&ack=true'

var request = require('request');
var entity = 'deposit'; // one of the entities listed in the table 'Available Entities'

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'POST',
  url: 'http://127.0.0.1/notifications/queue/' + entity,
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    count: 1,
    ack: true
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "count": 1,
    "deposit": [
      {
        "header": {
          "id": "a17e8c66-c9e8-4cad-91ae-058fdcc7c221",
          "type": "event",
          "topic": "deposit.processed",
          "correlationId": "520822e2-fa31-4bab-92ef-b3598e15278d",
          "token": null,
          "version": "1.0.0",
          "timestamp": "2019-01-01T12:00:00.000Z"
        },
        "body": {
          "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "amount": 0.12,
          "confirmations": 1,
          "toAddress": "1abcdefghijklmnopqrstuvwzyzABCDEFG",
          "fromAddress": ["1cdrdefghipmlmnopordtuvwzyzGHIJKL"],
          "toAccountId": "fedcba98-7654-3210-8012-34567890abcd",
          "userReference": "PLR-7654-3210-8012-34567890abcd",
          "currency": "BTC",
          "transactionTypeId": 2,
          "processStateId": 1,
          "risk": "high"
        }
      }
    ]
  }
}

Inspection

To "peek" at messages in the queue, provide the value "false" to the parameter "ack".

Acknowledgement

To "acknowledge" messages in the queue, provide the value true to the parameter "ack". Note that this permanently removes enqueued messages.

HTTP Request

Note: While this endpoint may be used to obtain messages from a queue, it may also be used to alter the state of the queue; hence, its method is POST.

The {entity} parameter in the above URL must be replaced with any of the entity names listed in the table below.

Available Entities

Parameters

Responses

Message Throttling

Events occur in the back-end which are often out of the application's control (blockchain synchronization, total number of transactions within a particular time-period, miner confirmation delays, etc).This can easily result in the consumer of notifications related to these kinds of events being inundated with notifications in a short period of time.

In order to mitigate this potential flood of notifications, the application will apply throttling to when it sends out certain notifications, such that if a number of the same types of notifications occur within a short period of time (e.g. 5-10 minutes), we will only send out a single notification indicating something has occurred.

An example would be two subsequent withdrawals which cause a wallet to experience a low-balance event. If two withdrawals are processed at the same time while a wallet balance is below an ideal low-water-mark, the application will send out a single "low wallet balance" notification.

Risk Analysis

To review information related to risk associated with user deposits and withdrawals, we expose certain third-party data via our API and event notifications. Additionally, in the unlikely event that third-party risk analysis services are temporarily unavailable, we facilitate re-evaluation of deposits and withdrawals via the API.

We perform risk analysis recording and verification on incoming deposit and outgoing withdraw activity to and from the wallets we manage according to configured parameters.

We also locally cache any results retrieved from third parties so they may be quickly inspected.

Finally, we establish the ability to pre-screen withdrawals, enabling API consumers to verify the destination address before committing a withdrawal transaction to the blockchain.

Workflow

Typical workflows are described below.

User ID vs. User Reference

As described in the Integration section, whichever mode by which you choose to refer to users (either by GBL PAY Crypto's internal User ID, or by your own User Reference) will be reflected in all third-party risk-analysis data, to assist investigation efforts should the need arise.

Deposits

To observe risk related to deposits, a consumer of the API and event notifications should expect to implement the following workflow:

1. You provide the user a deposit address using the POST /wallet/deposit API endpoint.
2. User performs a deposit (using the address obtained from Step 1) using an external wallet or exchange.
3. Blockchain synchronization occurs, and we watch for the deposit along with the required confirmations for the deposit's amount.
4. We perform a risk assessment on the blockchain record and locally record the results.
5. We send out a notification indicating a deposit has completed.
6. You periodically poll our notification service for deposits via the POST /notifications/deposit API endpoint, looking for events with deposit.processed.

At this point the user may be permitted to spend deposited funds.

In the event of failure at Step 4, we also provide you with an API endpoint, PUT /wallet/risk, including the transaction's txid as the criteria, to trigger a repeat of steps 4-6. See below for API details.

Withdrawals

To verify risk associated with a user's withdrawal address, a consumer of the API and event notifications should expect to implement the following workflow:

1. User provides you with a withdrawal address from an external wallet.
2. You make a call to the PUT /wallet/risk API endpoint, including the user's withdrawal address as the criteria.
3. We perform a risk assessment pre-screening on the withdraw address and provide you with the results.
4. If the result of the risk assessment is acceptable, you may then perform a call to POST /wallet/withdraw.
5. We transfer the required funds to the address provided.
6. We register the withdrawal with risk analysis service to facilitate their ongoing observance of risk-related activity related to this address.
7. After blockchain synchronization, the management interface for the user's external wallet will indicate receipt of the transfer.

Refunds

To verify risk associated with a user's refund address, a consumer of the API and event notifications should expect to implement the same workflow as described for withdrawals:

1. User provides you with a refund address from an external wallet.
2. You make a call to the PUT /wallet/risk API endpoint, including the user's refund address as the criteria.
3. We perform a risk assessment pre-screening on the refund address and provide you with the results.
4. If the result of the risk assessment is acceptable, you may then perform a call to POST /wallet/refund.
5. We transfer the required funds to the address provided.
6. After blockchain synchronization, the management interface for the user's external wallet will indicate receipt of the transfer.

Retrieve risk

curl -u username:password -X PUT \
  'http://127.0.0.1/wallet/risk?context=address&address=1abcdefghijklmnopqrstuvwzyzABCDEFG&userId=1234abcd-123a-4abc-8123-123456789abc&currency=BTC' \
  -H 'X-Tenant-Key: 01234567-890a-4cde-8012-34567890abcd'

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'PUT',
  url: 'http://127.0.0.1/wallet/risk',
  headers: {
    'X-Tenant-Key': '01234567-890a-4cde-8012-34567890abcd',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    context: 'address',
    userId: '1234abcd-123a-4abc-8123-123456789abc', // alternatively, userReference may be used
    currency: 'BTC',
    address: '1abcdefghijklmnopqrstuvwzyzABCDEFG'
  }
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "risk": "low"
  }
}

HTTP Request

Parameters

¹ The address parameter is required in the request when the context is set to address.
² Either one of userId or userReference must be included in the request, but not both.

Responses

Possible risk values

"risk" will be one of high, low, unknown (set by third-party risk analysis services) or unavailable (set by us in the event of an error getting risk from third-party risk analysis services).

Monitoring

The application has an optional feature, real-time transaction monitoring.

When disabled, the application relies solely on configured confirmation requirements to consider deposits as acceptable for funding a user's account.

When enabled and running, the application will verify the transaction with a third-party provider to determine the viability of spending the amount indicated in a transaction at the 0-confirmation stage. By observing an additional kind of notification, deposit.trusted, a consumer of these notifications may elect to enable spending before the transaction is officially committed to the blockchain, and before the first confirmation has occurred.

Sample Deposit Flow

A sample sequence of events follows:

1. End-user is provided an Address to be used as a deposit address for their account.
2. End-user commits a transfer to the blockchain using the Address from the previous step, and obtains a Hash for the Transaction.
3. The new Transaction enters the memory pool.
4. The application learns about the new Transaction in form of an untrusted transaction with 0 confirmations, and sends a deposit.created notification.
5. The application begins monitoring the Transaction, and invokes a third-party API to verify whether that Transaction is guaranteed to be risk-free.
6. If the third-party service indicates the transaction is not trusted yet (not visible in the mempool, or other indicators specific to the Transaction), the application will send out a deposit.trusted notification with trusted=false, and continue to monitor the Transaction. While uncommon, this situation must be observed in order to ensure deposits remain risk-free.
7. Once the application receives acceptance of the Transaction (often within seconds, and well before a typical first confirmation occurs), the application sends out a deposit.trusted notification indicating trusted=true. At this point, the funds may be considered 'spendable' by the end-user.
8. The application continues to monitor the Transaction; once it meets configured confirmation requirements, it sends a follow-up deposit.processed notification, and ceases monitoring the Transaction.

Note

In all cases, note that a deposit's uniqueness stems from the combination of its Transaction Hash and its destination Address. Deposits must only be processed once, either upon receipt of a deposit.trusted notification (in the event that real-time transaction monitoring is enabled and the message payload indicates the deposit is trustable) or upon receipt of a deposit.processed notification (in the event that this feature is not enabled, or the deposit is untrusted and then mined into a block).

Ensure to verify the uniqueness of a Transaction's Hash and Address together before funding an account.

If a deposit's value exceeds your configured limit, the transaction will be excluded from Realtime Transaction Monitoring and will follow the normal deposit flow. A notification will be sent out indicating RTM was skipped for this transaction.

Transaction Types

In the context of these APIs a transaction type is associated with a transaction behaviour (e.g. Send, Receive, Refund, etc) in the cryptocurrency network.

Retrieve Available Transaction Types

curl -u username:password -X GET \
  http://127.0.0.1/wallet/transactionTypes

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/transactionTypes'
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "transactionTypes": [
      {
        "id": 1,
        "name": "Send"
      },
      {
        "id": 2,
        "name": "Receive"
      },
      {
        "id": 3,
        "name": "Generate"
      },
      {
        "id": 4,
        "name": "Immature"
      },
      {
        "id": 5,
        "name": "Orphan"
      },
      {
        "id": 6,
        "name": "Overflow"
      },
      {
        "id": 7,
        "name": "Refund"
      },
      {
        "id": 8,
        "name": "Manual Transfer"
      }
    ]
  }
}

Retrieves all available transaction types.

HTTP Request

Parameters

n/a

Responses

Process States

In the context of these APIs the process state indicates the current status of a transaction in our system (e.g. NotStarted, InProgress, Succeeded, etc).

Retrieve Available Process States

curl -u username:password -X GET \
  http://127.0.0.1/wallet/processStates

var request = require('request');

var options = {
  auth: {
    user: 'username',
    pass: 'password'
  },
  method: 'GET',
  url: 'http://127.0.0.1/wallet/processStates'
};

request(options, function(error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The request above returns the following JSON response:

{
  "success": true,
  "data": {
    "processStates": [
      {
        "id": 1,
        "name": "NotStarted"
      },
      {
        "id": 2,
        "name": "InProgress"
      },
      {
        "id": 3,
        "name": "Succeeded"
      },
      {
        "id": 4,
        "name": "Failed"
      },
      {
        "id": 5,
        "name": "Cancelled"
      },
      {
        "id": 6,
        "name": "Processing"
      }, 
      {
        "id": 7,
        "name": "Monitoring"
      }
    ]
  }
}

Retrieves all available process states.

HTTP Request

Parameters

n/a

Responses