V1

Documentation for API V1. Extra simple if you want just start accepting crypto payments without headache. API V1 does not support Exchange or any Fiat currency related operations.

General information

Api endpoint for all requests is:

https://app.coinspaid.com/api/v1

Deposit flow

  1. You obtain new address from CoinsPaid API (for some currencies it may be address and tag) and store it somewhere on your side. After that you show this address to your customer in order to make a deposit.

  2. Customer sends some funds to this address.

  3. When transaction is sent by a customer - CoinsPaid sends a callback to your callback url with transaction details. It contains status, address, currency, amount and fees. If status is successful, you should deposit respective amount to customer balance on your side.

Withdrawal flow

  1. You request to send amount of money to address.

  2. Your request is validated on our side. If signature is correct, address is valid and you have enough balance - CoinsPaid responds you with the transaction object.

  3. You will receive a callback when transaction status is updated.

API Endpoints

post
Take new address for deposits

https://app.coinspaid.com/api/v1/addresses/take
This method is used for obtaining deposit address for receiving funds
Request
Response
Body Parameters
foreign_id
required
string
Any id from your side. We recommend using this parameter to identify customer on your side.
currency
required
string
Currency ISO you want to receive, for example: BTC
201: Created
If all is ok you will receive address object
{
"status": "ok",
"data": {
"id": 1,
"address": "1xds1983rh13ouifhj12fjo214f2f",
"foreign_id": "1872",
"tag": "tag-1"
}
}
400: Bad Request
In case of any errors you will receive json with human-readable error description
{
"errors": {
"currency": "Currency BTC is not enabled for your merchant"
},
"error_code": "forbidden_currency"
}

Please not that some cryptocurrencies require few parameters to receive funds, not only an address but also a "tag". For example Ripple (XRP) requires tag in order to send funds. If response has a non-empty tag parameter, please make sure to pass this "tag" to your customer otherwise this may lead to funds being delayed or lost.

post
Withdrawal

https://app.coinspaid.com/api/v1/withdrawal/make
Request funds withdrawal
Request
Response
Body Parameters
currency
required
string
Currency iso: BTC
foreign_id
required
string
Foreign id - unique identifier for your transaction
amount
required
string
Amount to send
address
required
string
Address to withdraw currency, for example:
201: Created
{
"status": "ok",
"data": {
"id": 1,
"currency": "BTC",
"currency_fee": "BTC",
"address": "address-string",
"tag": null,
"amount": "1.01",
"status": "processing"
}
}
400: Bad Request
{
"errors": {
"amount": "The amount field is required.",
"foreign_id": "The foreign id field is required.",
"address": "The address field is required.",
"currency": "The currency field is required."
},
"error_code": "not_enough_balance"
}
422: Unprocessable Entity
{
"errors": {
"amount": "Not enough amount",
"foreign_id": "The Foreign ID has already been taken.",
"currency": "Invalid balance."
},
"error_code": "not_enough_balance"
}

Foreign_id is used to identify the withdrawal. Foreign_id is a unique string that you send to CoinsPaid to avoid network issues and double sending of funds, and used to identify your requests. Common approach is to insert transaction record to your MySQL or any other relational database before calling withdrawal API, and send to CoinsPaid id from autoincrement field in your database.

Callbacks

For any transaction, deposit or withdrawal, transaction callback will come to the url that you specified in your merchant dashboard.

Deposit BTC
Withdrawal BTC
Deposit XRP
{
"id": "1127742",
"txid": "5145d00f9fe21cae7c0f94938ed91f8b493fae610f839703fde89aa2c5642bde",
"currency": "BTC",
"currency_fee": "BTC",
"confirmations": "0",
"amount": "0.01496462",
"fee": "0.00000000",
"address": "32dJKfbQLoHQVimtjt1U2h7Vw2kcbJbGVp",
"type": "deposit",
"status": "confirmed",
"error": ""
}
{
"id": "1127738",
"txid": "7266a32b9c893d62612f706b0c9f66fd20616dc86c46f68eefecbb7c3f9003be",
"foreign_id": "457630",
"currency": "BTC",
"currency_fee": "BTC",
"confirmations": "0",
"amount": "0.05190000",
"fee": "0.00057960",
"address": "1GCzAsthZADkcFH4VJyYvtcNuWQmXoavpx",
"type": "withdrawal",
"status": "confirmed",
"error": ""
}
{
"id": "216097",
"txid": "F78BE636A02CEE67EB36D87FAB90A098FA4946CBCB23726303A8AE6DA98BBD5C",
"currency": "XRP",
"currency_fee": "XRP",
"confirmations": "12",
"amount": "1399.75000000",
"fee": "0.00000000",
"address": "r3S9W2pYZj7vBueA8scxdJBSEVU2wjMedB",
"tag": "246861"
"type": "deposit",
"status": "confirmed",
"error": "",
}

To provide authentication for the callback, coinspaid API signs the POST your api key and secret:

  1. X-Processing-Key – Your public key

  2. X-Processing-Signature – POST body, signed by the your secret key HMAC-SHA512

Read this if you accept tokens. Please pay attention to having 2 currency fields - "currency" and "currency_fee". For USDT or ERC20 tokens "currency" will be USDT or *TOKENNAME* and "currency_fee" will be BTC or ETC / ETH, because in USDT blockchain fees are paid in BTC and in ERC20 fees paid by ETC / ETH respectively.

Transaction types can be:

Type

Meaning

deposit

Money arrived to your wallet from payer

withdrawal

Money sent from your wallet to address

Transaction statuses:

Status

Meaning

confirmed

Final. You are safe to process this transaction

not_confirmed

Transaction is not yet confirmed

error

Final. Some error occurred, pls see “error” field

cancelled

Final. This transaction is a double spend. Pay attention to this customer.

not_enough_fee

Not enough money to pay fee for transfers of ETH / ERC20 / USDT, when money are deposited transactions will try to transfer