NAV Navbar

Gateway.cash API

Hello there! This panel provides useful descriptions, annotations and examples demonstrating the features of the API. It generally shows up on the right-hand side of your screen and will stay lined up so that the examples always reference what's being talked about to the left. If you don't understand something, glance over and you'll find some handy examples.

Welcome to the Gateway.cash API! You can use our API to create and manage merchant accounts, make and receive Bitcoin Cash payments, keep track of invoices and more!

Overview

All code for these demonstrations is written in JavaScript (specifically ES2017). If you haven't heard of it, you should definitely check it out. It's pretty darn cool!

The API is served over HTTP or HTTPS with your current URL as a basepoint. If you are running a local instance of the server at http://127.0.0.1:8080/ then your requests will start with that URL.

URL Prefixes

API endpoints are prefixed with a version number, in the format BASEPOINT/vX/endpoint. X represents the API version. New API versions are released when a "breaking change" is made which would cause old clients to stop working. The current version of the API is v2.

For example, the endpoint for /user/login is http://127.0.0.1:8080/v2/user/login on your local instance. The examples in this documentation assume you are using a basepoint URL of https://api.gateway.cash/ which is the production server Gateway uses across all of our services.

A Note on the Use of Our Servers

You are free to use our API server as you wish. If we receive excessive spam we may choose to block your access. Like all open-source projects, you are also free to run your own server on the internet if you wish.

It is a common misconception that because gateway.cash is able to block, ban or "censor" merchants who do bad things from our platform, that the Gateway project is somehow centralized. If you disagree with our decision, you may run your own servers since our code is open-source. Merchants can take advantage of all of the features of Gateway regardless of our policies.

API Requests

All examples on this page use a popular JavaScript library called axios for making HTTP and HTTPS requests. Before you use axios, be sure to include it in your JavaScript file like so:

import axios from 'axios'

Making a request to the API will result in a JSON object string being returned. The "status" property of the object will either be "success" or "error" for all requests.

When "status" is "error", the JSON object will always contain an "error" property which will consist of a brief error message. "description" will contain a more in-depth explanation of the problem, suitable for showing to your users.

When "status" is "success", the object will contain the information documented here.

API Keys

For illustration purposes, we'll be using placeholders like YOUR_API_KEY and BITCOIN_CASH_ADDRESS throughout these examples. Be sure to replace and substitute those values for your actual data before trying to use the API.

An API key is required in all but a few special cases when working with the Gateway API. You don't need a key to create or pay invoices, but to be able to manage merchant accounts, administrate platforms or view invoices you will need to generate an API key.

Merchant accounts can be generated using the /user/register endpoint. When you create an account, your first API key is generated automatically. Keys can be managed with the /api/keys and /api/key endpoints, and /user/login will retrieve a working API key for your account.

Accounts, Access and Keys

This section covers accessing and managing your user account, API keys and related topics.

Registration

Create a new basic merchant account:

let result = await axios.post(
  'https://api.gateway.cash/v2/user/register',
  {
    address: 'BITCOIN_CASH_ADDRESS',
    username: 'JohnGalt12',
    password: 'IHeartDagney'
  }
)

Create a new Gateway Platforms user (see Platforms section):

let result = await axios.post(
  'https://api.gateway.cash/v2/user/register',
  {
    address: 'BITCOIN_CASH_ADDRESS',
    username: 'JohnGalt12',
    password: 'IHeartDagney',
    platformID: 'YOUR_PLATFORM_ID'
  }
)

When you successfully register a new merchant account, you'll get something like this back:

{
  "status": "success",
  "APIKey": "NEW_API_KEY"
}

So, to print your new API key:

console.log(result.data.APIKey)

Before you can use most portions of the Gateway API, you must first register for a merchant account. Without an API key, you can still create invoices and mark them as paid. A merchant account allows you to create payment buttons, view payments for each button, track your total sales and much more.

Parameters

Required Name Description
Sometimes address The Bitcoin Cash address to use for your merchant account. Required when XPUB is not provided
Sometimes XPUB The extended public key (XPUB) for your merchant account. Required when address is not provided
Yes username The username for your merchant account
Yes password A unique and strong password to protect your new account
No platformID Makes this user a Gateway Platforms user. See the Platforms section below for more info

A Warning About XPUB with Platforms Users

