Bitpace Merchant REST API

The Bitpace Merchant API is designed to be a predictable and intuitive interface to enable merchants to buy/sell supported cryptocurrencies.

API End Points:

Production

https://api.bitpace.com/api/v1/

Sandbox

https://api-sandbox.bitpace.com/api/v1/

Requests

Merchant API is REST-based.

Accepts and returns only JSON data.

All communication must be completed securely using HTTPS

Authorization

The Bitpace Merchant API implements JWT to allow clients to log in without exposing their credentials. The process involves several steps:

Acquire an access token

1. Use the access token to make authenticated requests
2. Before you begin, you will need to get the client credentials from us.

Acquire an access token

The authentication key consists of your merchant code and password.

curl -X POST 'https://api-sandbox.bitpace.com/api/v1/auth/token'
       -d '{"merchant_code" : "TESTMERCHANT0000111", "password" : "secret"}'

Exchanging an access token

The access token must be exchanged in any authorized requests in the header parameters. For example:

curl -X GET 'https://api-sandbox.bitpace.com/api/v1/buy/prices/BTC'
       -H 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElkIjoxLCJ0aW1lc3RhbXAiOjE1NDU4MjIwODd9.e_Qj_IgyZg09m5nJToQVZRDwVGJLTKLTgs0I3H9_uKM'

Flows:

Q. What are the available statuses of a DYNAMIC DEPOSIT/FIXED DEPOSIT?

A. For dynamic deposit: ‘PENDING’, ‘COMPLETED’, ‘FAILED’

For fixed deposit: ‘COMPLETED’, ‘EXPIRED’, ‘REFUNDABLE’, ‘REFUNDED’, ‘ACCEPTED’

Q.What would an example callback body look like?

A. We have number of examples (dynamic deposit, withdrawal and fixed deposit):

Dynamic Deposit

{
    "order_id": 53,
    "status": "COMPLETED",
    "type": "DEPOSIT",
    "customer_reference_id": "307388",
    "order_amount": "8.940444",
    "fee_amount": "0.33",
    "currency": "EUR",
    "cryptocurrency_amount": "0.003017",
    "cryptocurrency": "BTC",
    "blockchain_tx_id": "3a2b423ab6b64d97afda96166c7cb43ef8f0296bc4d970bff5ded11aeda64421",
    "network":"BITCOIN",
    "address":"0x123123123C194bF8BEAc8140E0C867B7215Eafe95"
}

Fixed Deposit

{
    "order_id": 53,
    "status": "COMPLETED",
    "type": "PAYMENT",
    "customer_reference_id": "307388",
    "order_amount": "8.94",
    "fee_amount": "0.33",
    "currency": "EUR",
    "cryptocurrency_amount": "0.003017",
    "cryptocurrency": "BTC",
    "blockchain_tx_id": "3a2b423ab6b64d97afda96166c7cb43ef8f0296bc4d970bff5ded11aeda64421",
    "network":"TRC20",
    "address":"TKQSfYyn4BpHnyrGcNKrG64uS6jiZ1Q13b"
}

Withdraw

{
    "order_id": 53,
    "status": "COMPLETED",
    "type": "WITHDRAW",
    "customer_reference_id": "307388",
    "fee_amount": "0.33",
    "blockchain_tx_id": "3a2b423ab6b64d97afda96166c7cb43ef8f0296bc4d970bff5ded11aeda64421",
    "network":"LTC",
    "address":"MBzFpsCLumCBVzrFAa1CXWHrTTwLc8xUm5"
}

Q. On which states do we receive callbacks?

A.  Callbacks sent for COMPLETED, REFUNDABLE, ACCEPTED, REFUNDED, FAILED, and EXPIRED statuses for all types of transactions

Q. Do I have to use your fixed deposit page? How can i create/use my own?

