Bitpace Merchant REST API
by Bitpace

Bitpace Merchant REST API

Cryptocurrency payment gateway for businesses
Introduction

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:

Authorization
Authorization Token
POST /auth/token
Authorization Token
POST /auth/token

Authentication

Open

This endpoint is used to acquire the access token. Lifetime of the token is 10 hours. Creating a new one doesn’t revoke the previous token.

Request body

Object
merchant_code
string
password
string

Responses

200 OK
Body
Object
data
Object
token
string

Valid for 10 hours

code
string
message
string
status
string
Response Example
{
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElkIjoxLCJ0aW1lc3RhbXAiOjE1NDU4MjIwODd9.e_Qj_IgyZg09m5nJToQVZRDwVGJLTKLTgs0I3H9_uKM"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}
Prices
Get Buy Price
GET /buy/prices/{cryptocurrencyCode}
Get Sell Price
GET /sell/prices/{cryptocurrencyCode}
Get Buy Price
GET /buy/prices/{cryptocurrencyCode}

Merchant can get the best current buy rate of a cryptocurrency for buys and withdrawals.

Path variables

cryptocurrencyCode
string required

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
buy_price
number

Coin fiat money price

Example:
3200
currency
string

Fiat money currency

Example:
EUR
cryptocurrency
string

Coin type

Example:
BTC
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "buy_price": 3302.4382,
        "currency": "EUR",
        "cryptocurrency": "BTC"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "8d1bc7316bec4f13"
}
Get Sell Price
GET /sell/prices/{cryptocurrencyCode}

Merchant can get the best current sell rate of a cryptocurrency for sells and deposits.

Path variables

cryptocurrencyCode
string required

currencyPair

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
sell_price
number
currency
string

Fiat money currency

Example:
EUR
cryptocurrency
string

Coin type

Example:
BTC
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "sell_price": 3302.4252,
        "currency": "EUR",
        "cryptocurrency": "BTC"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId" : "00e5e697d1ed6d92"
}
Balance
Get Fiat Balance
GET /balance
Get All Balances
GET /balance/currency
Get Balance By Currency
GET /balance/currency/{currencyCode}
Get Ledger Activities
GET /balance/merchant-balance/ledgers
Get Fiat Balance
GET /balance

Merchant can get his balance for buy and sell orders.

Request headers

Authorization
string required

Responses

200 200

OK

Body
*/*
Object
data
Object
buysell
Object
balance
number
currency
string
exchange
Object
balance
number
Example:
200000
currency
string

FIat money currency

Example:
EUR
code
string
message
string
status
string
traceId
string
show more
Response Example
{
    "data": {
        "buysell": {
            "balance": "0",
            "currency": "EUR"
        },
        "exchange": {
            "balance": "984554.09",
            "currency": "EUR"
        }
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "54439a729d0bb8ff"
}
Get All Balances
GET /balance/currency

Merchant can get all defined crypto currencies and FIAT balances

Request headers

Authorization
string required

Responses

200 200

OK

Body
*/*
Object
data
Object
balance
number
currency
string
Example:
EUR
code
string
message
string
status
string
traceId
string
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": [
        {
            "balance": 800921,
            "currency": "EUR"
        },
        {
            "balance": 11.311195,
            "currency": "BTC"
        },
        {
            "balance": 12.784886,
            "currency": "ETH"
        }
    ],
    "status": "APPROVED",
    "traceId": "14409c856bde4107"
}
Get Balance By Currency
GET /balance/currency/{currencyCode}

Merchant can get his exchange balance by parameter

Path variables

currencyCode
string required
Example:
EUR, BTC

Request headers

Authorization
string required

Responses

200 200

OK

Body
*/*
Object
data
Object
balance
number
currency
string
Example:
EUR
code
string
message
string
status
string
traceId
string
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": {
        "balance": 800921,
        "currency": "EUR"
    },
    "status": "APPROVED",
    "traceId": "e51b5ce7896c93f7"
}
Get Ledger Activities
GET /balance/merchant-balance/ledgers

Merchant can get his ledger activities

Request parameters

page
integer optional

Page number

size
integer optional

Page size, row count per page

startDate
string optional

Format:YYYY-MM-DD Should earlier than today.

Example:
2022-09-05
endDate
string optional

Format:YYYY-MM-DD Should be later than start date.

Example:
2022-09-06

Request headers

Authorization
string required

Responses

200 200

OK

Body
*/*
Object
data
Object
content
Array
Object
orderId
integer

