Getting Started

COINQVEST enables you to accept payments in Bitcoin, Ethereum, Litecoin, Stellar Lumens, or Ripple XRP and settle in USD, EUR, or other supported fiat currencies (or crypto) instead.

The COINQVEST API is a streamlined HTTP REST interface to integrate cryptocurrency payments into your online business, e-commerce store or application. This documentation provides information on how to interact with the COINQVEST API.

Using the COINQVEST API

Accepting cryptocurrency payments using the COINQVEST API is fast, secure, and easy. After you've signed up and obtained your API key, all you need to do is create a checkout to get paid.

There are two types of checkouts, hosted (by COINQVEST) and self-hosted (by you). Hosted checkouts live on COINQVEST servers and provide a fast, convenient, responsive, and easy user interface for your customers to complete payment. We built a great user experience so you don't have to. Self-hosted checkouts live on your servers and give you full control over branding and the entire payment process but require more development work.

Creating Hosted Checkouts

Hosted checkouts are the simplest form of getting paid using the COINQVEST platform. The POST /checkout/hosted API endpoint creates and returns a payment URL for a dynamic checkout page on COINQVEST servers. Once the URL is retrieved by your application, your customer is redirected to it to complete payment.

Here is an example of how to dynamically create a hosted checkout and get paid:

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: TIMESTAMP" \
     -d "@charge.json"

Where authentication is supplied via HTTP headers and charge.json is a JSON object:

Example Charge (minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Above example creates a charge for a t-shirt at 10.00 USD. You can configure more details, such as shipping costs, discounts, taxes, the related customer, or your preferred settlement currency as documented here.

Example Response (application/json)

{
   "id":"b5bcf27e5482",
   "url":"https://www.coinqvest.com/en/checkout?id=b5bcf27e5482"
}

The API returns a unique identifier along with a hosted checkout URL, which you display back to your customer in order for him or her to complete payment. Once the funds are captured we notify you via WEBHOOK payment.

Receiving Payments

Unlike credit card payments where merchants need to obtain credit card credentials in order to place a charge, cryptocurrency payments implement a push model where the customer must explicitly invoke the payment to send money to the merchant.

After creating a checkout, COINQVEST continuously observes your customer's selected blockchain to monitor inbound payments. We set a 60 minute monitoring window for the payment to complete. If your customer does not complete the payment within that time frame, we mark the payment as expired (but still accept payment if it arrives delayed).

Once the payment has been received, your balance is credited, your dashboard automatically updated, and a webhook callback sent to your server, to automatically process the order in your system (WEBHOOK payment).

Example Webhook (application/json)

{
  "id": "ce30afda2080",
  "type": "PAYMENT",
  "state": "RESOLVED",
  "timestamp": "2020-08-27T20:10:16+08:00",
  "creditAssetCode": "USD",
  "creditAssetIssuer": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
  "creditAmount": "10.0000000",
  "sourceAssetCode": "ETH",
  "sourceAssetIssuer": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
  "sourceAmount": "0.0265049",
  "sourceBlockchain": "ETH",
  "sourceAccount": "0x006538E99862411e921A376a496Bc9B3829aDEAC",
  "sourceTxId": "0x49c87eee0525ce1ce9586a76e00149ec57c91dce4464c8692f14ad7fed147dde",
  "customerId": "4cef8ebe46ae",
  "checkoutId": "f8052e98a9f3"
}

The webhook contains a JSON object in the HTTP request body and informs you about incoming payments and their attributes as specified in WEBHOOK payment. In above example the customer paid in ETH and the merchant got credited in USD.

Creating Self-Hosted Checkouts

COINQVEST APIs enable you to fully control and host the entire checkout process in your own web application and branding. Choose self-hosted checkouts if you want your users to stay within your application without being redirected to COINQVEST to complete payment. Inspect the POST /checkout API endpoint to get started with whitelabel payments.

Software Development Kits

The COINQVEST API works with any REST client in any programming language and we've published SDKs for PHP, Ruby, and NodeJS on our GitHub to help you get started quickly.

PHP
Official COINQVEST Merchant SDK for PHP

Ruby
Official COINQVEST Merchant SDK for Ruby

NodeJS
Official COINQVEST Merchant SDK for NodeJS

Developer Guides

We're continuously updating and adding to our library of COINQVEST guides and tutorials to help you understand and work with the platform as quickly and conveniently as possible. Below is a list of guides currently available on our blog.

COINQVEST Developer Guide
Cryptocurrency Payments with COINQVEST Merchant APIs

API Tools and Event Logging
An Introduction to COINQVEST's Merchant API, Developer Tools, and Event Logs

E-Commerce Integrations

We're continuously updating our e-commerce libraries, plugins and extensions to help you integrate with COINQVEST as quickly and conveniently as possible. Below is a list of e-commerce integrations currently available in production.

Wordpress
Official COINQVEST Plugin for Wordpress

WooCommerce
Official COINQVEST Plugin for WooCommerce

Shopify
Official COINQVEST Integration for Shopify

Magento
Official COINQVEST Extension for Magento 2

Not a Developer?

It's easy to receive cryptocurrency payments even if you are not a developer. Read our guide about hosted checkouts and direct invoicing.

COINQVEST for Non-Developers
Cryptocurrency Payment Processing for Non-Developers

Authentication

Most requests to the COINQVEST API must be authenticated. The API endpoints are marked as public () or protected (). When accessing a protected endpoint your request must be authenticated with your API key using either the Basic-Auth or Digest-Auth method. The latter is more secure and recommended. Try the GET /auth-test endpoint to conveniently test your authentication implementation.

API Key and Secret

Visit the API Settings to obtain your API key and API secret. You should also configure your preferred authentication method and enable "IP-address whitelisting" for increased security. If you ever feel that your API secret has been compromised, the settings allow you to roll a new one.

Digest-Auth

Digest-Auth is the recommended authentication method for accessing protected COINQVEST API endpoints. Every request must include the following headers: X-Digest-Key, X-Digest-Signature, and X-Digest-Timestamp, which are explained below.

Request

curl 'https://www.coinqvest.com/api/v1/auth-test' \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Request Headers

Key	Type	Description
`X-Digest-Key`	string	Your COINQVEST API key.	mandatory
`X-Digest-Signature`	string	Unique Digest-Auth Signature (see below).	mandatory
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`).	mandatory

The X-Digest-Signature is generated by creating a SHA256 HMAC hash using your API Secret as the shared secret in the message digest. The encrypted payload is composed as follows:
ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY, where . represents string concatenation.

X-Digest-Signature Components

Component	Type	Description
`ENDPOINT_PATH`	string	The path of the endpoint that is being invoked, e.g. `/auth-test` in lower case.
`UNIX_TIMESTAMP`	integer	Current Unix timestamp. Must be less than 30 seconds old (also see `GET /time`).
`REQUEST_METHOD`	string	The request method, e.g. `POST` or `GET` in upper case.
`REQUEST_BODY`	string	The request body string. Only needed in `POST`, `PUT`, or `DELETE` requests. Set `null` for `GET` requests.

Code Example (PHP)

$path = '/auth-test'
$timestamp = time();
$method = 'GET';
$body = $method == 'GET' ? null : json_encode($params);
$secret = 'YOUR_API_SECRET';

$signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

Code Example (Ruby)

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Code Example (NodeJS)

require('crypto');

let path = '/auth-test'
let timestamp = Date.now() / 1000 | 0;
let method = 'GET'
let body = method === 'GET' ? '' : JSON.stringify(params)
let secret = 'YOUR_API_SECRET'

let signature = crypto.createHmac('sha256', secret)
                .update(path + timestamp + method + body)
                .digest('hex');

View these examples if you're unsure how to create an HMAC SHA256 signature in your programming language.

Basic-Auth

You can choose to use a basic authentication header, which is easier to implement (as it's a static hash over your API key and secret) but less secure than Digest-Auth. We recommend use Basic-Auth during development or in test environments only.

Request

curl 'https://www.coinqvest.com/api/v1/auth-test' \
     -H "X-Basic: BASIC_AUTH_HASH"

Request Headers

Key	Type	Description
`X-Basic`	string	SHA256 hash over `YOUR_API_KEY:YOUR_API_SECRET`	mandatory

Code Example

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

IP Address Whitelisting

Use the API Settings to configure whether your API account can be accessed from any IP address or whitelisted IP addresses only. IP address whitelisting is recommended for production environments as it dramatically increases security. Withdrawal endpoints can only be accessed from whitelisted IP addresses.

We're working on it! API doc definition file not found: merchant-api-definitions/concepts.docs.php

Software Development Kits (SDKs)

Our Software Development Kits for PHP, Ruby, and NodeJS are here to help you quickly integrate with the COINQVEST Merchant APIs without hassle.

Below is a list of SDKs currently available on our GitHub.

PHP
Official COINQVEST Merchant SDK for PHP

1  include('CQMerchantClient.class.php');
2
3  $client = new CQMerchantClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/coinqvest.log'
7  );

View on GitHub README.md

Ruby
Official COINQVEST Merchant SDK for Ruby

1  require 'coinqvest_merchant_sdk/client'
2
3  client = CoinqvestMerchantSDK::Client.new(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/coinqvest-ruby.log'
7  )

View on GitHub README.md

NodeJS
Official COINQVEST Merchant SDK for NodeJS

1  require('coinqvest-merchant-sdk');
2
3  const client = new CoinqvestClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET'
6  );

View on GitHub README.md

POST/checkoutprotected

Invoking a checkout is the first step to get paid. This endpoint creates a self-hosted checkout on your server, which you control entirely on your own platform UI or API. If you would like to create a hosted checkout with an automated payment page on COINQVEST servers, please use POST /checkout/hosted instead.

This endpoint takes a charge object, which includes line items, optional shipping costs or discounts and taxes. It can be optionally linked to a customer and lets you specify your desired settlement currency, which can be different from what the charge is denominated in and what your customer used for payment. Upon successful completion, the endpoint returns a list of payment methods and amounts, which you display back to your customer.

Your customer then selects his preferred payment method (e.g. Bitcoin) and you submit a new request with the selected blockchain and corresponding checkout id to POST /checkout/commit. Once a checkout is committed, our system starts monitoring the blockchain for inbound payment transactions and notifies you about payment events via WEBHOOK payment.

Checkouts are unique and not re-usable. You should create a new checkout for every charge.

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in "USD" and has exactly one line item at a cost of USD 10.00. The required payment amount in BTC, ETH, XLM, etc. given in the API response is calculated against the total payment amount and currency given here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "webhook":"https://www.merchant.com/path/to/webhook",
   "blockchainRelays":{
      "ETH":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "BTC":"BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH"
   },
   "links":{
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout"
   }
}

Request Params (POST)

PRO Tip #1 Auto-Conversion

Make sure to set the settlementCurrency parameter to automatically convert incoming funds into your preferred currency, e.g. USD.

PRO Tip #2 Customer Object Relation

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

PRO Tip #3 Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Us the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The customer facing currency in which this charge is denominated in, e.g. `USD` or `EUR`. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to calculate payment amounts against AnchorUSD's market, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used. Unless a different asset code is specified in `settlementCurrency` (see below) this is also the currency you're paid in.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	integer	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementCurrency`	string	This specifies the currency you'll be credited in when the payment completes. For example, if you specify `USD` as settlement currency then you will be credited in `USD`. Otherwise you will be credited in the `currency` specified in the charge (see above). It is possible to select a settlement currency, which is different from the customer facing currency. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in AnchorUSD tokens, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in `WEBHOOK payment`.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, Litecoin or XRP Ledger networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK payment`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional

Success Response application/json

{
   "id":"6d55626309d6",
   "paymentMethods":[
      {
         "assetCode":"XLM",
         "blockchain":"Stellar Network",
         "paymentAmount":"165.7007861"
      },
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "paymentAmount":"0.0011102"
      },
      {
         "assetCode":"ETH",
         "blockchain":"Ethereum",
         "paymentAmount":"0.0440141"
      },
      {
         "assetCode":"LTC",
         "blockchain":"Litecoin",
         "paymentAmount":"0.1537514"
      },
      {
         "assetCode":"XRP",
         "blockchain":"XRP Ledger",
         "paymentAmount":"42.282669"
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.id`	string(12)	The identifier of the checkout. You should store this persistently to match payments and associated information against this checkout.	false
`.paymentMethods[]`	array	Contains a list of available payment methods for this checkout and associated payment amounts for your customer. Currently COINQVEST supports payments in `BTC`, `ETH`, `LTC`, `XRP`, `XLM` and any other asset on the Stellar Network in the form of path payments (to XLM). This list should be displayed back to your customer, who then selects the desired blockchain as payment method. Upon selection, your application submits a `POST /checkout/commit` and obtains the deposit information and required for your customer to make the payment. This list includes all blockchains listed in `GET /blockchains` that are above the minimum payment threshold. Some blockchains have high fees and might not appear in the list for payments with low payment amounts. Stellar Lumens `XLM` and Ripple `XRP` are always available.	false
`.assetCode`	string(3)	The asset code of the payment currency, e.g. `BTC`. Inspect `GET /blockchains` for a list of supported blockchains. Submit this `assetCode` along with the `checkoutId` to the `POST /checkout-commit` endpoint to obtain deposit information for your customer.	false
`.blockchain`	string(12)	The blockchain name in plain text.	false
`.paymentAmount`	string	The required payment amount to display back to your customer.	false

Next Step

Your application displays the payment methods received in the response back to your customer. The customer then selects his preferred payment method and your server submits this selection in a new API request to the POST /checkout/commit endpoint. In return you receive the deposit address for the selected blockchain for display to your customer. Continue here.

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/commitprotected

This endpoint is a continuation of the checkout process started in POST /checkout. If you aren't familiar with how to initialize a checkout process yet, please start here.

This endpoint takes a checkoutId and an assetCode as given by POST /checkout. Upon successful completion, it returns deposit information, which is displayed back to your customer in order for him or her to make the payment.

When the payment completes your server is automatically notified via WEBHOOK payment. Alternatively you can poll GET /checkout for payment updates after you displayed the deposit information to your customer.

In the previous step POST /checkout has given you a list of payment methods, like this:

Example Response (as given by `POST /checkout`)

{
   "id":"6d55626309d6",
   "paymentMethods":[
      {
         "assetCode":"XLM",
         "blockchain":"Stellar Network",
         "paymentAmount":"165.7007861"
      },
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "paymentAmount":"0.0011102"
      },
      {
         "assetCode":"ETH",
         "blockchain":"Ethereum",
         "paymentAmount":"0.0440141"
      }
   ]
}

As a prerequisite to invoke this endpoint you should have received a response as above from POST /checkout. It contains a list of payment methods, which you display back to your customer to choose from. Upon selection, you invoke POST /checkout/commit (this endpoint) with the selected assetCode and checkoutId to receive deposit information for your customer to make the payment.

Request

curl -X POST 'https://www.coinqvest.com/api/v1/checkout/commit'
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
  "checkoutId":"6d55626309d6",
  "assetCode":"ETH"
}

Request Params

Key	Type	Description	Default	Mandatory
`checkoutId`	string(12)	Unique identifier as given by `POST /checkout`.	null	mandatory
`assetCode`	string(3)	The asset code related to the payment method selected by your customer, e.g. `ETH` if your customer wishes to pay using the Ethereum blockchain.	null	mandatory

Example Success Response for ETH application/json

{
   "depositInstructions":{
      "blockchain":"Ethereum",
      "assetCode":"ETH",
      "amount":"0.0056804",
      "address":"0xc85eBb197c8212C09B7d0905C3ce9e3fCe324F0B",
      "memo":null,
      "memoType":null,
      "destinationTag":null
   },
   "expirationTime":"2020-02-26T18:49:33+00:00",
   "checkoutId":"29d030183ce9"
}

When you customer selects Bitcoin (BTC), Ethereum (ETH) or Litecoin (LTC) as their payment method of choice, the only relevant fields are address and amount. The response fields for memo, memoType and destinationTag are null and irrelevant in these cases. You don't need to display them to the customer.

Example Success Response for XLM application/json

{
   "depositInstructions":{
      "blockchain":"Stellar Network",
      "assetCode":"XLM",
      "amount":"17.8639906",
      "address":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"snowy-hills",
      "memoType":"text",
      "destinationTag":null
   },
   "expirationTime":"2020-02-26T18:48:58+00:00",
   "checkoutId":"d95114c52bca"
}

When your customers select XLM as their payment currency then you need to provide them with the address as well as memo and memoType. This is important in order for COINQVEST to map the payment to your merchant account. The destinationTag field is null and irrelevant for XLM payments and can be ignored.

Example Success Response for XRP application/json

{
   "depositInstructions":{
      "blockchain":"XRP Ledger",
      "assetCode":"XRP",
      "amount":"4.535824",
      "address":"rJY2W6QRaqbcmnYdzG3qdK1kYz5Ww6tXVk",
      "memo":null,
      "memoType":null,
      "destinationTag":"15918"
   },
   "expirationTime":"2020-02-26T18:48:30+00:00",
   "checkoutId":"1ff5df8ed792"
}

When your customer selects XRP as the payment currency then you need to provide him or her with the address as well as the destinationTag. This is important in order for COINQVEST to map the payment to your merchant account. The memo and memoType fields are null and irrelevant for XRP payments and can be ignored.

Success Response Attributes

Name	Type	Description	Nullable
`.depositInstructions{}`	object	The deposit information to display to your customer.	false
`.blockchain`	string	The selected blockchain name as plain text.	false
`.assetCode`	string(3)	The selected payment asset code, e.g. `BTC`, `ETH`, `XLM`, `LTC` or `XRP`.	false
`.amount`	string	The required payment amount for the selected blockchain. Display this back to your customer. Please note that this field is of type `string` even though it is numeric. You might need to do some type casting here.	false
`.memo`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.memoType`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.destinationTag`	string	This field is only relevant for payments in `XRP`. Otherwise it is `null`. If the `assetCode` is `XRP`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.expirationTime`	timestamp	W3C formatted timestamp with the expiration time for this checkout. COINQVEST allows for a 60 minute window to complete the payment, afterwards we mark the charge as expired. Don't worry though, you will still be credited even if the payment arrives late.	false
`.checkoutId`	array	The checkout id as originally given by `POST /checkout`.	false

Next Step

You display the deposit information back to your customer. Meanwhile COINQVEST starts monitoring the blockchain address given in the API response above and notifies you automatically via WEBHOOK payment when a payment completes. Alternatively you can poll GET /checkout for payment updates after you displayed the deposit information to your customer.

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/hostedprotected

Hosted checkouts are the simplest form of getting paid using the COINQVEST platform. This API endpoint creates and returns a URL for a hosted checkout page on COINQVEST servers. If you would like to maintain control of the UI and entire checkout process yourself, please use the POST /checkout endpoint instead.

Using this endpoint, your server submits a set of parameters, such as the payment details including optional tax items, customer information, and settlement currency. Your server then receives a checkout URL in return, which is displayed back to your customer.

Upon visiting the URL, your customer is presented with a checkout page hosted on COINQVEST servers. This page displays all the information the customer needs to complete payment. When completed, your application is automatically notified via WEBHOOK payment. Alternatively you can poll GET /checkout to query information about the payment state.

COINQVEST hosted checkouts implement responsive design and are suitable for mobile phone screens as well as desktop environments with large monitors.

Hosted checkout URLs are unique and not re-usable. You should issue a new URL for every charge.

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in "USD" and has exactly one line item at a cost of USD 10.00. The required payment amount in BTC, ETH, XLM, etc. given in the API response is calculated against the total payment amount and currency given here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "webhook":"https://www.merchant.com/path/to/webhook",
   "blockchainRelays":{
      "ETH":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "BTC":"BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH"
   },
   "links":{
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout"
   }
}

Request Params (POST)

PRO Tip #1 Auto-Conversion

Make sure to set the settlementCurrency parameter to automatically convert incoming funds into your preferred currency, e.g. USD.

PRO Tip #2 Customer Object Relation

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

PRO Tip #3 Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Us the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The customer facing currency in which this charge is denominated in, e.g. `USD` or `EUR`. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to calculate payment amounts against AnchorUSD's market, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used. Unless a different asset code is specified in `settlementCurrency` (see below) this is also the currency you're paid in.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	integer	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementCurrency`	string	This specifies the currency you'll be credited in when the payment completes. For example, if you specify `USD` as settlement currency then you will be credited in `USD`. Otherwise you will be credited in the `currency` specified in the charge (see above). It is possible to select a settlement currency, which is different from the customer facing currency. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in AnchorUSD tokens, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in `WEBHOOK payment`.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, Litecoin or XRP Ledger networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK payment`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional

Success Response application/json

{
    "id":"b5bcf27e5482",
    "url":"https://www.coinqvest.com/en/checkout?id=b5bcf27e5482"
}

Success Response Attributes

Name	Type	Description	Nullable
`.id`	string(12)	The identifier of the hosted checkout. You should store this persistently to match payments against this checkout.	false
`.url`	string(12)	The hosted checkout URL, which you display back to your customer to initiate payment. Upon visiting this URL your client is presented with a checkout interface where he completes the payment. When completed, your application is automatically notified via `WEBHOOK payment`. Alternatively you can poll `GET /checkout` using the `id` given in the above response to query information about the payment state.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutprotected

Retrieves information about a given checkout.

The response of this endpoint contains information about blockchain payments associated with this checkout, its overall completion state, as well as additional meta information.

This endpoint is suitable for polling payment events associated with the given checkout. An adequate alternative is listening for payment events using WEBHOOK payment on your server.

Request

curl 'https://www.coinqvest.com/api/v1/checkout?id=xxx'

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /checkout` or `POST /checkout/hosted`.	null	mandatory

Success Response application/json

{
   "checkout":{
      "id":"efd667b61725",
      "timestamp":"2020-09-16T21:34:28+00:00",
      "state":"COMPLETED",
      "type":"HOSTED",
      "settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "settlementAmountRequired":"2.5000000",
      "settlementAmountReceived":"2.5000000",
      "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "sourceAmountExpected":"0.0069518",
      "sourceAmountReceived":"0.0069518",
      "sourceBlockchain":"Ethereum",
      "sourceBlockchainAssetCode":"ETH",
      "blockchainTransactions":[
         {
            "type":"ORIGIN",
            "typeDescription":"Blockchain payment transaction initiated by customer.",
            "blockchain":"Ethereum",
            "blockchainAssetCode":"ETH",
            "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
            "amount":"0.0069518",
            "amountAssetCode":"ETH"
         },
         {
            "type":"TRANSFER",
            "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
            "amount":"0.0069518",
            "amountAssetCode":"ETH"
         },
         {
            "type":"SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
            "amount":"2.5000000",
            "amountAssetCode":"USD"
         }
      ],
      "payload":{
         "charge":{
            "lineItems":[
               {
                  "description":"SAMPLE",
                  "quantity":"1",
                  "netAmount":"2.5",
                  "productId":null
               }
            ],
            "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "customerId":"a2df67b61725"
         },
         "settlementCurrency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
      }
   }
}

Success Response Attributes

Name Type Description Nullable

.checkout{} array The checkout object. false

.id string(12) Unique identifier of the checkout. false

.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the checkout was created. false

.state

string

Indicates the current payment state associated with this checkout. This is an important field to parse.

A state of COMPLETED, DELAYED_COMPLETED or RESOLVED indicates this checkout has completed and the funds were credited to your account.

A state of EXPIRED indicates this checkout expired without a payment being made.

Possible states

`NEW_CHARGE`	Charge has been created and is awaiting customer payment.
`IN_PROGRESS`	Payment has been detected on the blockchain and is awaiting confirmation.
`COMPLETED`	Payment has been confirmed and deposited to your account.
`EXPIRED`	Charge has expired without a payment.
`UNRESOLVED_GENERIC`	Payment has diverged from what was expected or a generic error occurred.
`UNRESOLVED_UNDERPAID`	Payment amount was less than expected.
`UNRESOLVED_OVERPAID`	Payment amount was more than expected.
`DELAYED_COMPLETED`	Payment has successfully completed after the charge expired.
`DELAYED_UNDERPAID`	Payment arrived after the charge expired and was less than expected.
`DELAYED_OVERPAID`	Payment arrived after the charge expired and was more than expected.
`RESOLVED`	Payment has been marked as resolved by the merchant.

false

.type string Indicates whether this is a hosted (HOSTED) or self-hosted (SELF-HOSTED) checkout. false

.settlementAssetId string The settlement asset used for this checkout. Indicates the asset (GET /assets) you are credited in when the checkout is complete. false

.settlementAmountRequired numeric Indicates the total amount credited to your account when the checkout is complete. false

.settlementAmountReceived numeric The total amount credited to your account so far. This is usually 0 for incomplete checkouts or equal to settlementAmountRequired for completed checkouts. false

.sourceAssetId string The payment asset (GET /asset-issuers) used for this checkout. Indicates the blockchain and payment method selected by the customer. This field is null if the customer did not select any payment method for this checkout yet. true

.sourceAmountExpected numeric Indicates the total amount payable by the customer to complete this checkout. This field is null if the customer did not select any payment method for this checkout yet. true

.sourceAmountReceived numeric The total amount paid by the customer so far. This field is null if the customer did not select any payment method for this checkout yet. true

.sourceBlockchain string The payment blockchain (GET /blockchains) selected by the customer in English plain text. This field is null if the customer did not select any payment method for this checkout yet. true

.sourceBlockchainAssetCode string The native asset code of the blockchain (GET /blockchains) selected by the customer. This field is null if the customer did not select any payment method for this checkout yet. true

.blockchainTransactions[] array A list of blockchain transactions associated with this checkout. false

.type string The type of blockchain transaction. Can be either ORIGIN (blockchain payment transaction initiated by customer), TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), or SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). false

.typeDescription string An explanation of the above blockchain transaction type in English plain text. false

.blockchain string The blockchain (GET /blockchains) on which this transaction was executed. true

.blockchainAssetCode string The native asset code of the blockchain (GET /blockchains) on which this transaction was executed. true

.tx string The corresponding transaction id. true

.amount numeric The amount transferred during in this transaction. true

.amountAssetCode string The asset code of the amount transferred in this transaction. true

.payload{} object The checkout payload as originally submitted by you to POST /checkout or POST /checkout/hosted. false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutsprotected

Retrieves a list of checkout objects (in descending order from newest to oldest).

Request

curl 'https://www.coinqvest.com/api/v1/checkouts?limit=250&offset=0'

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of checkout objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

{
   "count":67,
   "limit":1,
   "offset":0,
   "checkouts":[
      {
         "id":"efd667b61725",
         "timestamp":"2020-09-16T21:34:28+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "settlementAmountRequired":"2.5000000",
         "settlementAmountReceived":"2.5000000",
         "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
         "sourceAmountExpected":"0.0069518",
         "sourceAmountReceived":"0.0069518",
         "sourceBlockchain":"Ethereum",
         "sourceBlockchainAssetCode":"ETH",
         "blockchainTransactions":[
            {
               "type":"ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "blockchain":"Ethereum",
               "blockchainAssetCode":"ETH",
               "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
               "amount":"0.0069518",
               "amountAssetCode":"ETH"
            },
            {
               "type":"TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
               "amount":"0.0069518",
               "amountAssetCode":"ETH"
            },
            {
               "type":"SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
               "amount":"2.5000000",
               "amountAssetCode":"USD"
            }
         ],
         "payload":{
            "charge":{
               "lineItems":[
                  {
                     "description":"SAMPLE",
                     "quantity":"1",
                     "netAmount":"2.5",
                     "productId":null
                  }
               ],
               "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "customerId":"a2df67b61725"
            },
            "settlementCurrency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      }
   ]
}

Success Response Attributes

Name Type Description Nullable

.count integer The total number of checkout URLs in existence for this account. false

.limit integer The limit argument used in this request. false

.offset integer The pagination offset used in this request. false

.checkouts[] array A list of checkout objects. false

.id string(12) Unique identifier of the checkout. false

.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the checkout was created. false

.state

string

Indicates the current payment state associated with this checkout. This is an important field to parse.

A state of COMPLETED, DELAYED_COMPLETED or RESOLVED indicates this checkout has completed and the funds were credited to your account.

A state of EXPIRED indicates this checkout expired without a payment being made.

Possible states

`NEW_CHARGE`	Charge has been created and is awaiting customer payment.
`IN_PROGRESS`	Payment has been detected on the blockchain and is awaiting confirmation.
`COMPLETED`	Payment has been confirmed and deposited to your account.
`EXPIRED`	Charge has expired without a payment.
`UNRESOLVED_GENERIC`	Payment has diverged from what was expected or a generic error occurred.
`UNRESOLVED_UNDERPAID`	Payment amount was less than expected.
`UNRESOLVED_OVERPAID`	Payment amount was more than expected.
`DELAYED_COMPLETED`	Payment has successfully completed after the charge expired.
`DELAYED_UNDERPAID`	Payment arrived after the charge expired and was less than expected.
`DELAYED_OVERPAID`	Payment arrived after the charge expired and was more than expected.
`RESOLVED`	Payment has been marked as resolved by the merchant.