Merchant Tools

HTTP/Polled API

HTTP/Polled API

Introduction

The HTTP/polled API will provide access to our services and information to our sellers. If you would like to see a particular function added, please click the Contact menu item above. API calls are implemented as HTTP POST calls to https://www.coinpayments.net/api.php

API Setup

The only setup needed is to go to the API Keys page and generate an API key. You will be given a private and public key used to authenticate your API calls. Make sure you don't share your private key with any 3rd parties!
Note: You must click 'Edit Permissions' to enable most commands

Authentication

Every API call has a SHA-512 HMAC signature generated with your private key. Our server generates it's own HMAC signature and compares it with the API caller's. If they don't match the API call is discarded. The HMAC signature is sent as a HTTP header called 'HMAC'.

API Response

The API will return an array with 1 or 2 elements: 'error' and 'result'.
The result will always have an 'error' field. If its value is 'ok' (case-sensitive) the API call was a success, otherwise it will contain an error message.
If there is data to return to you, it will be stored as an array in the 'result' element.

Accepting Payments

There are 2 ways to accept payments with the CoinPayments API:
  • 'create_transaction' - Fixed-price Payments (most popular): You specify a price in fiat or cryptocurrency and what type of coin to receive. The buyer has to send the amount of coin returned by the API in order for the transaction to go through; if you want to receive for example $100 USD worth of Bitcoin for a client's order this is the choice for you. Fixed-price payments also have a multitude of payout options from storing in your CoinPayments Wallet, forwarding to another crypto wallet, converting to another coin, or settling in fiat currency.
  • 'get_callback_address' - Variable Payments: Gives you an address, any coins received by it are deposited into your CoinPayments Wallet and if you have an IPN URL set will notify your server of the payment. The buyer can send any amount of coins as many times as they want; if you want to assign a client an address they can use to "top up" any time this is the choice for you. This is a new interface and is only supported by Bitcoin and Bitcoin-based coins (Litecoin, Dogecoin, etc.) at this time, we are looking to add more support in the future.

Sample Code

PHP Class with Examples: coinpayments-phplib-1.0.zip (should work on PHP 5.2 and newer).
Low level function for calling the API (for those who like more of the nitty gritty): api-example.php.
NPM/JavaScript Library by OrahKokos.
Ruby Gem by Przemyslaw Janowski.

API POST Fields