Order Id

Example:
32213
amount
number

Order amount

Example:
232
preBalance
number

Balance before this order

postBalance
number

Balance after this order

type
string

Order type

Example:
PAYMENT, WITHDRAW, DEPOSIT, BUY, SELL, TRANSFER, COIN_STORE, COIN_WITHDRAW, REFUND, WITHDRAW_FAILED
transactionType
string

effecting balance as increasing or decreasing

Example:
CREDIT, DEBIT
currencyCode
string

FIAT Money or cryptocoin types

Example:
BTC, EUR, ...
createdAt
string

Datetime

Example:
2022-08-16T07:24:51.019339
pageable
Object
sort
Object
sorted
boolean
unsorted
boolean
empty
boolean
pageSize
integer
pageNumber
integer
offset
integer
paged
boolean
unpaged
boolean
totalPages
integer

Total page count

totalElements
integer

Total row size in the ledger

number
integer
size
integer

How many rows are requested in a page

numberOfElements
integer

How many rows are existing in the selected page

sort
Object
first
boolean

If the result is the first page this area will be TRUE, else FALSE

last
boolean

If the result is the last page this area will be TRUE, else FALSE

empty
boolean

If result data is empty this area will be TRUE, else FALSE

code
string
message
string
status
string
traceId
string
show more
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": {
        "content": [
            {
                "orderId": 45698,
                "amount": 50.130000,
                "preBalance": 453668.000000,
                "postBalance": 453718.130000,
                "type": "PAYMENT",
                "transactionType": "CREDIT",
                "currencyCode": "EUR",
                "createdAt": "2022-08-22T14:50:04.747269"
            },
            {
                "orderId": 45701,
                "amount": 34.960000,
                "preBalance": 453633.040000,
                "postBalance": 453668.000000,
                "type": "PAYMENT",
                "transactionType": "CREDIT",
                "currencyCode": "EUR",
                "createdAt": "2022-08-22T14:14:03.353505"
            },
            {
                "orderId": 45697,
                "amount": 0.000550,
                "preBalance": 6.458402,
                "postBalance": 6.457852,
                "type": "WITHDRAW",
                "transactionType": "DEBIT",
                "currencyCode": "BTC",
                "createdAt": "2022-08-22T12:25:12.266353"
            }
        ],
        "pageable": {
            "sort": {
                "sorted": false,
                "unsorted": true,
                "empty": true
            },
            "pageSize": 3,
            "pageNumber": 0,
            "offset": 0,
            "paged": true,
            "unpaged": false
        },
        "totalPages": 1,
        "totalElements": 3,
        "last": true,
        "number": 0,
        "size": 3,
        "numberOfElements": 3,
        "sort": {
            "sorted": false,
            "unsorted": true,
            "empty": true
        },
        "first": true,
        "empty": false
    },
    "status": "APPROVED",
    "traceId": "3c7e9e390e671eeb"
}
show more
Orders
Get Order Price
POST /orders/prices
Create Order
POST /orders
Get Order Details
GET /orders/{orderId}
Get Order Price
POST /orders/prices

Merchant can get an order price.

Request headers

Authorization
string required

Request body

application/json
Object
cryptocurrency_amount
number nullable

Coin Amount

cryptocurrency
string

Coin Type

network
string

Optional. It should be one of the blockchain network code we support. ERC20 for ETH, USDT, USDC, LINK

Example:
TRC20, ERC20, BTC
currency_amount
number nullable

FIAT Money Amount

currency
string

FIAT Money Type

order_type
string
Enumeration:
BUY

Get a Buy Price to buy coins that you are gonna hold with Bitpace.

SELL

Get a Sell Price to sell your coins that you are holding with Bitpace.

WITHDRAW