A. We provide a fixed deposit url ( ’/fixed-deposit/url' ) to the merchant and merchant redirects the customer to this url, customer see the fixed deposit page and has 30 minutes to send coins. The price remains locked for 30 minutes, after payment is done, it redirects to the merchant’s page which is provided by merchant on create fixed deposit request.

The other way to create fixed deposit is create fixed deposit without a fixed deposit page but with information of the fixed deposit, you need to create fixed deposit with “/fixed-deposit” and choose a coin type at second call “/fixed-deposit/{id}/conversion”.  After this call you will have all calculations and regarding info about the fixed payment and we will be waiting to complete the payment.

Q. I’ve locked the price via get order price method, does that mean i can create order from that price whenever i want?

A. No it doesn’t. The price is locked for 1 minute. Furthermore to this, there are number of mechanisms preventing price taken to be valid if there is a sudden price change. This is to make sure we minimize your loss under such circumstances.

Q. How many confirmations do you need?

A.  For fixed payments we only need to see in blockchain. For dynamic deposits we need one confirmation and for withdrawals 1 confirmations.

Q. What are the types of response codes and what do the mean?

A. Please see table below for all response codes:

Code: 00  - Message: Response Approved
Code: 05  - Message: Response Rejected
Code: 10  - Message: Response Waiting
Code: 300 - Message: Authorization token not found
Code: 301 - Message: Invalid authorization token
Code: 303 - Message: Merchant IP not Whitelisted
Code: 100 - Message: Merchant not found, check your credentials
Code: 105 - Message: Merchant not authorized to reach this resource
Code: 106 - Message: Requested order was not found
Code: 107 - Message: Minimum order amount should be: %s
Code: 108 - Message: Maximum order amount should be: %s
Code: 110 - Message: Mercant customer not found
Code: 115 - Message: Merchant customer deposit address not found
Code: 116 - Message: Merchant customer not found
Code: 120 - Message: Order cannot be refunded
Code: 121 - Message: Order cannot be accepted
Code: 150 - Message: Unsupported cryptocurrency
Code: 155 - Message: Required field missing: %s
Code: 156 - Message: Invalid value for field: %s
Code: 157 - Message: Deposit address not found
Code: 160 - Message: Price not available
Code: 165 - Message: Order cannot be created
Code: 166 - Message: Deposit address cannot be created
Code: 167 - Message: Withdraw order cannot be created
Code: 168 - Message: Another order is processing right now
Code: 170 - Message: Merchant balance not enough for this transaction
Code: 171 - Message: Customer balance not enough for this transaction
Code: 172 - Message: Amount must be positive
Code: 173 - Message: Merchant balance transaction state failure
Code: 201 - Message: Resource not found
Code: 400 - Message: Content not found
Code: 401 - Message: Unauthorized access
Code: 500 - Message: System Error

Q. Do you have an ETA on the notifications change?

A. For Fixed Deposit; as soon as the payment is made or 15 minute period is completed and partial payment is made or accepted. If no payment is made, notification will not be sent and payment will be expired.

For Dynamic Deposits;  it’s sent after 1 confirmation.

For Withdrawals;  it’s sent after 1 confirmation.

Q. How can I visualize fixed deposit payment page with pre-selected language?

A. You may add the language parameter as query string at the end of the url

This is a sample fixed deposit payment URL;

https://deposit.bitpace.com/sci/fixed-deposit/PAYM-2a7227a7b1c608ba

Add “lang” parameter

https://deposit.bitpace.com/sci/fixed-deposit/PAYM-2a7227a7b1c608ba?lang=en-EN

Here is the full list supported ; en-UK’, ‘tr-TR’, ‘ar-SA’, ‘de-DE’, ‘es-ES’, ‘es-MX’, ‘fr-FR’, ‘hi-IN’, ‘it-IT’, ‘iw-IL’, ‘ja-JP’, ‘ko-KR’, ‘ms-MY’, ‘no-NO’, ‘pt-PT’, ‘ru-RU’, ‘zh-CN’,‘vi-VN’

Q. How can we open fixed deposit page with pre-selected coin and pre-selected network?

You can add the /pay/[coin type]/[network] at the end of the URL.

This is a sample fixed deposit payment URL;

https://deposit.bitpace.com/sci/fixed-deposit/PAYM-2a7227a7b1c608ba

Add “/pay/[coin type]/[network]”

https://deposit.bitpace.com/sci/fixed-deposit/PAYM-2a7227a7b1c608ba/pay/USDT

or

https://deposit.bitpace.com/sci/fixed-deposit/PAYM-2a7227a7b1c608ba/pay/USDT/TRC20

When the customer opens the fixed deposit payment URL with a coin parameter, the customer can’t change his payment to another coin!

Q. How can we check the health status of the services?

Here is the health checker service;

https://api.bitpace.com/actuator/health

Q. What are the FIAT currencies that you support?

We may add any requested FIAT currency in our system. Currently added currencies are; EUR, USD, GBP, TRY, NOK, AUD, CAD, INR, JPY, ZAR, VND, BRL, ARS, MXN, PLN, THB, BGN, COP, CRC, MKD, HKD, PGK, PKR, PHP, RON, MVR, SGD, HUF, CHF