It is not possible to utilize Platform commissions if your Platforms user accounts have XPUB keys. This is because when XPUB is used, payment is forwarded directly to the merchant and Gateway never controls the funds.

If you do not ever want to take a commission and only want to use Gateway Platforms to track total platform sales, you can still use XPUB with Platforms user accounts. Include dismissXPUBWithPlatformIDWarning=YES with your request to bypass the warning.

Logging In

In previous versions of this API, it was possible to log in with your payout address. Since it's now possible for multiple people to have the same payout address, you must always use your username and password when logging in:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/login',
  {
    params: {
      username: 'JohnGalt12',
      password: 'IHeartDagney'
    }
  }
)

A successful response will always return a working API key for your account:

{
  "status": "success",
  "APIKey": "YOUR_API_KEY"
}

Use the API key you receive when calling other endpoints.

When you need to retrieve a working API key for your account, send a GET request to /user/login and one will be returned.

Parameters

Required Name Description
Yes username The username for the merchant account
Yes password The password for the merchant account

If you delete all your API keys, the login endpoint will generate a new API key for your account so you aren't locked out.

Getting Your Merchant ID

Get the merchant ID for the account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/merchantid',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will look like this:

{
  "status": "success",
  "merchantID": "MERCHANT_ID"
}

The merchant ID is passed to the /pay endpoint to generate invoices. To retrieve the merchant ID, send a GET request to /user/merchantid.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Getting Total Sales

Get total sales information for the merchant account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/sales',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will look like this:

{
  "status": "success",
  "totalsales": 133706969
}

All values are in units of Satoshi.

To retrieve the total amount ever paid to this merchant, send a GET request to /user/sales.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Getting Total Contributions

Retrieve the total contributed to Gateway by this merchant:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/contribution',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will include a contributionTotal property:

{
  "status": "success",
  ...
  "contributionTotal": 133706969
}

All values are in units of Satoshi.

To retrieve the total amount ever contributed to Gateway by this merchant, send a GET request to /user/contribution.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

The response, among other things, will include a field called "contributionTotal".

Viewing Your Payments

Get the first page of payments for your account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/payments',
  {
    params: {
      APIKey: 'YOUR_API_KEY',
      includeKeys: 'NO',
      includeUnpaid: 'NO'
    }
  }
)

The response will look something like this:

{
  "status": "success",
  "totalPayments": 32,
  "totalPages": 11,
  "resultsPerPage": 3,
  "resultsOffset": 0,
  "currentPage": 1,
  "payments": [
    {
      "status": "complete",
      "paymentAddress":"BITCOIN_CASH_ADDRESS",
      "invoiceAmount":9003,
      "paymentID": "order-fe43dcb493ac",
      "created": "2018-10-22T23:49:53.000Z",
      "privateKey": "hidden",
      "callbackURL": "https://www.ooooooggle.com",
      "callbackStatus": "status-200",
      "platformID": "GATEWAY_PLATFORM_ID",
      "transactions": [
        {
          "type": "payment",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        },
        {
          "type": "transfer-to-merchant",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        }
      ]
    },
    {
      "paymentAddress":"BITCOIN_CASH_ADDRESS",
      "invoiceAmount":9003,
      "status": "complete",
      "paymentID": "order-fe43dcb493ac",
      "created": "2018-10-22T23:49:53.000Z",
      "privateKey": "hidden",
      "transactions": [
        {
          "type": "payment",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        },
        {
          "type": "transfer-to-merchant",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        }
      ]
    },
    {
      "paymentAddress": "BITCOIN_CASH_ADDRESS",
      "invoiceAmount":9003,
      "status": "complete",
      "paymentID": "order-fe43dcb493ac",
      "created": "2018-10-22T23:49:53.000Z",
      "privateKey": "hidden",
      "transactions": [
        {
          "type": "payment",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        },
        {
          "type": "transfer-to-merchant",
          "TXID": "BITCOIN_CASH_TRANSACTION_ID"
        }
      ]
    }
  ]
}

To retrieve your payments, send a GET request to /user/payments. Since some merchants have a lot of payments, this endpoint splits them into pages and allows you to cycle through to find the one you are looking for.

Parameters

Required Name Default Description
Yes APIKey N/A An active API key belonging to the merchant
No includeKeys NO Include payment address private keys in the response
No includeUnpaid NO Include broken, unpaid or half-complete invoices
No resultsPerPage 25 The max number of results to send
No page 1 The page number