Get a Withdraw Price to buy then withdraw it to a given customer coin wallet address.

exclude_withdraw_fee
string

Displaying prices with/without fees shown separately & deducting from sending amount or merchant balance

Enumeration:
false

Pricing will be displayed as usual and withdrawal fee will be deducted from the sending amount

true

the withdrawal fee will not be deducted from amount being sent, it will be deducted from the merchant balance and fee will be displayed in the response.

Default:
false
show_fees
string

Merchant Comission fee appears in the response

Enumeration:
false

Merchant commision fee doesn’t appear

true

Merchant commision fee appears

Default:
false

Responses

200 OK
Body
Object
data
Object
token
string

It will be valid for 30 seconds.

total_amount
number
currency
string
cryptocurrency_amount
number
cryptocurrency
string
withdraw_fee
number

if you add the “excluded_withdraw_fee” field in your request. it will be displayed. It is cryptocurrency amount.

withdraw_fee_value
number

if you add the “excluded_withdraw_fee” field in your request. It is FIAT value of cryptocurrency amount

merchant_commission_fee
number

if you add the “show_fees” field in your request as true, merchant commission fee will be added the response. It is FIAT value in requested currency.

code
string
message
string
status
string
traceId
string
show more
Response Example
{
    "data": {
        "token": "nRRMlCnAwr5SHWeEaqe3a5BQLCAxtHVAEexsJsDcmhYmbCAEts1GM9U9ehek0IpO7YP4w1PLgrW3w6WSzSDBFq6EFWzt9iCqE1MhSmR1Fpo=",
        "total_amount": 703.62,
        "currency": "EUR",
        "cryptocurrency_amount": 0.223121,
        "cryptocurrency": "BTC",
        "withdraw_fee": 0.0002, //Displayed if you add exclude_withdraw_fee 
        "withdraw_fee_value": 10.12 //Displayed if you add exclude_withdraw_fee
        "merchant_commission_fee": 1.00 //Displayed if you add show_fees 
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "2b49d543e7804cd0"
}
show more
Create Order
POST /orders

Merchant can create an order.

Request headers

Authorization
string required

Request body

Object
token
string required
customer
Object
reference_id
string
first_name
string nullable

Customer’s first name

Example:
John
last_name
string nullable

Customer’s last name

Example:
Smith
email
string

Customer’s email address

Example:
johnsmith@gmail.com
withdraw
Object

Only for withdraws

address
string

Coin wallet address for withdrawals

destination_tag
string

For XRP, EOS and XLM orders

Responses

200 OK
Body
Object
data
Object
order_id
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "order_id": 11
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "cf42bf4929c9d924"
}
Get Order Details
GET /orders/{orderId}

Merchants can query order details.

Path variables

orderId
string required

Order id

Request headers

Authentication
string required

Authentication token

Responses

200 OK
Body
Object
order_id
number required

Unique id of an order

Example:
123
type
string required

Order type

Enumeration:
BUY
SELL
WITHDRAW
DEPOSIT

For Merchant’s own deposits

status
string required

Current status of an order

Enumeration:
PENDING
COMPLETED
order_amount
number required

Currency amount of an order

Example:
78.23
currency
string required

Fiat money currency code

Example:
EUR
cryptocurrency_amount
number required

Cryptocurrency amount of an order

Example:
1.0223
cryptocurrency
string required

Cryptocurrency code

Example:
BTC
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": {
        "order_id": 11,
        "type": "WITHDRAW",
        "status": "COMPLETED",
        "order_amount": 50.00,
        "currency": "EUR",
        "cryptocurrency_amount": 0.005910,
        "cryptocurrency": "BTC"
    },
    "status": "APPROVED",
    "traceId": "902a3c59a3b7f94c"
}
Dynamic Deposits

Merchants can create dynamic deposit addresses for their customers and get deposit addresses related to any customer.

Create Deposit Address
POST /customer/deposit/address
Get Deposit Address List
GET /customer/deposit/address/referenceId/{referenceId}
Get Last Deposit Address
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}
Get Deposit Address List By Coin
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}/all
Supported Crypto Currencies
GET /customer/deposit/cryptocurrencies
Supported Networks
GET /customer/deposit/networks/{cryptocurrencyCode}
Supported Settlement Currency List
GET /customer/deposit/cryptocurrencies/settlement/
Create Deposit Address
POST /customer/deposit/address

