Lydiax Merchant REST API

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

Flows:

REST API URL: https://sandbox-merchant-api.lydiax.com/api/v1/

Authorization

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

Acquire an access token

Use the access token to make authenticated requests
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://sandbox-merchant-api.lydiax.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://sandbox-merchant-api.lydiax.com/api/v1/buy/prices/BTC'
       -H 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElkIjoxLCJ0aW1lc3RhbXAiOjE1NDU4MjIwODd9.e_Qj_IgyZg09m5nJToQVZRDwVGJLTKLTgs0I3H9_uKM'

Authorization Token

POST /auth/token

Authentication

Open

This endpoint is used to acquire the access token.

Request body

Object

merchant_code

string

password

string

Responses

200 OK

Body

Object

data

Object

token

string

code

string

message

string

status

string

Response Example

{
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudElkIjoxLCJ0aW1lc3RhbXAiOjE1NDU4MjIwODd9.e_Qj_IgyZg09m5nJToQVZRDwVGJLTKLTgs0I3H9_uKM"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

Get Buy Price

GET /buy/prices/{cryptocurrencyCode}

Get Sell Price

GET /sell/prices/{cryptocurrency}

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

Response Example

{
    "data": {
        "buy_price": 3302.4,
        "currency": "EUR",
        "cryptocurrency": "BTC"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

GET /sell/prices/{cryptocurrency}

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

Path variables

cryptocurrency

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

Response Example

{
    "data": {
        "sell_price": 3302.4,
        "currency": "EUR",
        "cryptocurrency": "BTC"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

Get Customer Buy/Sell Balance

GET /customer/balance/referenceId/{referenceId}/cryptocurrency/{code}

Get Balance

GET /balance

Get Order Price

POST /orders/prices

Create Order

POST /orders

Get Order Details

GET /orders/{orderId}

GET /customer/balance/referenceId/{referenceId}/cryptocurrency/{code}

Merchant can get customer’s balance for buy and sell orders.

Path variables

referenceId

string required

Customer reference id

code

string required

Cryptocurrency code

Request headers

Authorization

string required

Responses

200 200

OK

Body

*/*

Object

data

Object

balance

number

cryptocurrency

string

code

string

message

string

status

string

Response Example

{
    "data": {
        "balance": 0.6,
        "cryptocurrency": "LTC"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

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

Response Example

{
    "data": {
        "buysell": {
            "balance": "1002931.53",
            "currency": "EUR"
        },
        "exchange": {
            "balance": "984554.09",
            "currency": "EUR"
        }
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

POST /orders/prices

Merchant can get an order price.

Request headers

Authorization

string required

Request body

application/json

Object

cryptocurrency_amount

number nullable

cryptocurrency

string

currency_amount

number nullable

order_type

string

Enumeration:

BUY

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

SELL

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

WITHDRAW

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

Responses

200 OK

Body

Object

data

Object

token

string

total_amount

number

currency

string

cryptocurrency_amount

number

cryptocurrency

string

code

string

message

string

status

string

Response Example

{
    "data": {
        "token": "nRRMlCnAwr5SHWeEaqe3a5BQLCAxtHVAEexsJsDcmhYmbCAEts1GM9U9ehek0IpO7YP4w1PLgrW3w6WSzSDBFq6EFWzt9iCqE1MhSmR1Fpo=",
        "total_amount": 703.62,
        "currency": "EUR",
        "cryptocurrency_amount": 0.223,
        "cryptocurrency": "BTC"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

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 orders

Responses

200 OK

Body

Object

data

Object

order_id

string

code

string

message

string

status

string

Response Example

{
    "data": {
        "order_id": 11
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

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

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

Create Customer Deposit Address

POST /customer/deposit/address

Get Customer Deposit Address

GET /customer/deposit/address/{referenceId}/cryptocurrency/{cryptocurrencyCode}

POST /customer/deposit/address

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

Request headers

Authorization

string required

Request body

application/json

customerDepositAddress

Object

cryptocurrency

string required

customer

Object

reference_id

string

Merchant’s customer reference id

Example:

customer1234

first_name

string nullable

Customer’s name

Example:

John

last_name

string nullable

Customer’s surname

Example:

Smith

email

string

Customer’s email address

Example:

johnsmith@gmail.com

Responses

200 200

OK

Body

*/*

Object

data

Object

address

string

code

string

message

string

status

string

Response Example

{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

GET /customer/deposit/address/{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

Response Example

{
    "data": {
        "address": "2Mv2VAaATwnmaqxNLRWQB3vVUyjrMpy48zr"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}

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

Create Payment

POST /payments

Payment Conversion

POST /payments/{id}/conversion

Create Payment Url

POST /payments/url

Refund Payment

POST /payments/refund

Accept Payment

POST /payments/accept

Create Custom Payment

POST /payments/cpg

POST /payments

Merchant can create both amount and customer specific unique payment.

Request headers

Authorization

string required

Request body

Object

order_amount

number required

Order EUR money amount

Example:

200

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

Responses

200 OK

Body

Object

data

Object

order_id

string

Order id

Example:

103

code

string

message

string

status

string

POST /payments/{id}/conversion

Merchant can confirm previously created payment 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

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

POST /payments/url

Merchant can create both amount and customer specific unique payment url.

Request headers

Authorization

string required

Request body

Object

order_amount

number required

Order EUR money amount

Example:

200

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

Responses

200 OK

Body

Object

data

Object

payment_url

string

Merchant’s amount and customer specific unique payment url

Example:

https://www.lydiax.com/payment/aY9890mNkd34

status

string

timeout_at

string

code

string

message

string

status

string

POST /payments/refund

Merchant can refund payments if available.

Request headers

Authorization

string required

Request body

Object

order_id

number required

Order id

Example:

200

address

string

Blockchain address which is payment will be refunded

destination_tag

string nullable

Only for XRP refunds

Responses

200 OK

Body

Object

data

boolean

Returns TRUE if refund request is accepted

code

string

message

string

status

string

POST /payments/accept

Merchant can accept payments 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

POST /payments/cpg

All the instructions same with “Create Payment”.

This payment type is only available for Bitcoin (BTC).

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 Lydiax from callback secret(generated for merchant) value and JSON body of callback request with SHA-256. Callback secret is also generated by Lydiax 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:

{ “id”: 123, … }11qq22ww

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

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

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

number

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

Example:

78.23

currency

string

Fiat money code (Only available for deposits and payments)

Example:

EUR

cryptocurrency_amount

number

Cryptocurrency amount of order (Only available for deposits and payments)

Example:

1.0223

cryptocurrency

string

Cryptocurrency code (Only available for deposits and payments)

Enumeration:

BTC

Bitcoin

ETH

Ethereum

LTC

Litecoin

XRP

Ripple

BCH

Bitcoin Cash