API calls are made as basic HTTP POST requests using the following variables: (note: The POST data is regular application/x-www-form-urlencoded style data, not JSON or XML)
Field NameDescriptionRequired?
Main Fields
These fields will be here for all calls.
version1Yes
keyYour API public keyYes
cmdThe API you are callingYes
nonceOptional nonce (an integer that is always higher than in your previous API call) to prevent replay attacks. This is optional, however once used with a particular key it must always be used with that key from then on. Note: API nonce processing is non-atomic so you always want to wait for an API call to return before making another.No
formatThe format of response to return, json or xml. (default: json)No
Exchange Rates / Coin List (cmd = 'rates')
shortIf set to 1, the response won't include the full coin names and number of confirms needed to save bandwidth.No
acceptedIf set to 1, the response will include if you have the coin enabled for acceptance on your Coin Acceptance Settings page.No
Coin Balances (cmd = 'balances')
allIf set to 1, the response will include all coins, even those with a 0 balance.No
Create Transaction (cmd = 'create_transaction')
amountThe amount of the transaction in the original currency (currency1 below).Yes
currency1The original currency of the transaction.Yes
currency2The currency the buyer will be sending. For example if your products are priced in USD but you are receiving BTC, you would use currency1=USD and currency2=BTC.
currency1 and currency2 can be set to the same thing if you don't need currency conversion.
Yes
addressOptionally set the address to send the funds to (if not set will use the address you have set on the 'What Coins To Accept' page).
Remember: this must be an address in currency2's network.
No
buyer_nameOptionally set the buyer's name for your reference.No
buyer_emailOptionally set the buyer's email address. This will let us send them a notice if they underpay or need a refund.No
item_nameItem name for your reference, will be on the payment information page and in the IPNs for the transaction.No
item_numberItem number for your reference, will be on the payment information page and in the IPNs for the transaction.No
invoiceAnother field for your use, will be on the payment information page and in the IPNs for the transaction.No
customAnother field for your use, will be on the payment information page and in the IPNs for the transaction.No
ipn_urlURL for your IPN callbacks. If not set it will use the IPN URL in your Edit Settings page if you have one set.No
Get Callback Address (cmd = 'get_callback_address')
currencyThe currency the buyer will be sending.Yes
ipn_urlURL for your IPN callbacks. If not set it will use the IPN URL in your Edit Settings page if you have one set.No
Create Withdrawal (cmd = 'create_withdrawal')
amountThe amount of the withdrawal in the currency below.Yes
currencyThe cryptocurrency to withdraw. (BTC, LTC, etc.)Yes
addressThe address to send the funds to, either this OR pbntag must be specified.
Remember: this must be an address in currency's network.
See Desc
pbntagThe $PayByName tag to send the withdrawal to, either this OR address must be specified. This will also override any destination tag specified.See Desc
dest_tagThe destination tag to use for the withdrawal (for Ripple.)No
ipn_urlURL for your IPN callbacks. If not set it will use the IPN URL in your Edit Settings page if you have one set.No
auto_confirmIf set to 1, withdrawal will complete without email confirmation.No
Create Mass Withdrawal (cmd = 'create_mass_withdrawal')
wdThe withdrawals are passed in an associative array called wd, each having the parameters from 'create_withdrawal' except auto_confirm. The key of each withdrawal is used to return the result (same as 'create_withdrawal' again.) The key can contain ONLY a-z, A-Z, and 0-9. Withdrawals with empty keys or containing other characters will be silently ignored.Yes
Get Withdrawal Information (cmd = 'get_withdrawal_info')
idThe withdrawal ID to query.Yes
Create Transfer (cmd = 'create_transfer')
amountThe amount of the transfer in the currency below.Yes
currencyThe cryptocurrency to withdraw. (BTC, LTC, etc.)Yes
merchantThe merchant ID to send the funds to, either this OR pbntag must be specified.
Remember: this is a merchant ID and not a username.
See Desc
pbntagThe $PayByName tag to send the funds to, either this OR merchant must be specified.See Desc
auto_confirmIf set to 1, withdrawal will complete without email confirmation.No
Note:For coins that don't support transfers directly a withdrawal will be created instead, increasing the utility of this API call.No
Get Deposit Address (cmd = 'get_deposit_address')
currencyThe cryptocurrency to deposit. (BTC, LTC, etc.) This will return one of your personal keys if you have any or create one if you don't. Keys returned by this API are for your personal, non-commercial use.Yes
Get Transaction Information (cmd = 'get_tx_info')
txidThe transaction ID to query (API key must belong to the seller.) Note: It is recommended to handle IPNs instead of using this command when possible, it is more efficient and places less load on our servers.Yes
Get Multiple Transaction Information (cmd = 'get_tx_info_multi')
txidLets you query up to 25 transaction ID(s) (API key must belong to the seller.) Transaction IDs should be separated with a | (pipe symbol.) Note: It is recommended to handle IPNs instead of using this command when possible, it is more efficient and places less load on our servers.Yes
Get Account Transaction ID(s) (cmd = 'get_tx_ids')
limitThe maximum number of transaction IDs to return from 1-100. (default: 25)No
startWhat transaction # to start from (for iteration/pagination.) (default: 0, starts with your newest transactions.)No
allBy default we return an array of TX IDs where you are the seller for use with get_tx_info_multi or get_tx_info. If all is set to 1 returns an array with TX IDs and whether you are the seller or buyer for the transaction.No

Exchange Rate Response

A successful call to the 'rates' command will give you a result similar to this (JSON):
{
    "error": "ok",
    "result": {
        "EUR": {
            "is_fiat": "1",
            "rate_btc": "0.01372411",
            "last_update": "1378170061",
            "name": "Euro",
            "confirms": "10"
        },
        "GBP": {
            "is_fiat": "1",
            "rate_btc": "0.01197391",
            "last_update": "1378170061",
            "name": "British Pound",
            "confirms": "10"
        },
        "USD": {
            "is_fiat": "1",
            "rate_btc": "0.01012442",
            "last_update": "1378170061",
            "name": "United States Dollar",
            "confirms": "10"
        },
        "BTC": {
            "is_fiat": "0",
            "rate_btc": "1.00000000",
            "last_update": "1375473661",
            "name": "Bitcoin",
            "confirms": "6"
        },
        "LTC": {
            "is_fiat": "0",
            "rate_btc": "0.01936722",
            "last_update": "1378170061",
            "name": "Litecoin",
            "confirms": "10"
        }
    }
}
Each coin will have the following fields:
  • name = The coin's full/display name.
  • rate_btc = The exchange rate to Bitcoin.
  • is_fiat = If the coin is a fiat currency. You can use fiat currencies in your buttons so you don't get to get conversion rates yourself.
  • confirms = The number of confirms a coin has to have in our system before we send it to you.
  • accepted = 1 if you have the coin enabled for acceptance, 0 otherwise.
  • last_update = The last time the exchange rate was updated. This is a standad Unix timestamp.

Balances

A successful call to the 'balances' command will give you a result similar to this (JSON):
{
    "error": "ok",
    "result": {
        "BTC": {
            "balance": 10000000,
            "balancef": 0.10000000,
        }
    }
}
Each coin will have the following fields:
  • balance = The coin balance as an integer (in Satoshis).
  • balancef = The coin balance as a floating point number.