Merchant can create a customer spesific coin wallet address to receive coins. These addresses are allocated for the specific customer. Whenever they send the coin as much as they want, the system will create a “dynamic deposit order” with the received amount of money converted from received coins. We are using smart contracts so, some of the coins may use the same wallet addresses for the same customer.

Request headers

Authorization
string required

Request body

Object
cryptocurrency
string required
Example:
btc
network
string

Optional. It should be one of the blockchain network code we support

Default:
ERC20 for ETH, USDT, USDC, LINK
Examples:
ERC20TRC20BTC
customer
Object
reference_id
string required

Merchant’s customer reference id

Example:
customer1234
first_name
string nullable

Customer’s name

Example:
John
last_name
string nullable

Customer’s surename

Example:
Smith
email
string required

Customer’s email address

Example:
johnsmith@domain.com
settlement_currency
string

The crypto currency type that, the deposit arrived to this addreess will be automatically converted to

Default:
EUR
Examples:
USDCEUR

Responses

200 200

OK

Body
*/*
Object
data
Object
address
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Get Deposit Address List
GET /customer/deposit/address/referenceId/{referenceId}

Fetches all created deposit addresses for a customer.

Path variables

referenceId
string required

Merchant’s customer reference id

Example:
customer1234

Request parameters

settlement_currency
string optional

Reponse will contains the settlement currency?

Enumeration:
false

(default) Do not return the settlement currency

true

Return the settlement currency

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Array
Object
code
string
Example:
BTC
address
string
Example:
2N89APxLxMUU6XaytrgSuhce2g93teMyN1w
settlement_currency
string

(Optional, if only parameter exists) The currency type that, the deposit arrived to this addreess will be automatically converted to (For now only EUR, USDT, USDC available)

Examples:
USDTUSDCEUR
code
string
message
string
status
string
traceId
string
Response Example
Settlement Currency example
{
    "data": [
        {
            "code": "BTC",
            "address": "2N89APxLxMUU6XaytrgSuhce2g93teMyN1w"
        },
        {
            "code": "BCH",
            "address": "2NFMVznLLbs9XAkh1dSskGCbWiu71XrZpWk"
        }
    ],
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
{
    "data": [
        {
            "code": "BTC",
            "address": "2N89APxLxMUU6XaytrgSuhce2g93teMyN1w",
            "settlement_currency":"USDT"
        },
        {
            "code": "BCH",
            "address": "2NFMVznLLbs9XAkh1dSskGCbWiu71XrZpWk",
             "settlement_currency":"EUR"
        }
    ],
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Get Last Deposit Address
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}

Fetches a previously created deposit address for a customer.

Path variables

referenceId
string required

Merchant’s customer reference id

Example:
customer1234
cryptocurrencyCode
string required

Coin type

Example:
BTC

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
address
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Get Deposit Address List By Coin
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}/all

Fetches all created deposit address by cryptocurrency code for a customer.

Path variables

referenceId
string required

Merchant’s customer reference id

Example:
customer1234
cryptocurrencyCode
string required

Coin type

Example:
BTC

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Array
Object
code
string
address
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": [
        {
            "code": "BTC",
            "address": "2N89APxLxMUU6XaytrgSuhce2g93teMyN1w"
        },
        {
            "code": "BTC",
            "address": "2NFMVznLLbs9XAkh1dSskGCbWiu71XrZpWk"
        }
    ],
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Supported Crypto Currencies
GET /customer/deposit/cryptocurrencies

Get list of supported crypto currencies in dynamic deposits.

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
active
Array of string

List items

code
string
message
string
status
string
traceId
string
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": [
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "BTC",
            "name": "Bitcoin",
            "supportedSettlement": false
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "ETH",
            "name": "Ethereum",
            "supportedSettlement": false
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "BCH",
            "name": "Bitcoin Cash",
            "supportedSettlement": false
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "LTC",
            "name": "Litecoin",
            "supportedSettlement": false
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "XRP",
            "name": "Ripple",
            "supportedSettlement": false
        },
        
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "USDT",
            "name": "USDT",
            "supportedSettlement": true
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "USDC",
            "name": "USDC",
            "supportedSettlement": true
        },
        {
            "depositActive": false,
            "fixedDepositActive": false,
            "withdrawActive": true,
            "paymentActive": false,
            "tradeActive": true,
            "code": "AVAX",
            "name": "Avalanche",
            "supportedSettlement": false
        }
    ],
    "status": "APPROVED",
    "traceId": "c06c232ad7277629"
}
show more
Supported Networks
GET /customer/deposit/networks/{cryptocurrencyCode}

Get list of supported networks for a specific crypto currenciy in dynamic deposits.

Path variables

cryptocurrencyCode
string required

Coin Type

Examples:
USDTBTC

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Array of string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "ERC20",
        "TRC20"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "a78477f154e84076"
}
Supported Settlement Currency List
GET /customer/deposit/cryptocurrencies/settlement/

Get list of supported crypto currencies which is available to use as settlement currency

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
active
Array of string

List items

code
string
message
string
status
string
traceId
string
Response Example
{
    "code": "00",
    "message": "Response Approved",
    "data": [
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "USDT",
            "name": "USDT",
            "supportedSettlement": true
        },
        {
            "depositActive": true,
            "fixedDepositActive": true,
            "withdrawActive": true,
            "paymentActive": true,
            "tradeActive": true,
            "code": "USDC",
            "name": "USDC",
            "supportedSettlement": true
        }
    ],
    "status": "APPROVED",
    "traceId": "724830220364fe6d"
}
show more
Fixed Deposits

Fixed Deposits differ from dynamic deposit as there is an expected fixed amount from this action. Whereas, deposits can be made in any amount above minimum transaction value.

Create Fixed Deposits
POST /fixed-deposit
Fixed Deposit Conversion
POST /fixed-deposit/{id}/conversion
Create Fixed Deposit Url
POST /fixed-deposit/url
Refund Fixed Deposit
POST /fixed-deposit/refund
Accept Fixed Deposit
POST /fixed-deposit/accept
Create Fixed Deposits
POST /fixed-deposit

Merchant can create both amount and customer specific unique fixed deposit.

Request headers

Authorization
string required

Request body

Object
order_amount
number required

Order FIAT money amount

Example:
200
currency
string

FIAT Currency Type

Enumeration:
EUR
USD
GBP
TRY
MXN
THB
PLN
BRL
NOK
INR
CAD
AUD
ZAR
ARS
VND
return_url
string required

Merchant’s return url

Example:
https://www.merchant.com/payment/thankyou.html
failure_url
string required

Merchant’s failure url

Example:
https://www.merchant.com/payment/error.html
merchant_name
string nullable

Merchant’s name on invoice page

description
string nullable
ip_address
string required

Customer’s ip address

Example:
192.101.118.1
customer
Object
reference_id
string required
first_name
string nullable

Customer’s name

Example:
John
last_name
string nullable

Customer’s last name

Example:
Smith
email
string required

Customer’s email address

Example:
johnsmith@gmail.com
show more

Responses

200 OK
Body
Object
data
Object
order_id
string

Order id

Example:
103
code
string
message
string
status
string
traceId
string
Fixed Deposit Conversion
POST /fixed-deposit/{id}/conversion

Merchant can confirm previously created fixed deposit with cryptocurrency code.

Path variables

id
string required

Order id that will be confirmed.

Request headers

Authorization
string required

Request body

Object
cryptocurrency
string

Cryptocurrency code

Example:
BTC
network
string

Optional. It must be one of the blockchain network code we support

Default:
ERC20 for ETH, USDT, USDC, LINK
Examples:
ERC20TRC20BTC

Responses

200 OK
Body
Object
data
Object
order_id
string

Order id

Example:
103
status
string

Order status

order_amount
number

Order amount

currency
string

Currency code

cryptocurrency_amount
number

Cryptocurrency amount

cryptocurrency
string

Cryptocurrency code

address
string

Blockchain address

merchant_name
string

Merchant name

expires_in
string
code
string
message
string
status
string
traceId
string
show more
Create Fixed Deposit Url
POST /fixed-deposit/url

Merchant can create both amount and customer specific unique fixed deposit url.

Request headers

Authorization
string required

Request body

Object
order_amount
number required

Order EUR money amount

Example:
200
currency
string

FIAT currency type

Enumeration:
EUR
USD
GBP
TRY
MXN
THB
PLN
BRL
NOK
INR
CAD
AUD
ZAR
ARS
VND
return_url
string required

Merchant’s return url

Example:
https://www.merchant.com/payment/thankyou.html
failure_url
string required

Merchant’s failure url

Example:
https://www.merchant.com/payment/error.html
merchant_name
string nullable

Merchant’s name on invoice page

description
string nullable
ip_address
string required

Customer’s ip address

Example:
192.101.118.1
customer
Object
reference_id
string required
first_name
string nullable

Customer’s name

Example:
John
last_name
string nullable

Customer’s last name

Example:
Smith
email
string required

Customer’s email address

Example:
johnsmith@gmail.com
timeout_duration
integer

Payment expiration time in minutes after coin type selection which is counting in the customer payment page. Default: 30

Example:
3
expire_duration
integer

Order expiration time in minutes after coin type selection. After this duration order will be expired if not any deposit has been received. Default: 120

show_overpayment_amount_detail
boolean

if this parameter is FALSE, and the customer sends overpayment, customer will see SUCCESSFULL payment when his deposit arrived. If this paremeter is TRUE, and the customer sends overpayment, customer will see a PARTIAL PAYMENT warning. Default: TRUE

settlement_currency
string

The crypto currency type that, the deposit arrived to this addreess will be automatically converted to

Default:
EUR
show more

Responses

200 OK
Body
Object
data
Object
payment_url
string

Merchant’s amount and customer specific unique fixed deposit url

Example:
https://www.bitpace.com/fixed-deposit/aY9890mNkd34
order_id
integer
timeout_at
string
code
string
message
string
status
string
traceId
string
Refund Fixed Deposit
POST /fixed-deposit/refund

Merchant can refund fixed deposit if available.

Request headers

Authorization
string required

Request body

Object
order_id
number required

Order id

Example:
200
address
string

Blockchain address which is fixed deposit will be refunded

destination_tag
string nullable

Only for XRP, XLM and EOS refunds

refund_cost_party
string

Who will pay refund costs including the network fee

Examples:
MERCHANTCUSTOMER

Responses

200 OK
Body
Object
data
boolean

Returns TRUE if refund request is accepted

code
string
message
string
status
string
traceId
string
Accept Fixed Deposit
POST /fixed-deposit/accept

Merchant can accept fixed deposit if available.

Request headers

Authorization
string required

Request body

Object
order_id
number required

Order id

Example:
200

Responses

200 OK
Body
Object
data
Object
order_id
number required

Unique id of an order

type
string required

Order type

status
string required

Current status of order

order_amount
number required

Currency amount of an order

currency
string required

Currency code

cryptocurrency_amount
number required

Cryptocurrency amount of an order

cryptocurrency
string required

Cryptocurrency code

address
string required

Blockchain address

blockchain_tx_id
string required

Blockchain transaction id

code
string
message
string
status
string
traceId
string
show more
Trade
Create Coin Store Deposit Address
POST /customer/deposit/address
Get Coin Store Deposit Address
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}/depositType/COIN_STORE
Withdraw Coin
POST /orders/coin-withdraw
Create Coin Store Deposit Address
POST /customer/deposit/address

Merchant can create a customer spesific coin wallet address to receive coins.

Request headers

Authorization
string required

Request body

Object
deposit_type
string

COIN_STORE

cryptocurrency
string required
Example:
btc
customer
Object
reference_id
string required

Merchant’s customer reference id

Example:
customer1234
first_name
string nullable

Customer’s name

Example:
John
last_name
string nullable

Customer’s surename

Example:
Smith
email
string required

Customer’s email address

Example:
johnsmith@domain.com

Responses

200 200

OK

Body
*/*
Object
data
Object
address
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Get Coin Store Deposit Address
GET /customer/deposit/address/referenceId/{referenceId}/cryptocurrency/{cryptocurrencyCode}/depositType/COIN_STORE