Return Value

Name Description
totalPayments The total number of payments in this category for the merchant
resultsPerPage The number of results being sent in the current page
totalPages When pages are this size, this is the total number of needed pages to display all results
resultsOffset The offset of the first payment on the page into the total number of payments. On page 3 with 25 results per page this is 50.
currentPage The current page being displayed
payments An array containing the payments on the current page
payments[x].paymentAddress The address associated with the payment
payments[x].status The current status of the payment
payments[x].privateKey The private key for the payment. Not applicable to XPUB payments
payments[x].invoiceAmount The amount of the invoice from the user's browser
payments[x].created The timestamp when the payment was created
payments[x].paymentID An identifier for the payment
payments[x].callbackURL The callback URL for the payment
payments[x].callbackStatus The status of the callback request
payments[x].transactions An array of transactions associated with this payment
payments[x].transactions[y].TXID The TXID of the transaction
payments[x].transactions[y].type The type of the transaction, generally one of payment, transfer-to-merchant, refund etc.

Getting Payout Method

Retrieve the payout method:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/payout/method',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

Successful results will look as follows:

{
  "status": "success",
  "payoutMethod": "METHOD"
}

There are two supported payout methods for Gateway accounts. "address" allows merchants to receive all their payments with a single Bitcoin Cash address, while "XPUB" allows you to specify an extended public key.

To get your payout method, send a GET request to /user/payout/method.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Changing Payout Method

Update the payout method:

let result = await axios.patch(
  'https://api.gateway.cash/v2/user/payout/method',
  {
    APIKey: 'YOUR_API_KEY',
    newPayoutMethod: 'METHOD'
  }
)

When successful, the new payout method will be sent back:

{
  "status": "success",
  "newPayoutMethod": "METHOD"
}

To update the payout method, first make sure you've provided a valid address or XPUB key, then send a PATCH request to /user/payout/method.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes newPayoutMethod The new payout method for the merchant

Getting Payout Address

Get the payout address for the merchant account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/payout/address',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will look like this:

{
  "status": "success",
  "payoutAddress": "BITCOIN_CASH_ADDRESS"
}

To retrieve the payout address, send a GET request to /user/payout/address.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Changing Payout Address

Change the payout address:

let result = await axios.patch(
  'https://api.gateway.cash/v2/user/payout/address',
  {
    APIKey: 'YOUR_API_KEY',
    newAddress: 'BITCOIN_CASH_ADDRESS'
  }
)

Your new address will be sent back for confirmation. If you send an address in a format other than CashAddress, the CashAddress formatted version will always be returned.

{
  "status": "success",
  "newAddress": "BITCOIN_CASH_ADDRESS"
}

To specify a new payout address for a merchant account, send a PATCH request to /user/payout/address.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes newAddress The new payout address for the merchant

Getting Payout XPUB

Get the payout XPUB key for the merchant account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/payout/xpub',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will look like this:

{
  "status": "success",
  "payoutXPUB": "EXTENDED_PUBLIC_KEY"
}

To retrieve the payout XPUB key, send a GET request to /user/payout/xpub.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Changing Payout XPUB

Change the payout XPUB key:

let result = await axios.patch(
  'https://api.gateway.cash/v2/user/payout/xpub',
  {
    APIKey: 'YOUR_API_KEY',
    newXPUB: 'EXTENDED_PUBLIC_KEY'
  }
)

Your new XPUB key will be sent back for confirmation, in addition to the address derivation index used for the key, which is generally 0 for new keys.

{
  "status": "success",
  "newXPUB": "EXTENDED_PUBLIC_KEY",
  "XPUBIndex": 0
}

Gateway assumes you are using BIP44 derivation for XPUB keys. When your new key is provided, the XPUB index (the address index in BIP44 derivation) is reset to 0.

To specify a new payout XPUB key for a merchant account, send a PATCH request to /user/payout/xpub.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes newXPUB The new payout XPUB key for the merchant

Getting Your Username

Get the current username for the merchant account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/name',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

A successful response will look like this:

{
  "status": "success",
  "username": "johngalt12"
}

To return your current username, send a GET request to /user/name.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Changing Your Username

Change the account username:

let result = await axios.post(
  'https://api.gateway.cash/v2/user/name',
  {
    APIKey: 'YOUR_API_KEY',
    newUsername: 'JohnGalt12'
  }
)

Your new username will be sent back for confirmation. Usernames are converted to lower case before being stored in the database.

{
  "status": "success",
  "newUsername": "johngalt12"
}

To update your username, send a PATCH request to /user/name.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes newUsername The new username for the merchant account

Changing Your Password

Change the account password:

let result = await axios.patch(
  'https://api.gateway.cash/v2/user/password',
  {
    APIKey: 'YOUR_API_KEY',
    newPassword: 'B@nk3rSh!llzSkillz#!/bin/sh'
  }
)

Your password will not be sent back for confirmation, so store it safely! It's generally a good idea to encrypt credentials when plausible. Passwords are always hashed and salted prior to being stored in the database.

{
  "status": "success"
}

To set a new password, send a PATCH request to /user/password.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes newPassword The new password for the merchant account

Viewing API Keys

Get a list of all API keys associated with your account:

let result = await axios.get(
  'https://api.gateway.cash/v2/api/keys',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

The request will result in a response like this:

{
  "APIKeys": [
    {
      "created": "TIMESTAMP",
      "active": "true",
      "APIKey": "API_KEY",
      "label": "Created at registration"
    },
    {
      "created": "TIMESTAMP",
      "active": "false",
      "APIKey": "API_KEY",
      "label": "Test",
      "revokedDate": "TIMESTAMP"
    }
  ]
}

To get a list of the API keys for your account, send a GET request to /api/keys.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Adding an API Key

Add a new API key:

let result = await axios.put(
  'https://api.gateway.cash/v2/api/key',
  {
    "APIKey": "YOUR_CURRENT_API_KEY",
    "label": "Mobile App"
  }
)

When successful, you will get this back:

{
  "status": "success",
  "newAPIKey": "YOUR_NEW_API_KEY"
}

New API keys can be generated by sending a PUT request to /api/key.

Parameters

Required Name Description
Yes APIKey A current API key which is active
No label The label for the new key

You will be able to see your new API key by sending a GET request to /api/keys.

Deleting an API Key

Permanently delete an API key:

let result = await axios.delete(
  'https://api.gateway.cash/v2/api/key',
  {
    "APIKey": "YOUR_CURRENT_API_KEY",
    "APIKeyToPermanentlyDelete": "KEY_TO_DELETE"
  }
)

When successful, you will get this back:

{
  "status": "success"
}

To permanently delete a key from your account, send a DELETE request to /api/key.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes APIKeyToPermanentlyDelete The key which is to be deleted

Modifying an API Key

Deactivate an API key:

let result = await axios.patch(
  'https://api.gateway.cash/v2/api/key',
  {
    "APIKey": "YOUR_CURRENT_API_KEY",
    "action": "deactivate",
    "APIKeyToDeactivate": "KEY_TO_DEACTIVATE"
  }
)

Reactivate an API key:

let result = await axios.patch(
  'https://api.gateway.cash/v2/api/key',
  {
    "APIKey": "YOUR_CURRENT_API_KEY",
    "action": "deactivate",
    "APIKeyToReactivate": "KEY_TO_REACTIVATE"
  }
)

In any case, successful responses will appear as follows:

{
  "status": "success"
}

You can update certain aspects of your API key (such as its permissions) by sending a PATCH request to /api/key.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes action The action to be performed (see below)
Sometimes APIKeyToDeactivate The key to be deactivated
Sometimes APIKeyToReactivate The key to be reactivated

Possible Actions

Action Description
reactivate Reactivates an API key and allows it to be used again
deactivate Deactivates an API key so that it can no longer be used

Making Payments

This section covers the process of making and receiving payments with Gateway. The process is fairly straightforward, and no API keys are required.

Payment Processing

Payment processing with Gateway is intuitive and simple. Merchants and developers put PayButtons on their websites and apps so that customers can generate invoices and make payments for services.

Once the merchant sets up PayButton, the process starts with the customer; when they click the PayButton, an invoice gets generated and we await their payment. Once they pay, the receipt is stored with Gateway for the merchant.

More Details

To make a payment, the customer's browser uses the POST /pay API call with any payment information given to them by the merchant website (paymentID, callbackURL, etc). Gateway creates an invoice and responds with an address (the paymentAddress) where the customer can complete their payment.

Once the payment is complete, the customer's browser uses the POST /paid endpoint and sends the paymentAddress with the paymentTXID back to Gateway.

At this point, the customer is done and can move on with their day. Gateway maks the payment as pending. Pending payments are processed every 30 seconds by the fundsTransferService.

Funds Transfer Service

The Gateway fundsTransferService manages payments sent using the Gateway API. Every 30 seconds, it checks for and processes payments which have been marked as "pending".

For each payment marked as pending, fundsTransferService will do the following:

Broken Payments

When a customer pays an invoice but neglects to call the POST /paid endpoint and mark it as paid, the payment will still eventually arrive at the merchant's address.

The Gateway Broken Payments Service runs every 12 hours and checks the balances of all addresses over which Gateway has custody. Any invoices who's payment addresses have a balance are immediately assigned "pending" status at which point the payment is processed as normal.

Extended Public Keys (XPUB)

When a merchant sets their payout method to XPUB and provides a valid XPUB key for their account, there is no need for Gateway to forward the payment. The merchant is always in control of their money, and Gateway never sees the coins.

However, this can create some issues with contributions and Platforms. See the Registration and Platforms sections for more details.

Creating an Invoice

Create a new invoice and generate a payment address:

let result = await axios.post(
  'https://api.gateway.cash/v2/pay',
  {
    merchantID: 'MERCHANT_ID',
    paymentID: 'PAYMENT_ID',
    callbackURL: 'CALLBACK_URL'
  }
)

If successful, you will get back something like this:

{
  "status": "success",
  "paymentAddress": "BITCOIN_CASH_ADDRESS"
}

So, to print your payment address:

console.log(result.data.paymentAddress)

To open a new invoice with a merchant, send a POST request to /pay. Include their merchant ID in the request and you'll get a payment address back.

Parameters

Required Name Description
Yes merchantID The ID for the merchant for whom the payment is intended
No paymentID An identifier for the payment which will be shown to the merchant
No callbackURL See the Callbacks section

Marking Invoices as Paid

Send the request with the payment address and TXID:

let result = await axios.post(
  'https://api.gateway.cash/v2/paid',
  {
    paymentAddress: 'PAYMENT_ADDRESS',
    paymentTXID: 'PAYMENT_TXID'
  }
)

If successful, you should get back something like this:

{
  "status": "success"
}

Once an invoice has been paid, send a POST request to /paid to give the payment TXID to the server for processing.

Parameters

Required Name Description
Yes paymentAddress The payment address of the invoice
Yes paymentTXID The TXID of the transaction which pays the invoice

Gateway Platforms

Gateway Platforms are an innovative way for website operators, service providers and developers to take commissions from Bitcoin Cash payments. This section describes how to create, manage and deploy Platforms.

Overview

In this context, a platform refers to any website where users interact with each other, with each other's content or where they can buy things. Each project you work on shouldn't generally require more than one platform, but you can set commission rules so that certain things apply in certain cases but not others.

On Gateway, each platform has a merchant account designated as its owner. The owner can set commission rules for the platform and take a percentage of the earnings as profit.

Platform Users

Platform users are created in the same manner as normal users. See the Registration section for more info. Include the platformID with a registration request to create a new Platforms user.

The new user will be exclusively owned by the platform and any payments sent to their merchantID will be subject to the commissions and policies of the platform.

Creating a Platform

Create a new platform:

let result = await axios.put(
  'https://api.gateway.cash/v2/platforms',
  {
    APIKey: 'YOUR_API_KEY',
    name: 'FaceHook',
    description: "Hooks people's faces"
  }
)

Successful responses include the new platform ID:

{
  "status": "success",
  "platformID": "NEW_PLATFORM_ID"
}

Setting up a Gateway Platform is as simple as sending a PUT request to /platforms.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
Yes name The name of the new platform
No description The platform description (defaults to "New Platform")

When you create a new platform, the merchant account who's API key was used to send the PUT request will be made the owner of the new platform. Until they delegate permission to others, their API key must be used in any request that deals with the commissions or policies of their new platform.

Listing Your Platforms

List your platforms:

let result = await axios.get(
  'https://api.gateway.cash/v2/platforms',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

The response will look like this:

{
  "status": "success",
  "numberOfPlatforms": 2,
  "platforms": [
    {
      "created": "CREATED_TIMESTAMP",
      "name": "Platform Name",
      "description": "Platform Description",
      "platformID": "PLATFORM_ID"
    },
    {
      "created": "CREATED_TIMESTAMP",
      "name": "Platform Name",
      "description": "Platform Description",
      "platformID": "PLATFORM_ID"
    }
  ]
}

You can send a GET request to /platforms to view all platforms to which you have access.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the account for which a list of platforms is to be generated

Changing Platform Settings

Update the platform name and settings:

let result = await axios.patch(
  'https://api.gateway.cash/v2/platforms',
  {
    APIKey: 'YOUR_API_KEY',
    platformID: 'YOUR_PLATFORM_ID',
    newName: 'HookFace',
    newDescription: 'Avoid a trademark lawsuit with Mark Zuckerberg'
  }
)

A successful response will look like this:

{
  "status": "success",
  "newName": "NEW_NAME",
  "newDescription": "NEW_DESCRIPTION",
  "platformID": "YOUR_PLATFORM_ID"
}

The PATCH /platforms endpoint allows you to specify new settings for a platform. This is how the policies that govern your platforms are managed.

Parameters

Required Name Description
Yes APIKey An active API key belonging to someone with permission
Yes platformID The ID of the platform to be updated
No newName A new name for the platform
No newDescription A new description for the platform
No newAllowXPUB Whether XPUB keys are allowed. Either "true" or "false".

Commission Rules

Commission rules are directives given to the Gateway payment processing service which determine when and how much of a commission is taken from which payments, and where the commission is to be sent.

Listing Commissions

Get a list of commissions:

let result = await axios.get(
  'https://api.gateway.cash/v2/commissions',
  {
    params: {
      APIKey: "YOUR_API_KEY",
      platformID: "YOUR_PLATFORM_ID"
    }
  }
)

a successful response will look like this:

{
  "status": "success",
  "numberOfCommissions": 2,
  "commissions": [
    {
      "label": "Federal Gov't Theft",
      "commissionID": "COMMISSION_ID",
      "commissionAmount": "0.00",
      "commissionCurrency": "USD",
      "commissionPercentage": "30.00",
      "commissionLessMore": "more",
      "commissionMethod": "address",
      "commissionXPUB": null,
      "commissionAddress": "COMMISSION_BCH_ADDRESS"
    },
    {
      "label": "State Gov't Theft",
      "commissionID": "COMMISSION_ID",
      "commissionAmount": "0.00",
      "commissionCurrency": "USD",
      "commissionPercentage": "20.00",
      "commissionLessMore": "more",
      "commissionMethod": "XPUB",
      "commissionXPUB": "COMMISSION_XPUB_KEY",
      "commissionAddress": null
    }
  ]
}

To get a list of all commissions associated with a platform, send a GET request to /commissions.

Parameters

Required Name Description
Yes APIKey An active API key belonging to someone with permission
Yes platformID The ID of the platform for which a list is to be generated

In this example, two commissions are applied to all payments made through this platform. The first takes 30% of the total and the second takes 20% of the total. The merchant receives 50% of the total minus transaction fees.

Return Values

This endpoint returns an array called "commissions". This array contains the following values for each commission in the array:

Name Description
label A label for the commission
commissionID A unique identifier for the commission
commissionAmount An amount (in units of commissionCurrency) to be charged
commissionCurrency A three-digit currency code
commissionPercentage A percentage value for the commission
commissionLessMore A "less/more" value which determines which of commissionAmount and commissionPercentage to charge
commissionMethod Method of payout: either "address" or "XPUB"
commissionAddress The address to which the commission is to be paid
commissionXPUB The XPUB key to which the commission is to be paid

Adding a Commission

Add a commission to a platform:

let result = await axios.put(
  'https://api.gateway.cash/v2/commissions',
  {
    "APIKey": "YOUR_API_KEY",
    "platformID": "PLATFORM_ID",
    "commissionLabel": "Sales Tax",
    "commissionAmount": "0",
    "commissionCurrency": "BCH",
    "commissionPercentage": "5.00",
    "commissionLessMore": "more",
    "commissionMethod": "address",
    "commissionAddress": "BITCOIN_CASH_ADDRESS"
  }
)

When successful, the information is sent back along with a new commissionID:

{
  "status": "success",
  "commissionID": "NEW_COMMISSION_ID",
  "platformID": "YOUR_PLATFORM_ID",
  "commissionLabel": "Sales Tax",
  "commisionAddress": "BITCOIN_CASH_ADDRESS",
  "commissionXPUB": null,
  "commissionMethod": "address",
  "commissionAmount": "0",
  "commissionCurrency": "BCH",
  "commissionPercentage": "5.00",
  "commissionLessMore": "more"
}

You can add a commission to a platform by sending a PUT request to /commissions.

Parameters

Required Name Description
Yes APIKey An active API key belonging to someone with permission
Yes platformID The ID of the platform where the commission should be added
Yes commissionLabel A label for the new commission
Yes commissionAmount An amount in units of commissionCurrency
Yes commissionCurrency Three-digit currency code, BCH by default
Yes commissionPercentage A percentage, for example 0.25 for 0.25% or 25 for 25%
Yes commissionLessMore A less/more value indicating whether the lesser or the greater of commissionAmount or commissionPercentage should be charged
Yes commissionMethod The payout method, either "XPUB" or "address"
Sometimes commissionAddress Required when commissionMethod is "address"
Sometimes commissionXPUB Required when commissionMethod is "XPUB"

Changing a Commission

Update a commission:

let result = await axios.patch(
  'https://api.gateway.cash/v2/commissions',
  {
    "APIKey": "YOUR_API_KEY",
    "newCommissionID": "COMMISSION_ID",
    "newCommissionPercentage": "6.00",
    "newCommissionMethod": "XPUB",
    "newCommissionXPUB": "EXTENDED_PUBLIC_KEY"
  }
)

When successful, the new data will be sent back:

{
  "status": "success",
  "newCommissionLabel": "Sales Tax",
  "newCommisionAddress": "BITCOIN_CASH_ADDRESS",
  "newCommissionXPUB": "EXTENDED_PUBLIC_KEY",
  "newCommissionMethod": "XPUB",
  "newCommissionAmount": "0",
  "newCommissionCurrency": "BCH",
  "newCommissionPercentage": "6.00",
  "newCommissionLessMore": "more"
}

You can update a commission by sending a PATCH request to /commissions.

Parameters

Required Name Description
Yes APIKey An active API key belonging to someone with permission
Yes commissionID The ID of the commission to update
No newCommissionLabel A new label for the commission
No newCommissionAmount An amount in units of newCommissionCurrency
No newCommissionCurrency Three-digit currency code, BCH by default
No newCommissionPercentage A percentage, for example 0.25 for 0.25% or 25 for 25%
No newCommissionLessMore A less/more value indicating whether the lesser or the greater of newCommissionAmount or newCommissionPercentage should be charged
No newCommissionMethod The payout method, either "XPUB" or "address"
Sometimes newCommissionAddress Required when newCommissionMethod is being changed to "address"
Sometimes newCommissionXPUB Required when newCommissionMethod is being changed to "XPUB"

Deleting a Commission

Delete a commission:

let result = await axios.delete(
  'https://api.gateway.cash/v2/commissions',
  {
    "APIKey": "YOUR_API_KEY",
    "commissionID": "COMMISSION_ID"
  }
)

A successful response will look like this:

{
  "status": "success"
}

To delete a commission, send a DELETE request to /commissions

Parameters

Required Name Description
Yes APIKey An active API key belonging to someone with permission
Yes commissionID The ID of the commission to be deleted

Contributing to Gateway

When you contribute to Gateway, a portion of each payment made to your merchant account is deducted and sent to the Gateway donation address. We use these donations to make Gateway better and to help build new ideas in the Gateway ecosystem.

If you run a platform, you can add a Gateway contribution option for your users. Platform user accounts can set contribution settings in the same way as any other normal Gateway merchant account.

Contributions to Gateway are deducted before platform commissions, so there may be cases in which the platform commission is not paid since the payment isn't enough to cover both.

Contribution Rules

Contribution rules are very similar to the rules used for platform commissions. They take the form:

"I would like to contribute {A}% or {B} {C}, whichever is {D}."

We substitute as follows:

{A} = A percentage

{B} = An amount (in units if {C})

{C} = A three-digit currency code like BCH

{D} = Either "less" or "more"

Getting Contribution Info

Get current contribution settings for your account:

let result = await axios.get(
  'https://api.gateway.cash/v2/user/contribution',
  {
    params: {
      APIKey: 'YOUR_API_KEY'
    }
  }
)

The above request will return a result like this:

{
  "status": "success",
  "contributionAmount": "0.1",
  "contributionCurrency": "USD",
  "contributionPercentage": "30",
  "contributionLessMore": "less"
}

To get current contribution settings for the user, send a GET request to /user/contribution.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant

Return Values

The request returns a JSON object with the following parameters:

Parameter Description
contributionTotal The total ever contributed to Gateway by this user
contributionAmount The amount, in units of contributionCurrency, to contribute
contributionCurrency A three-digit currency code. Possible values: USD, EUR, JPY, CNY and of course BCH which is the default
contributionPercentage A percentage of each payment to send to Gateway
contributionLessMore Indicates whether the lesser or the greater of contributionAmount and contributionPercentage should be contributed

Updating Contribution Settings

Set updated contribution settings for your account:

let result = await axios.patch(
  'https://api.gateway.cash/v2/user/contribution',
  {
    APIKey: 'YOUR_API_KEY',
    newContributionAmount: '0.25',
    newContributionCurrency: 'EUR',
    newContributionPercentage: '2',
    newContributionLessMore: 'less'
  }
)

Values are sent back for confirmation:

{
  "status": "success",
  "newContributionAmount": "0.25",
  "newContributionCurrency": "EUR",
  "newContributionPercentage": "2",
  "newContributionLessMore": "less"
}

To update the contribution values for a merchant account, send a PATCH request to /user/contribution.

Parameters

Required Name Description
Yes APIKey An active API key belonging to the merchant
No newContributionAmount The amount, in units of newContributionCurrency, to contribute
No newContributionCurrency A three-digit currency code. Possible values: USD, EUR, JPY, CNY and of course BCH which is the default
No newContributionPercentage A percentage of each payment to send to Gateway
No newContributionLessMore Indicates whether the lesser or the greater of newContributionAmount and newContributionPercentage should be contributed

If you don't include all four values in your request, the ones included will be updated and the others will stay the same. All four values will always be sent back for confirmation.

In Case of Errors

Suppose Alice has a merchant account with the following generous contribution rules:

"I would like to contribute 10% or 1.00 USD, whichever is more."

Now, suppose Bob pays Alice 0.13 USD. Since 1.00 USD (the greater of the two values) cannot be deducted from the payment, Alice receives the entire payment of 0.13 USD.

In another case, if Carol sent Alice a large payment of 1337.00 USD, Gateway would receive 133.70 USD and Alice would receive the rest of the payment, minus transaction fees.

Contribution Defaults

Gateway will never enable contributions by default. In other words:

"I would like to contribute 0% or 0 BCH, whichever is less."

Callback URLs

Merchants can leverage callback URLs to get notified when a payment reaches their payout address. While callback URLs can be handy, there are a few things you need to keep in mind when building your applications.

Don't Trust. Verify.

Callbacks will be sent as POST requests to the URL provided by the customer when they requested the invoice. The data contained in a legitimate callback will look like this:

{
  "paymentAddress": "GATEWAY_INVOICE_PAYMENT_ADDRESS",
  "paymentTXID": "CUSTOMER_PAYMENT_TXID"
}

When you create a payment button and publish it on the internet (on your website, a check-out page, a mobile app or a point-of-sale system), your callback URL becomes public. This means that any malicious customer can see your callback URL and make illegitimate callbacks.

To solve this rather large problem, Gateway will always and only send a callback containing information that can (and must) be independently validated by you.

The Bitcoin Cash payment information, including the payment address and TXIDs asociated with relevant transactions will be included in legitimate callback requests.

As the merchant, you must, I repeat MUST VALIDATE that the provided transaction data satisfies your requirements. TXIDs can be queried from block explorers or a trusted Bitcoin Cash node. You need to ensure that the following are true:

Gateway has plans to release software that will make this easier in the future, but for now it may be advisable not to use callback URLs. You may prefer to log into gateway.cash and manually verify and ship your orders.

Failure to perform these validations will result in hackers defrauding you.

Parameters

Legitimate callbacks contain several pieces of information:

Name Description
transactions An array of transactions pertaining to the payment
paymentAddress The Gateway payment address used by the customer to pay the invoice