Create Transaction Response

A successful call to the 'create_transaction' command will give you a result similar to this (JSON):
{
   "error":"ok",
   "result":{
      "amount":"1.00000000",
      "address":"YYY",
      "txn_id":"XXX",
      "confirms_needed":"10",
      "timeout":9000,
      "status_url":"https:\/\/www.coinpayments.net\/index.php?cmd=status&id=XXX&key=ZZZ"
      "qrcode_url":"https:\/\/www.coinpayments.net\/qrgen.php?id=XXX&key=ZZZ"
   }
}
The result wil have the following fields:
  • amount = The amount for the buyer to send in the destination currency (currency2).
  • address = The address the buyer needs to send the coins to.
  • txn_id = The CoinPayments.net transaction ID.
  • confirms_needed = The number of confirms needed for the transaction to be complete.
  • timeout = How long the buyer has to send the coins and have them be confirmed in seconds.
  • status_url = A URL where the buyer can view the payment progress and leave feedback for you.

Create Withdrawal/Transfer Response

A successful call to the 'create_withdrawal' or 'create_transfer' command will give you a result similar to this (JSON):
{
   "error":"ok",
   "result":{
      "id":"hex string",
      "status":0,
   }
}
The result wil have the following fields:
  • id = The CoinPayments.net withdrawal ID.
  • status = 0 or 1. 0 = Withdrawal created, waiting for email confirmation. 1 = Withdrawal created with no email confirmation needed.

Create Mass Withdrawal Example

Example Call (using our code sample downloadable above)
$req = array(
        'wd[wd1][amount]' => 1.00,
        'wd[wd1][address]' => '1BitcoinAddress',
        'wd[wd1][currency]' => 'BTC',
        'wd[wd2][amount]' => 0.0001,
        'wd[wd2][address]' => '1BitcoinAddress',
        'wd[wd2][currency]' => 'BTC',
        'wd[wd3][amount]' => 0.0001,
        'wd[wd3][address]' => '1BitcoinAddress',
        'wd[wd3][currency]' => 'LTC',
        'wd[wd4][amount]' => 0.01,
        'wd[wd4][address]' => '1BitcoinAddress',
        'wd[wd4][currency]' => 'BTC',
);
$return = coinpayments_api_call('create_mass_withdrawal', $req);
print_r($return);
Example Response from the Call Above
The 1st three withdrawals have purposeful errors, the 4th has correct parameters:
(
    [error] => ok
    [result] => Array
        (
            [wd1] => Array
                (
                    [error] => That amount is larger than your balance!
                )

            [wd2] => Array
                (
                    [error] => Minimum withdrawal amount is 0.00020000 for this coin!
                )

            [wd3] => Array
                (
                    [error] => That is not a valid address for that coin!
                )

            [wd4] => Array
                (
                    [error] => ok
                    [id] => 5d2b60b70c2ee37b954c197f6907f7743286693163c388815dd18bb49188aa48
                    [status] => 1
                )

        )
)

Get Withdrawal Information

A successful call to the 'get_withdrawal_info' command will give you a result similar to this (JSON):
{  
   "error":"ok",
   "result":{  
      "time_created":1391924372,
      "status":2,
      "status_text":"Complete",
      "coin":"BTC",
      "amount":40000000,
      "amountf":"0.40000000",
      "send_address":"1BitcoinAddress",
      "send_txid":"hex_txid"
   }
}
The result wil have the following fields:
  • time_created = The time the withdrawal request was submitted.
  • status = The status of the withdrawal (-1 = Cancelled, 0 = Waiting for email confirmation, 1 = Pending, 2 = Complete).
  • status_text = The status of the withdrawal in text format.
  • coin = The ticker symbol of the coin for the withdrawal.
  • amount = The amount of the withdrawal (in Satoshis).
  • amountf = The amount of the withdrawal (as a floating point number).
  • send_address = The address the withdrawal was sent to. (only in response if status == 2)
  • send_txid = The coin TX ID of the send. (only in response if status == 2)

Get Callback Address / Get Deposit Address

A successful call to the 'get_callback_address' or 'get_deposit_address' command will give you a result similar to this (JSON):
{  
   "error":"ok",
   "result":{  
      "address":"1BitcoinAddress",
      "pubkey":"",
      "dest_tag":100,
   }
}
The result wil have the following fields:
  • address = The address to deposit the selected coin into your CoinPayments Wallet.
  • pubkey = NXT Only: The pubkey to attach the 1st time you sent to the address to activate it.
  • dest_tag = Ripple/Stellar-based Only: The destination tag to set for depositing into your CoinPayments Wallet.