Fetches a previously created deposit address for a customer.

Path variables

referenceId
string required

Merchant’s customer reference id

Example:
customer1234
cryptocurrencyCode
string required

Coin type

Example:
BTC

Request headers

Authorization
string required

Responses

200 200

OK

Body
Object
data
Object
address
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "4dd44277dc06d5b8"
}
Withdraw Coin
POST /orders/coin-withdraw

Merchant can create an order.

Request headers

Authorization
string required

Request body

Object
customer
Object
reference_id
string
first_name
string nullable

Customer’s first name

Example:
John
last_name
string nullable

Customer’s last name

Example:
Smith
email
string

Customer’s email address

Example:
johnsmith@gmail.com
withdraw
Object

Only for withdraws

address
string

Coin wallet address for withdrawals

destination_tag
string

For XRP, EOS and XLM orders

cryptocurrency
string required
Example:
XRP
cryptocurrency_amount
number required
description
string
sequence_id
string
show more

Responses

200 OK
Body
Object
data
Object
order_id
string
code
string
message
string
status
string
traceId
string
Response Example
{
    "data": {
        "order_id": 11
    },
    "code": "00",
    "message": "Response Approved",
    "status": "APPROVED",
    "traceId": "cf42bf4929c9d924"
}
Callbacks

After the transaction is processed, callback in JSON format is sent to callback URL provided by merchant. Callbacks are sent for only deposit and withdraw transactions.

Callbacks are always sent:

  • when received transaction was completed
  • when its status was changed

Callback signature

Signature is used in callbacks and protects the message from changes. Each callback’s request is signed by the signature, signature of callback is sent in callback header.

Signature is calculated by Bitpace from callback secret(generated for merchant) value and JSON body of callback request with SHA-256. Callback secret is also generated by Bitpace and received by merchant with merchant code.

For example, you have following parameters:

Callback secret: 11qq22ww

Received callback’s JSON body

Then merchant will need to calculate SHA-256 signature of the following string:

{“order_id”:123,“status”:“COMPLETED”,“type”:“DEPOSIT”,… }11qq22ww

The result string must be equal to string in the header Signature of callback.

Callback Request
POST /callback/url
Callback Request
POST /callback/url

Callback requests are sent with the following parameters.

Request headers

Content-Type
string required
Default:
application/json
Signature
string required

Callback signature

Example:
923630f7e917dd7521fa6bd44e1b87f47e16965bd7e8aed87b144fdbc4fbe1e9
HmacSignature
string required

Callback signature with Hmac

Example:
yLuFvmVYGRc/2ApPgyBLfSTLEHycNjedPophrU6i1jw=

Request body

Object
order_id
integer required

Unique id of order

Example:
123456
status
string required

Current status of order

Example:
COMPLETED
type
string required

Type of order

Enumeration:
DEPOSIT
WITHDRAW
PAYMENT
customer_reference_id
string required

Reference id of merchant’s customer

blockchain_tx_id
string required
order_amount
string

Fiat money amount of order (Only available for dynamic deposits and fixed deposits)

fee_amount
string

Merchant’s commission fee amount in currency

currency
string

Fiat money code (Only available for dynamic deposits and fixed deposits)

Example:
EUR
cryptocurrency_amount
string

Cryptocurrency amount of order (Only available for dynamic deposits and fixed deposits)

cryptocurrency
string

Cryptocurrency code (Only available for dynamic deposits and fixed deposits)

Enumeration:
BTC

Bitcoin

ETH

Ethereum

LTC

Litecoin

XRP

Ripple

BCH

Bitcoin Cash

show more
Developer FAQ

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, TRY, AUD, CAD, INR, ZAR, VND, BRL, ARS, MXN, PLN, THB, BGN, COP, CRC, MKD, HKD, PGK, PKR, PHP, RON, MVR, SGD, HUF, CHF