Merchant API Docs

INTRO

Getting Started Authentication Concepts SDKs

CHECKOUTS

POST /checkout POST /checkout/commit POST /checkout/hosted GET /checkout GET /checkouts

PAYMENTS

GET /payment GET /payments

CUSTOMERS

POST /customer GET /customer PUT /customer DELETE /customer GET /customers

WALLETS

GET /wallets GET /wallet

WITHDRAWALS

POST /withdrawal POST /withdrawal/commit GET /withdrawal GET /withdrawals

BLOCKCHAINS

GET /blockchains GET /blockchain

FIAT CURRENCIES

GET /fiat-currencies GET /fiat-currency

ASSETS

GET /assets GET /asset

ASSET ISSUERS

GET /asset-issuers GET /asset-issuer

HELPER ENDPOINTS

GET /ping GET /time GET /auth-test

WEBHOOKS

WEBHOOK payment

Getting Started

Cryptocurrencies have dramatically transformed the way payments can be accepted over the internet and lowered the entry barrier for merchants to start getting paid. COINQVEST makes it simple to add cryptocurrency payments as a stand-alone solution or in addition to your existing checkout flows.

COINQVEST merchants benefit from all the advantages of a hosted software service. Using COINQVEST, it is no longer necessary to continuously monitor various blockchains for payment transactions. It allows you to focus on your core business while leaving the complexities of real-time blockchain settlement to us. COINQVEST creates cryptocurrency payment transactions on your behalf and automatically notifies you once the payment has been settled.

Customers can now pay you directly from their computers or mobile phones using their preferred cryptocurrency. COINQVEST converts incoming payments automatically into your cryptocurrency or fiat token of choice and deposits them to your account in your preferred form.

Using COINQVEST it is possible to accept payments in Bitcoin, Ethereum, Litecoin, Stellar Lumens or Ripple XRP but get paid in USD, EUR or any other supported currency instead.

The COINQVEST API provides a streamlined HTTP REST interface to integrate cryptocurrency payments into your online business or application. This API reference provides information on available endpoints and how to interact with them.

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.

Creating an API Checkout

When you invoke the POST /checkout endpoint, COINQVEST generates and returns a list of payment methods (e.g. Bitcoin, Ethereum, Stellar Lumens etc.) along with the corresponding payment amount. Your customer selects his or her preferred blockchain and you then commit the checkout with POST /checkout/commit. COINQVEST now generates and returns the wallet address, which you display back to your customer for payment settlement. Using this method, you control the payment process entirely in your web application.

Creating a Hosted Checkout

To get started quickly we can alternatively provide you with a hosted checkout page you can send to your customers to complete the payment. Create a hosted checkout and retrieve the URL by invoking POST /checkout/hosted.

An example of how to dynamically create a hosted checkout and get paid:

Example Request

cURL 
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 "@payload.json"

Where payload.json is a simple JSON object. Learn about authentication here.

Example Payload (minimal)

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

Above is the simplest form of creating a checkout. You submit a charge with exactly one line item at the cost of 10.00 USD. In the response the API returns an id along with a hosted checkout URL, which you display back to your customer in order for him or her to complete the payment.

Example Response

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

Once the payment is captured we notify you via WEBHOOK /payment. Alternatively you can poll GET /checkout for payment status updates.

If you prefer to control and host the entire checkout process in your own web application and branding instead, have a look at POST /checkout.

PRO Tip

You can inspect your API requests and the associated HTTP responses sent by COINQVEST in your .

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 will continuously observe 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.

Once the payment has been sent, 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).

If you do not want to listen for webhook callbacks, you can monitor the GET /checkout endpoint by supplying the unique identifier that was provided when you created the checkout. Here is a simplified example:

Example Request

cURL 
curl 'https://www.coinqvest.com/api/v1/checkout?id=b5bcf27e5482' \
-H "X-Digest-Key: YOUR_API_KEY" \
-H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
-H "X-Digest-Timestamp: TIMESTAMP"

The endpoint returns an object with information about the current payment state, time to expiration and other parameters as specified in GET /checkout.

Software Development Kits

COINQVEST works with any REST client in any programming language. For convenient and quick implementation please consider our SDKs on GitHub.

PHP Logo

PHP
Official COINQVEST Merchant SDK for PHP


Ruby Logo

Ruby
Official COINQVEST Merchant SDK for Ruby


NodeJS Logo

NodeJS
Official COINQVEST Merchant SDK for NodeJS

Read our Developer Guide

Developer Guide To learn more about creating checkouts and getting paid using the COINQVEST Merchant API, read our developers guide, Accept Cryptocurrency Payments with COINQVEST Merchant APIs.

Not a Developer?

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

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 API-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 
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.

PHP Logo Code Example (PHP)

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);

Ruby Logo Code Example (Ruby)

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)

Ruby Logo Code Example (NodeJS)

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

Albeit simpler to implement, Basic-Auth is less secure than Digest-Auth and we recommend using the latter instead. By default COINQVEST API docs and examples always utilize Digest-Auth, but you can use Basic-Auth by replacing X-Digest headers with X-Basic, which is explained below:

Request

cURL 
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

PHP 
$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.

Concepts

This segment explains... https://www.codecademy.com/articles/what-is-rest

View Integrations in UI

Software Development Kits (SDKs)

We're continuously updating our software development kits (SDKs) to help you integrate with COINQVEST Merchant APIs as conveniently and quickly as possible.

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

PHP Logo

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
Ruby Logo

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
NodeJS Logo

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

POST/checkoutprotected

Invoking a checkout is the first step to get paid. This endpoint creates a white-label checkout, 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 
curl -X POST https://www.coinqvest.com/api/v1/checkout \
        -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

application/json 
{
   "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)

application/json 
{
   "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

200 OK 
{
   "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

4xx/5xx 
{
    "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)

200 OK 
{
   "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 
curl -X POST 'https://www.coinqvest.com/api/v1/checkout/commit'
-d "@payload.json"

Where payload.json is a JSON object.

Example Payload

application/json 
{
  "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

200 OK 
{
   "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

200 OK 
{
   "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

200 OK 
{
   "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

4xx/5xx 
{
    "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 
curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
        -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

application/json 
{
   "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)

application/json 
{
   "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

200 OK 
{
    "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

4xx/5xx 
{
    "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 crucial information about payments associated with this checkout as well as its overall completion state.

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 
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

200 OK 
{
   "checkout":{
      "id":"82098fd51fcc",
      "timestamp":"2020-03-02T19:36:33+00:00",
      "state":"COMPLETED",
      "hostedCheckoutUrl":null,
      "payments":[
         {
            "id":"06aadf4b25ac",
            "type":"PAYMENT",
            "state":"RESOLVED",
            "timestamp":"2020-03-02T21:37:10+02:00",
            "creditAssetCode":"USD",
            "creditAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "creditAmount":"10.0000000",
            "sourceAssetCode":"XLM",
            "sourceAssetIssuer":"XLM:NATIVE",
            "sourceAmount":"170.1372000",
            "sourceBlockchain":"XLM",
            "sourceAccount":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
            "sourceTxId":"1424f2e6d98c9a49b52baeaac5906a4d9e1cf5071d7cb558331ec23b5238258c",
            "customerId":"1acf0d0b10bd",
            "checkoutId":"82098fd51fcc"
         }
      ],
      "payload":{
         "charge":{
            "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "customerId":"1acf0d0b10bd",
            "lineItems":[
               {
                  "description":"T-Shirt",
                  "netAmount":10
               }
            ]
         },
         "settlementCurrency":"USD"
      }
   }
}

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_CHARGECharge has been created and is awaiting customer payment.
IN_PROGRESSPayment has been detected on the blockchain and is awaiting confirmation.
COMPLETEDPayment has been confirmed and deposited to your account.
EXPIREDCharge has expired without a payment.
UNRESOLVED_GENERICPayment has diverged from what was expected or a generic error occurred.
UNRESOLVED_UNDERPAIDPayment amount was less than expected.
UNRESOLVED_OVERPAIDPayment amount was more than expected.
DELAYED_COMPLETEDPayment has successfully completed after the charge expired.
DELAYED_UNDERPAIDPayment arrived after the charge expired and was less than expected.
DELAYED_OVERPAIDPayment arrived after the charge expired and was more than expected.
RESOLVEDPayment has been marked as resolved by the merchant.
 false
.hostedCheckoutUrl string The checkout URL if this is a hosted checkout. Otherwise null. true
.payments[] array A list of payment objects associated with this checkout. false
.id string(12) Unique identifier of this payment. false
.type string The payment type. Currently the only existing value is PAYMENT, which represents a payment sent by a customer. false
.state string RESOLVED or UNRESOLVED. Indicates whether this payment has been resolved and credited to your account. A payment is flagged as unresolved if the payment amount was below or above what was expected or another exception occurred. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the payment was made. false
.creditAssetCode string The asset code credited to your account (e.g USD). false
.creditAssetIssuer string Identifier of the issuer of the asset credited to your account, see GET /asset-issuers. false
.creditAmount numeric The amount credited to your account. false
.sourceAssetCode string This field represents the asset used by your customer to make this payment (e.g. BTC, XLM, ETH, LTC, XRP). false
.sourceAssetIssuer string This field indicates the entity that processed this payment on your behalf, see GET /asset-issuers. false
.sourceAmount numeric This field displays the exact amount paid by your customer to make this payment. false
.sourceBlockchain string(3) References the blockchain from which this payment originated, see GET /blockchains. false
.sourceAccount string Specifies the blockchain account from which the payment originated. This account lives on the blockchain given in sourceBlockchain. true
.sourceTxId string Specifies the transaction id related to this payment. This transaction lives on the blockchain given in sourceBlockchain. true
.customerId string(12) References the customer related to this payment, see GET /customer. true
.checkoutId string(12) References the checkout related to this payment, see GET /checkout. false
.payload{} object The checkout payload as originally submitted by you to POST /checkout or POST /checkout/hosted. false

Error Response application/json

4xx/5xx 
{
    "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 
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

200 OK 
{
   "count":67,
   "limit":"2",
   "offset":0,
   "checkouts":[
      {
         "id":"82098fd51fcc",
         "timestamp":"2020-03-02T19:36:33+00:00",
         "state":"COMPLETED",
         "hostedCheckoutUrl":null,
         "payments":[
            {
               "id":"06aadf4b25ac",
               "type":"PAYMENT",
               "state":"RESOLVED",
               "timestamp":"2020-03-02T21:37:10+02:00",
               "creditAssetCode":"USD",
               "creditAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "creditAmount":"0.0100000",
               "sourceAssetCode":"XLM",
               "sourceAssetIssuer":"XLM:NATIVE",
               "sourceAmount":"0.1701372",
               "sourceBlockchain":"XLM",
               "sourceAccount":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
               "sourceTxId":"1424f2e6d98c9a49b52baeaac5906a4d9e1cf5071d7cb558331ec23b5238258c",
               "customerId":"1acf0d0b10bd",
               "checkoutId":"82098fd51fcc"
            }
         ],
         "payload":{
            "charge":{
               "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "customerId":"1acf0d0b10bd",
               "lineItems":[
                  {
                     "description":"Sticker",
                     "netAmount":0.01
                  }
               ]
            },
            "settlementCurrency":"USD"
         }
      },
      {
         "id":"e506f9a487dc",
         "timestamp":"2020-03-02T19:49:56+00:00",
         "state":"EXPIRED",
         "hostedCheckoutUrl":null,
         "payments":[

         ],
         "payload":{
            "charge":{
               "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "customerId":"1acf0d0b10bd",
               "lineItems":[
                  {
                     "description":"Sticker",
                     "netAmount":0.01
                  }
               ]
            },
            "settlementCurrency":"USD"
         }
      }
   ]
}

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_CHARGECharge has been created and is awaiting customer payment.
IN_PROGRESSPayment has been detected on the blockchain and is awaiting confirmation.
COMPLETEDPayment has been confirmed and deposited to your account.
EXPIREDCharge has expired without a payment.
UNRESOLVED_GENERICPayment has diverged from what was expected or a generic error occurred.
UNRESOLVED_UNDERPAIDPayment amount was less than expected.
UNRESOLVED_OVERPAIDPayment amount was more than expected.
DELAYED_COMPLETEDPayment has successfully completed after the charge expired.
DELAYED_UNDERPAIDPayment arrived after the charge expired and was less than expected.
DELAYED_OVERPAIDPayment arrived after the charge expired and was more than expected.
RESOLVEDPayment has been marked as resolved by the merchant.
 false
.hostedCheckoutUrl string The checkout URL if this is a hosted checkout. Otherwise null. true
.payments[] array A list of payment objects associated with this checkout. false
.id string(12) Unique identifier of this payment. false
.type string The payment type. Currently the only existing value is PAYMENT, which represents a payment sent by a customer. false
.state string RESOLVED or UNRESOLVED. Indicates whether this payment has been resolved and credited to your account. A payment is flagged as unresolved if the payment amount was below or above what was expected or another exception occurred. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the payment was made. false
.creditAssetCode string The asset code credited to your account (e.g USD). false
.creditAssetIssuer string Identifier of the issuer of the asset credited to your account, see GET /asset-issuers. false
.creditAmount numeric The amount credited to your account. false
.sourceAssetCode string This field represents the asset used by your customer to make this payment (e.g. BTC, XLM, ETH, LTC, XRP). false
.sourceAssetIssuer string This field indicates the entity that processed this payment on your behalf, see GET /asset-issuers. false
.sourceAmount numeric This field displays the exact amount paid by your customer to make this payment. false
.sourceBlockchain string(3) References the blockchain from which this payment originated, see GET /blockchains. false
.sourceAccount string Specifies the blockchain account from which the payment originated. This account lives on the blockchain given in sourceBlockchain. true
.sourceTxId string Specifies the transaction id related to this payment. This transaction lives on the blockchain given in sourceBlockchain. true
.customerId string(12) References the customer related to this payment, see GET /customer. true
.checkoutId string(12) References the checkout related to this payment, see GET /checkout. false
.payload{} object The checkout payload as originally submitted by you to POST /checkout or POST /checkout/hosted. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/paymentprotected

Retrieves details of a given payment.

Request

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

Request Params

Key Type Description Default Mandatory
id string(12) Unique identifier as given by GET /payments, the GET /checkouts endpoint or WEBHOOK payment. null mandatory

Success Response application/json

200 OK 
{
   "payment":{
      "id":"0bb9f9aa929f",
      "type":"PAYMENT",
      "state":"RESOLVED",
      "timestamp":"2020-03-01T13:33:51+02:00",
      "creditAssetCode":"USD",
      "creditAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "creditAmount":"1.0000000",
      "sourceAssetCode":"XRP",
      "sourceAssetIssuer":"XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
      "sourceAmount":"4.4292550",
      "sourceBlockchain":"XRP",
      "sourceAccount":"rEfqXNqQoyVVgkcF51NQNGWst96KJFZQf2",
      "sourceTxId":"49A5EB13E1900BF800BF402B8D46FAF94315CA54D63050A7741BB55544772642",
      "customerId":"1acf0d0b10bd",
      "checkoutId":"2b2813372e89"
   }
}

Success Response Attributes

Name Type Description Nullable
.payment{} object An object with details about the payment. false
.id string(12) Unique identifier of this payment. false
.type string The payment type. Currently the only existing value is PAYMENT, which represents a payment sent by a customer. false
.state string RESOLVED or UNRESOLVED. Indicates whether this payment has been resolved and credited to your account. A payment is flagged as unresolved if the payment amount was below or above what was expected or another exception occurred. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the payment was made. false
.creditAssetCode string The asset code credited to your account (e.g USD). false
.creditAssetIssuer string Identifier of the issuer of the asset credited to your account, see GET /asset-issuers. false
.creditAmount numeric The amount credited to your account. false
.sourceAssetCode string This field represents the asset used by your customer to make this payment (e.g. BTC, XLM, ETH, LTC, XRP). false
.sourceAssetIssuer string This field indicates the entity that processed this payment on your behalf, see GET /asset-issuers. false
.sourceAmount numeric This field displays the exact amount paid by your customer to make this payment. false
.sourceBlockchain string(3) References the blockchain from which this payment originated, see GET /blockchains. false
.sourceAccount string Specifies the blockchain account from which the payment originated. This account lives on the blockchain given in sourceBlockchain. true
.sourceTxId string Specifies the transaction id related to this payment. This transaction lives on the blockchain given in sourceBlockchain. true
.customerId string(12) References the customer related to this payment, see GET /customer. true
.checkoutId string(12) References the checkout related to this payment, see GET /checkout. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/paymentsprotected

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

Request

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

Request Params

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

Success Response application/json

200 OK 
{
   "count":2,
   "limit":250,
   "offset":0,
   "payments":[
      {
         "id":"0bb9f9aa929f",
         "type":"PAYMENT",
         "state":"RESOLVED",
         "timestamp":"2020-03-01T13:33:51+02:00",
         "creditAssetCode":"USD",
         "creditAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "creditAmount":"1.0000000",
         "sourceAssetCode":"XRP",
         "sourceAssetIssuer":"XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
         "sourceAmount":"4.4292550",
         "sourceBlockchain":"XRP",
         "sourceAccount":"rEfqXNqQoyVVgkcF51NQNGWst96KJFZQf2",
         "sourceTxId":"49A5EB13E1900BF800BF402B8D46FAF94315CA54D63050A7741BB55544772642",
         "customerId":"1acf0d0b10bd",
         "checkoutId":"2b2813372e89"
      },
      {
         "id":"9de6b7b383a3",
         "type":"PAYMENT",
         "timestamp":"2020-03-01T16:16:51+02:00",
         "creditAssetCode":"USD",
         "creditAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "creditAmount":"1.0000000",
         "sourceAssetCode":"XLM",
         "sourceAssetIssuer":"XLM:NATIVE",
         "sourceAmount":"17.7043058",
         "sourceBlockchain":"XLM",
         "sourceAccount":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
         "sourceTxId":"21c604fc094f7f017138ddbee2215d7f7d993c4f77de2a0e887dc107da9915b7",
         "customerId":null,
         "checkoutId":"ba34d3ccda14"
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.count integer The total number of payments received in this account. false
.limit integer The limit argument used in this request. false
.offset integer The pagination offset used in this request. false
.payments[] array A list of payment objects. false
.id string(12) Unique identifier of this payment. false
.type string The payment type. Currently the only existing value is PAYMENT, which represents a payment sent by a customer. false
.state string RESOLVED or UNRESOLVED. Indicates whether this payment has been resolved and credited to your account. A payment is flagged as unresolved if the payment amount was below or above what was expected or another exception occurred. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the payment was made. false
.creditAssetCode string The asset code credited to your account (e.g USD). false
.creditAssetIssuer string Identifier of the issuer of the asset credited to your account, see GET /asset-issuers. false
.creditAmount numeric The amount credited to your account. false
.sourceAssetCode string This field represents the asset used by your customer to make this payment (e.g. BTC, XLM, ETH, LTC, XRP). false
.sourceAssetIssuer string This field indicates the entity that processed this payment on your behalf, see GET /asset-issuers. false
.sourceAmount numeric This field displays the exact amount paid by your customer to make this payment. false
.sourceBlockchain string(3) References the blockchain from which this payment originated, see GET /blockchains. false
.sourceAccount string Specifies the blockchain account from which the payment originated. This account lives on the blockchain given in sourceBlockchain. true
.sourceTxId string Specifies the transaction id related to this payment. This transaction lives on the blockchain given in sourceBlockchain. true
.customerId string(12) References the customer related to this payment, see GET /customer. true
.checkoutId string(12) References the checkout related to this payment, see GET /checkout. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/walletsprotected

Returns a list of all wallets in your account, along with the corresponding balances.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/wallets'

Success Response application/json

200 OK 
{
   "wallets":[
      {
         "assetCode":"XLM",
         "type":"CRYPTO",
         "balance":950,
         "assets":[
            {
               "id":"XLM:NATIVE",
               "issuerName":"Stellar Development Foundation (SDF)",
               "issuerDomain":"stellar.org",
               "balance":950,
               "path":"\/api\/v1\/asset?id=XLM:NATIVE"
            }
         ]
      },
      {
         "assetCode":"BTC",
         "type":"CRYPTO",
         "balance":0,
         "assets":[

         ]
      },
      {
         "assetCode":"ETH",
         "type":"CRYPTO",
         "balance":0,
         "assets":[

         ]
      },
      {
         "assetCode":"LTC",
         "type":"CRYPTO",
         "balance":0,
         "assets":[

         ]
      },
      {
         "assetCode":"XRP",
         "type":"CRYPTO",
         "balance":562.9698492,
         "assets":[
            {
               "id":"XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
               "issuerName":"Stellarport",
               "issuerDomain":"stellarport.io",
               "balance":562.9698492,
               "path":"\/api\/v1\/asset?id=XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5"
            }
         ]
      },
      {
         "assetCode":"EUR",
         "type":"FIAT",
         "balance":0,
         "assets":[

         ]
      },
      {
         "assetCode":"NGN",
         "type":"FIAT",
         "balance":3938.25,
         "assets":[
            {
               "id":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
               "issuerName":"Cowrie",
               "issuerDomain":"cowrie.exchange",
               "balance":3938.25,
               "path":"\/api\/v1\/asset?id=NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD"
            }
         ]
      },
      {
         "assetCode":"USD",
         "type":"FIAT",
         "balance":10.835825,
         "assets":[
            {
               "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "issuerName":"AnchorUSD",
               "issuerDomain":"anchorusd.com",
               "balance":10.835825,
               "path":"\/api\/v1\/asset?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
            }
         ]
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.wallets[] array A list objects, representing the wallets in your account. false
.assetCode string(3) The wallet's asset code, e.g. BTC or USD. false
.type string The wallet type, i.e. FIAT or CRYPTO. false
.balance numeric The total balance in this wallet. This is the sum of all asset balances held in this wallet, see below. false
.assets[] array A list of objects, representing the assets held in this wallet, along with their corresponding balances. false
.id string The unique id of asset. For the machines among us. false
.issuerName string The name of the asset issuer. false
.issuerDomain string The asset issuer's domain. false
.balance numeric The amount of this asset currently held in this wallet. false
.path string Invoke this endpoint to obtain more information about this asset. See GET /asset. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/walletprotected

Retrieves wallet details based on the given assetCode.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/wallet?assetCode=XXX'

Request Params

Key Type Description Default Mandatory
assetCode string(3) Specifies which wallet to retrieve, e.g. BTC or USD - mandatory

Success Response application/json

200 OK 
{
   "wallet":{
      "assetCode":"USD",
      "type":"FIAT",
      "balance":10.835825,
      "assets":[
         {
            "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "issuerName":"AnchorUSD",
            "issuerDomain":"anchorusd.com",
            "balance":10.835825,
            "path":"\/api\/v1\/asset?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      ]
   }
}

Success Response Attributes

Name Type Description Nullable
.wallet{} array An object containing information about the wallet. false
.assetCode string(3) The wallet's asset code, e.g. BTC or USD. false
.type string The wallet type, i.e. FIAT or CRYPTO. false
.balance numeric The total balance in this wallet. This is the sum of all asset balances held in this wallet, see below. false
.assets[] array A list of objects, representing the assets held in this wallet, along with their corresponding balances. false
.id string The unique id of asset. For the machines among us. false
.issuerName string The name of the asset issuer. false
.issuerDomain string The asset issuer's domain. false
.balance numeric The amount of this asset currently held in this wallet. false
.path string Invoke this endpoint to obtain more information about this asset. See GET /asset. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

POST/withdrawalprotected

This endpoint is invoked when you wish to withdraw funds from the COINQVEST platform into your own cryptocurrency wallets or fiat bank accounts.

This endpoint takes a list of parameters, which include the source asset to withdraw from, as well as information on the target account to deposit the funds into.

Upon successful completion, the endpoint returns a withdrawal object, which includes the guaranteed amount that will be deposited into the target account when you confirm the withdrawal by submitting a subsequent request to the POST /withdrawal/commit endpoint.

Example Request

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

Where payload.json is a JSON object.

Example Payload (Withdrawal to the Stellar Network)

application/json 
{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":10,
   "targetNetwork":"XLM",
   "targetAsset":"XLM:NATIVE",
   "targetAccount":{
      "account":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"EXODUS",
      "memoType":"text"
   }
}

In above example 10 USD are withdrawn from your COINQVEST wallet, converted into XLM and sent to the Stellar Network account GASKY...6EDCQ.

Example Payload (Withdrawal to an EU IBAN Bank Account)

application/json 
{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"EUR",
   "targetAccount":{
      "iban":"DE23100110012624331587",
      "swift":"NTSBDEB1XXX"
   }
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into EUR and sent to the EU bank account with the IBAN DE23...1587 at SWIFT NTS...XXX.

Example Payload (Withdrawal to the Bitcoin Network)

application/json 
{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"BTC",
   "targetAccount":{
      "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
   },
   "relay":"BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5"
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into native BTC and sent to the Bitcoin address bc1q...ew23. The payload specifically elects the asset issuer BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5 (Stellarport) to process this payment and convert the funds on COINQVEST into native Bitcoin. See GET /asset-issuers for a list of available asset issuers.

Example Payload (Withdrawal to the Ripple Network)

application/json 
{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"XRP",
   "targetAccount":{
      "account":"rEfqXNqQoyVVgkcF51NQNGWst96KJFZQf2",
      "destinationTag":"1234"
   }
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into native XRP and sent to the XRP Ledger account rEfq...ZQf2.

Example Payload (Withdrawal to an NGN Bank Account)

application/json 
{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"NGN",
   "targetAccount":{
      "nuban":"3080494548",
      "bankName":"FirstBank"
   }
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into Nigerian Naira (NGN) and sent to the NUBAN bank account 3080494548 at FirstBank.

Request Params (POST)

Key Type Description Nullable Mandatory
.sourceAsset string Specifies the source asset from which you want to withdraw. Invoke GET /wallets to inspect which assets you currently hold. false mandatory
.sourceAmount string The exact amount you wish to withdraw. Invoke GET /wallets to inspect how much sourceAsset you currently hold. false mandatory
.targetNetwork string(3) Specifies the blockchain or fiat currency to which you want to withdraw. This field takes a blockchain asset code as given by GET /blockchains or a fiat currency asset code as given by GET /fiat-currencies. Examples: Set this to XLM if you wish to withdraw to the Stellar Network, to EUR if you wish to withdraw to an EU IBAN bank account or BTC if you wish to withdraw to the Bitcoin network. false mandatory
.targetAsset string This field is only relevant when the targetNetwork is set to XLM (withdrawal to the Stellar Network).

It specifies the target asset you want the recipient to be credited in. If no value is given then the target account is credited in sourceAsset.

Required format is XLM:NATIVE for XLM or USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX for USD by AnchorUSD.		 true optional
.targetAccount object An object describing the target account to which the payment should be sent.

This field is mutable and its contents depend on the requirements of the related targetNetwork used in the request.

Field Attributes for withdrawals to CAD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field Attributes for withdrawals to EUR
iban The recipient bank account's IBAN.
swift The recipient bank account's SWIFT/BIC.

Field Attributes for withdrawals to NGN
nuban The recipient bank account's NUBAN.
bankName The recipient bank's name. The only possible choices are The recipient bank's name. The only possible choices are AccessBank, CitiBank, DiamondBank, Ecobank, EnterpriseBank, FCMB, FidelityBank, FirstBank, GTBank, Heritage, JaizBank, KeystoneBank, ProvidusBank, SkyeBank, Stanbic, StandardChartered, SterlingBank, SuntrustBank, UBA, UnionBank, UnityBank, WemaBank, ZenithBank.

Field Attributes for withdrawals to USD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field Attributes for withdrawals to BTC, ETH, LTC
address The address to which the withdrawal should be sent.

Field Attributes for withdrawals to XLM (any Stellar Network asset)
account The account to which the withdrawal should be sent.
memo The Stellar memo used in this payment. Can be null.
memoType The type of memo, if any. Can be null.

Field Attributes for withdrawals to XRP
account The account to which the withdrawal should be sent.
destinationTag The Ripple destination tag used in this payment. Can be null.

false mandatory
.relay string This field takes a assetIssuerId as given by GET /asset-issuers and is only relevant for withdrawals to fiat currencies and blockchains other than the Stellar Network. It specifies the asset issuer (Stellar Anchor) that should be used to process the payment and convert funds into native USD, NGN, EUR, BTC, ETH, LTC, XRP. If no relay is specified then the option with the highest resulting target amount (your most economic option) is automatically selected. See GET /asset-issuers for a list of available options. true optional

Success Response application/json

200 OK 
{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":null,
      "targetAccount":{
         "nuban":"3080494548",
         "bankName":"FirstBank"
      }
   }
}

Above response is issued in response to a withdrawal request over 142.315660 USD, conversion into NGN and deposit into an NGN bank account in the form of native NGN fiat money (targetFiatCurrency is set to NGN).

Success Response Attributes

Name Type Description Nullable
.withdrawal{} object An object with details about the withdrawal. false
.id string(12) Unique identifier of this withdrawal. false
.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false
.state string This field represents the withdrawal state. The only possible state in a response to the POST /withdrawal endpoint is PENDING_API_COMMIT. This state indicates that the withdrawal has been initialized, a target amount was calculated and the withdrawal is awaiting confirmation by the POST /withdrawal/commit endpoint. false
.origin string This field indicates how the withdrawal was initiated, either UI or API. The only possible origin in a response to the POST /withdrawal endpoint is API. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false
.sourceAssetCode string The asset code debited from your account (e.g USD). false
.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. Invoke GET /wallets to inspect which assets you currently hold. false
.sourceAmount numeric The amount debited from your account. false
.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false
.targetAssetIssuer string This field indicates the entity that will process this withdrawal on your behalf, see GET /asset-issuers. false
.targetAmount numeric This field displays the guaranteed amount received in the target account. false
.withdrawalFee numeric This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account will be debited the equivalent of the sum of
targetAssetIssuerFee + targetAmount. 		false
.targetBlockchain string(3) References the blockchain to which this withdrawal will be sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true
.targetFiatCurrency string(3) References the fiat currency to which this withdrawal will be sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true
.transactionId string(64) References the related transaction on the Stellar Network. The only value in a response to the POST /withdrawal endpoint is null because the transaction does not execute until the withdrawal is confirmed by invoking the POST /withdrawal/commit endpoint. true
.targetAccount object An object describing the target account to which the payment will be sent.

This field is mutable and its contents depend on the requirements of the related targetNetwork originally used in the request.

Field attributes for withdrawals to CAD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to EUR
iban The recipient bank account's IBAN.
swift The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN
nuban The recipient bank account's NUBAN.
bankName The recipient bank's name.

Field attributes for withdrawals to USD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC
address The address to which the withdrawal should be sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)
account The account to which the withdrawal should be sent.
memo The Stellar memo used in this payment. Can be null.
memoType The type of memo, if any. Can be null.

Field attributes for withdrawals to XRP
account The account to which the withdrawal should be sent.
destinationTag The Ripple destination tag used in this payment. Can be null.

false

Next Step

Your application analyzes the API response and determines whether it wants to accept the guaranteed targetAmount. To finalize the withdrawal, you confirm it by invoking the POST /withdrawal/commit endpoint.

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

POST/withdrawal/commitprotected

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

This endpoint takes a withdrawalId parameter as given by POST /withdrawal. Upon successful completion, the withdrawal is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to COMPLETED in the response.

In the previous step POST /withdrawal has given you an object, like this:

Example Response (as given by POST /withdrawal)

200 OK 
{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":null,
      "targetAccount":{
         "nuban":"3080494548",
         "bankName":"FirstBank"
      }
   }
}

As a prerequisite, to invoke this endpoint you should have received a response as above from POST /withdrawal. Its state is PENDING_API_COMMIT, which means it is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given targetAmount, you invoke POST /withdrawal/commit (this endpoint) to confirm the withdrawal and submit it for processing.

Request

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

Where payload.json is a JSON object.

Example Payload

application/json 
{
  "withdrawalId":"12d72c3c8145"
}

Request Params

Key Type Description Default Mandatory
withdrawalId string(12) Unique identifier as given by POST /withdrawal. null mandatory

Success Response application/json

200 OK 
{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"COMPLETED",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
      "targetAccount":{
         "nuban":"3080494548",
         "bankName":"FirstBank"
      }
   }
}

Success Response Attributes

Name Type Description Nullable
.withdrawal{} object An object with details about the withdrawal. false
.id string(12) Unique identifier of this withdrawal. false
.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false
.state string This field represents the withdrawal state. The only possible state in a response to the POST /withdrawal/commit endpoint is COMPLETED . This state indicates that the withdrawal has been processed and the money is on the way (or has been deposited if you're withdrawing to a fast blockchain) . false
.origin string This field indicates how the withdrawal was initiated, either UI or API. The only possible origin in a response to the POST /withdrawal/commit endpoint is API. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false
.sourceAssetCode string The asset code debited from your account (e.g USD). false
.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. false
.sourceAmount numeric The amount debited from your account. false
.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false
.targetAssetIssuer string This field indicates the entity that processed this withdrawal on your behalf, see GET /asset-issuers. false
.targetAmount numeric This field displays the amount received in the target account. false
.withdrawalFee numeric This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account was debited the equivalent of the sum of
targetAssetIssuerFee + targetAmount. 		false
.targetBlockchain string(3) References the blockchain to which this withdrawal was sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true
.targetFiatCurrency string(3) References the fiat currency to which this withdrawal was sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true
.transactionId string(64) References the related transaction on the Stellar Network. true
.targetAccount object An object describing the target account to which the payment was sent.

This field is mutable and its contents depend on the requirements of the related targetBlockchain or targetFiatCurrency.

Field attributes for withdrawals to CAD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to EUR
iban The recipient bank account's IBAN.
swift The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN
nuban The recipient bank account's NUBAN.
bankName The recipient bank's name.

Field attributes for withdrawals to USD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC
address The address to which the withdrawal was sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)
account The account to which the withdrawal was sent.
memo The Stellar memo used in this payment. Can be null.
memoType The type of memo, if any. Can be null.

Field attributes for withdrawals to XRP
account The account to which the withdrawal was sent.
destinationTag The Ripple destination tag used in this payment. Can be null.

false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/withdrawalprotected

Retrieves details of a given withdrawal.

Request

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

Request Params

Key Type Description Default Mandatory
id string(12) Unique identifier as given by GET /withdrawals or POST /withdrawal. null mandatory

Success Response application/json

200 OK 
{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"COMPLETED",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
      "targetAccount":{
         "nuban":"3080494548",
         "bankName":"FirstBank"
      }
   }
}

Success Response Attributes

Name Type Description Nullable
.withdrawal{} object An object with details about the withdrawal. false
.id string(12) Unique identifier of this withdrawal. false
.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false
.state string This field represents the withdrawal state. Currently, the only possible values are COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. false
.origin string This field indicates how the withdrawal was initiated, either UI or API. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false
.sourceAssetCode string The asset code debited from your account (e.g USD). false
.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. false
.sourceAmount numeric The amount debited from your account. false
.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false
.targetAssetIssuer string This field indicates the entity that processed this withdrawal on your behalf, see GET /asset-issuers. false
.targetAmount numeric This field displays the amount received in the target account. false
.withdrawalFee numeric This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account was debited the equivalent of the sum of
targetAssetIssuerFee + targetAmount. 		false
.targetBlockchain string(3) References the blockchain to which this withdrawal was sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true
.targetFiatCurrency string(3) References the fiat currency to which this withdrawal was sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true
.transactionId string(64) References the related transaction on the Stellar Network. true
.targetAccount object An object describing the target account to which the payment was sent.

This field is mutable and its contents depend on the requirements of the related targetBlockchain or targetFiatCurrency.

Field attributes for withdrawals to CAD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to EUR
iban The recipient bank account's IBAN.
swift The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN
nuban The recipient bank account's NUBAN.
bankName The recipient bank's name.

Field attributes for withdrawals to USD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC
address The address to which the withdrawal was sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)
account The account to which the withdrawal was sent.
memo The Stellar memo used in this payment. Can be null.
memoType The type of memo, if any. Can be null.

Field attributes for withdrawals to XRP
account The account to which the withdrawal was sent.
destinationTag The Ripple destination tag used in this payment. Can be null.

false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/withdrawalsprotected

Retrieves a list of your withdrawals (in descending order from newest to oldest).

Request

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

Request Params

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

Success Response application/json

200 OK 
{
   "count":2,
   "limit":"10",
   "offset":0,
   "withdrawals":[
      {
         "id":"b35c97c377f9",
         "type":"WITHDRAWAL",
         "state":"COMPLETED",
         "origin":"UI",
         "timestamp":"2020-03-04T17:22:39+02:00",
         "sourceAssetCode":"XLM",
         "sourceAssetIssuer":"XLM:NATIVE",
         "sourceAmount":"0.1765850",
         "targetAssetCode":"XLM",
         "targetAssetIssuer":"XLM:NATIVE",
         "targetAmount":"0.1765850",
         "withdrawalFee":"0",
         "targetBlockchainId":"XLM",
         "targetFiatCurrencyId":null,
         "transactionId":"b7bb615cabf971d1e00256ae87249333e4deb9ef1ad5dad80ee2af0ea21d050b",
         "targetAccount":{
            "account":"GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo":"EXODUS",
            "memoType":"text"
         }
      },
      {
         "id":"12d72c3c8145",
         "type":"WITHDRAWAL",
         "state":"COMPLETED",
         "origin":"UI",
         "timestamp":"2020-03-04T19:54:47+02:00",
         "sourceAssetCode":"USD",
         "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "sourceAmount":"1.4231566",
         "targetAssetCode":"NGNT",
         "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
         "targetAmount":"315.0909904",
         "withdrawalFee":"200.0000000",
         "targetBlockchainId":null,
         "targetFiatCurrencyId":"NGN",
         "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
         "targetAccount":{
            "nuban":"3080494548",
            "bankName":"FirstBank"
         }
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.count integer The total number of withdrawals received in this account. false
.limit integer The limit argument used in this request. false
.offset integer The pagination offset used in this request. false
.withdrawals[] array A list of withdrawal objects. false
.id string(12) Unique identifier of this withdrawal. false
.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false
.state string This field represents the withdrawal state. Currently, the only possible values are COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. false
.origin string This field indicates how the withdrawal was initiated, either UI or API. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false
.sourceAssetCode string The asset code debited from your account (e.g USD). false
.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. false
.sourceAmount numeric The amount debited from your account. false
.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false
.targetAssetIssuer string This field indicates the entity that processed this withdrawal on your behalf, see GET /asset-issuers. false
.targetAmount numeric This field displays the amount received in the target account. false
.withdrawalFee numeric This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account was debited the equivalent of the sum of
targetAssetIssuerFee + targetAmount. 		false
.targetBlockchain string(3) References the blockchain to which this withdrawal was sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true
.targetFiatCurrency string(3) References the fiat currency to which this withdrawal was sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true
.transactionId string(64) References the related transaction on the Stellar Network. true
.targetAccount object An object describing the target account to which the payment was sent.

This field is mutable and its contents depend on the requirements of the related targetBlockchain or targetFiatCurrency.

Field attributes for withdrawals to CAD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to EUR
iban The recipient bank account's IBAN.
swift The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN
nuban The recipient bank account's NUBAN.
bankName The recipient bank's name.

Field attributes for withdrawals to USD
accountNumber The recipient's bank account number.
routingNumber The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC
address The address to which the withdrawal was sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)
account The account to which the withdrawal was sent.
memo The Stellar memo used in this payment. Can be null.
memoType The type of memo, if any. Can be null.

Field attributes for withdrawals to XRP
account The account to which the withdrawal was sent.
destinationTag The Ripple destination tag used in this payment. Can be null.

false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/asset-issuersprotected

Returns a list of asset issuers supported by the COINQVEST platform. Assets represent a crypto or fiat currency and exist as tokens on the Stellar Network. Asset issuers are the regulated financial institutions, companies or other entities that bring assets on and off the network.

Whenever you receive a payment, funds are tokenized on the Stellar Network and credited to your account. When you make a withdrawal, funds are de-tokenized and converted back into their true form, e.g. money in your bank account or funds on the native Bitcoin blockchain.

Asset issuers are responsible for tokenizing and de-tokenizing assets during customer checkouts and withdrawals from the COINQVEST platform.

If you have a preference you can explicitly specify asset issuers during checkout and withdrawal, otherwise the platform default or the most economic option for you is automatically selected.

View Asset Issuers in UI

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/asset-issuers'

Success Response application/json

200 OK 
{
   "assetIssuers":[
      {
         "id":"BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
         "name":"Stellarport",
         "domain":"stellarport.io",
         "address":"StellarPort LLC, Chicago, IL, United States",
         "country":"US",
         "type":"CRYPTO",
         "checkouts":{
            "enabled":true,
            "min":"0.0002000",
            "max":null,
            "feeFixed":"0.0000000",
            "feePercent":"0.0000000"
         },
         "withdrawals":{
            "enabled":true,
            "min":"0.0050000",
            "max":null,
            "feeFixed":"0.0005000",
            "feePercent":"0.0050000"
         },
         "asset":{
            "id":"BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
            "name":"Bitcoin",
            "path":"\/api\/v1\/asset?id=BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5"
         },
         "blockchain":{
            "nativeAssetCode":"BTC",
            "name":"Bitcoin",
            "path":"\/api\/v1\/blockchain?assetCode=BTC"
         },
         "fiatCurrency":null
      },
      {
         "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "name":"AnchorUSD",
         "domain":"anchorusd.com",
         "address":"AnchorCoin LLC, CA, United States",
         "country":"US",
         "type":"FIAT",
         "checkouts":{
            "enabled":false,
            "min":"5.0000000",
            "max":null,
            "feeFixed":"5.0000000",
            "feePercent":"0.0100000"
         },
         "withdrawals":{
            "enabled":true,
            "min":"15.0000000",
            "max":null,
            "feeFixed":"5.0000000",
            "feePercent":"0.0200000"
         },
         "asset":{
            "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "name":"US Dollar",
            "path":"\/api\/v1\/asset?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         },
         "blockchain":null,
         "fiatCurrency":{
            "assetCode":"USD",
            "name":"US Dollar",
            "path":"\/api\/v1\/fiat-currency?assetCode=USD"
         }
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.assetIssuers[] array A list of asset issuers available on the COINQVEST platform. false
.id string The unique id of this anchor. false
.name string The issuer's name in plain text. false
.domain string The issuer's internet domain. This is a good place to start your due diligence. false
.address string The issuer's company name and registered address. false
.country string The issuer's country of origin. false
.type string An asset issuer can be of type CRYPTO or FIAT.

CRYPTO issuers tokenize cryptocurrencies on the Stellar Network, while FIAT issuers tokenize traditional money. 		false
.checkouts{} object An object containing information about this issuer's checkout eligibility on the COINQVEST platform. false
.enabled boolean Indicates whether this issuer's assets can be used when receiving customer payments during checkout. false
.min string This is the minimum payment amount during checkout. false
.max string This is the maximum payment amount during checkout. If null then there is no upper bound. true
.feeFixed string This is the issuer's fixed fee for payments processed during checkout. Typically 0. false
.feePercent string This is the issuer's percentage fee for payments processed during checkout. Typically 0. false
.withdrawals{} object An object containing information about this issuer's withdrawal eligibility on the COINQVEST platform. false
.enabled boolean Indicates whether this issuer's asset can be used for withdrawals from COINQVEST. false
.min string This is the minimum withdrawal amount for this issuer's asset. false
.max string This is the maximum withdrawal amount for this issuer's asset. If null then there is no upper bound. true
.feeFixed string This is the issuer's fixed fee, imposed during withdrawals from COINQVEST. false
.feePercent string This is the issuer's percentage fee, imposed during withdrawals from COINQVEST. false
.blockchain{} object Contains details about the related blockchain if this is a CRYPTO anchor. Otherwise null. true
.nativeAssetCode string(3) The blockchains native asset code. false
.name string The blockchain's name in plain text. For the humans among us. false
.path string Invoke this endpoint to obtain more information about the blockchain. See GET /blockchain. false
.fiatCurrency{} object Contains details about the related fiat currency if this is an anchor of type FIAT. Otherwise null true
.assetCode string(12) The unique id of the related fiat currency. false
.name string The related fiat currency's name in plain text. false
.path string Invoke this endpoint to obtain more information about this fiat currency. See GET /fiat-currency. false
.asset{} object Contains details about the related asset issued by this entity. true
.id string(12) The unique id of the related asset. This matches the asset issuer's id. false
.path string Invoke this endpoint to obtain more information about the related asset. See GET /asset. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/asset-issuerprotected

Retrieves asset issuer details based on the given id.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/asset-issuer?id=XXX'

Request Params

Key Type Description Default Mandatory
id string The anchor id in the form of an asset id on the Stellar Network, e.g. XLM:NATIVE or BTC:GABC...WXYZ - mandatory

Success Response application/json

200 OK 
{
      "assetIssuer":{
         "id":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
         "name":"Tempo",
         "domain":"tempo.eu.com",
         "address":"TEMPO France S.A.S., 89, Boulevard de Magenta, 75010 Paris, France",
         "country":"FR",
         "type":"FIAT",
         "checkouts":{
            "enabled":false,
            "min":"0.0000000",
            "max":null,
            "feeFixed":"0.0000000",
            "feePercent":"0.0000000"
         },
         "withdrawals":{
            "enabled":true,
            "min":"10.0000000",
            "max":null,
            "feeFixed":"1.9800000",
            "feePercent":"0.0000000"
         },
         "asset":{
            "id":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "name":"Euro",
            "path":"\/api\/v1\/asset?id=EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S"
         },
         "blockchain":null,
         "fiatCurrency":{
            "assetCode":"EUR",
            "name":"Euro",
            "path":"\/api\/v1\/fiat-currency?assetCode=EUR"
         }
      }
}

Success Response Attributes

Name Type Description Nullable
.assetIssuer{} array An object containing information about the asset issuer. false
.id string The unique id of this anchor. false
.name string The issuer's name in plain text. false
.domain string The issuer's internet domain. This is a good place to start your due diligence. false
.address string The issuer's company name and registered address. false
.country string The issuer's country of origin. false
.type string An asset issuer can be of type CRYPTO or FIAT.

CRYPTO issuers tokenize cryptocurrencies on the Stellar Network, while FIAT issuers tokenize traditional money. 		false
.checkouts{} object An object containing information about this issuer's checkout eligibility on the COINQVEST platform. false
.enabled boolean Indicates whether this issuer's assets can be used when receiving customer payments during checkout. false
.min string This is the minimum payment amount during checkout. false
.max string This is the maximum payment amount during checkout. If null then there is no upper bound. true
.feeFixed string This is the issuer's fixed fee for payments processed during checkout. Typically 0. false
.feePercent string This is the issuer's percentage fee for payments processed during checkout. Typically 0. false
.withdrawals{} object An object containing information about this issuer's withdrawal eligibility on the COINQVEST platform. false
.enabled boolean Indicates whether this issuer's asset can be used for withdrawals from COINQVEST. false
.min string This is the minimum withdrawal amount for this issuer's asset. false
.max string This is the maximum withdrawal amount for this issuer's asset. If null then there is no upper bound. true
.feeFixed string This is the issuer's fixed fee, imposed during withdrawals from COINQVEST. false
.feePercent string This is the issuer's percentage fee, imposed during withdrawals from COINQVEST. false
.blockchain{} object Contains details about the related blockchain if this is a CRYPTO anchor. Otherwise null. true
.nativeAssetCode string(3) The blockchains native asset code. false
.name string The blockchain's name in plain text. For the humans among us. false
.path string Invoke this endpoint to obtain more information about the blockchain. See GET /blockchain. false
.fiatCurrency{} object Contains details about the related fiat currency if this is an anchor of type FIAT. Otherwise null true
.assetCode string(12) The unique id of the related fiat currency. false
.name string The related fiat currency's name in plain text. false
.path string Invoke this endpoint to obtain more information about this fiat currency. See GET /fiat-currency. false
.asset{} object Contains details about the related asset issued by this entity. true
.id string(12) The unique id of the related asset. This matches the asset issuer's id. false
.path string Invoke this endpoint to obtain more information about the related asset. See GET /asset. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/assetsprotected

Returns a list of assets supported by the COINQVEST platform. Assets represent a crypto or fiat currency and exist as tokens on the Stellar Network.

Whenever you receive a payment, funds are tokenized on the Stellar Network and credited to your account. When you make a withdrawal, funds are de-tokenized and converted back into their true form, e.g. money in your bank account or funds on the native Bitcoin blockchain.

View Assets in UI

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/assets'

Success Response application/json

200 OK 
{
   "assets":[
      {
         "id":"XLM:NATIVE",
         "code":"XLM",
         "name":"Lumens",
         "type":"CRYPTO",
         "issuer":{
            "id":"XLM:NATIVE",
            "name":"Stellar Development Foundation (SDF)",
            "path":"\/api\/v1\/asset-issuer?id=XLM:NATIVE"
         }
      },
      {
         "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "code":"USD",
         "name":"US Dollar",
         "type":"FIAT",
         "issuer":{
            "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "name":"AnchorUSD",
            "path":"\/api\/v1\/asset-issuer?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      },
      {
         "id":"XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
         "code":"XRP",
         "name":"Ripple",
         "type":"CRYPTO",
         "issuer":{
            "id":"XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
            "name":"Stellarport",
            "path":"\/api\/v1\/asset-issuer?id=XRP:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5"
         }
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.assets[] array A list of assets on the COINQVEST platform. false
.id string(12) The asset id on the Stellar Network. false
.code string The asset code. false
.name string The asset's name. false
.type string An asset can be of type CRYPTO or FIAT. false
.issuer{} object Contains additional information about the asset issuer. true
.id string The unique id of the corresponding asset issuer. This matches the asset id. false
.name string The name of the corresponding asset issuer. false
.path string Invoke this endpoint to obtain more information about this issuer. See GET /asset-issuer. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/assetprotected

Retrieves asset details based on the given id.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/asset?id=XXX'

Request Params

Key Type Description Default Mandatory
id string The unique identifier of the selected asset, e.g. XLM:NATIVE or BTC:GABC...WXYZ - mandatory

Success Response application/json

200 OK 
{
   "asset":{
      "id":"ETH:GBETHKBL5TCUTQ3JPDIYOZ5RDARTMHMEKIO2QZQ7IOZ4YC5XV3C2IKYU",
      "code":"ETH",
      "name":"Ether",
      "type":"CRYPTO",
      "issuer":{
         "id":"ETH:GBETHKBL5TCUTQ3JPDIYOZ5RDARTMHMEKIO2QZQ7IOZ4YC5XV3C2IKYU",
         "name":"Firefly",
         "path":"\/api\/v1\/asset-issuer?id=ETH:GBETHKBL5TCUTQ3JPDIYOZ5RDARTMHMEKIO2QZQ7IOZ4YC5XV3C2IKYU"
      }
   }
}

Success Response Attributes

Name Type Description Nullable
.asset{} array An object containing information about the asset. false
.id string(12) The asset id on the Stellar Network. false
.code string The asset code. false
.name string The asset's name. false
.type string An asset can be of type CRYPTO or FIAT. false
.issuer{} object Contains additional information about the asset issuer. true
.id string The unique id of the corresponding asset issuer. This matches the asset id. false
.name string The name of the corresponding asset issuer. false
.path string Invoke this endpoint to obtain more information about this issuer. See GET /asset-issuer. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/fiat-currenciesprotected

Returns a list of fiat currencies supported by the COINQVEST platform. These are typically used as settlement currency and during withdrawals.

View Fiat Currencies in UI

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/fiat-currencies'

Success Response application/json

200 OK 
{
   "fiatCurrencies":[
      {
         "name":"US Dollar",
         "assetCode":"USD",
         "assetName":"US Dollar",
         "minChargeAmount":"0.01",
         "assetIssuers":[
            {
               "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "path":"\/api\/v1\/asset-issuer?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "name":"AnchorUSD",
               "default":true
            }
         ]
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.fiatCurrencies[] array A list of supported fiat currencies. false
.name string Name of the fiat currency. false
.assetCode string Corresponding asset code. This is also the fiat currency's unique identifier. false
.assetName string Name of the fiat currency's native asset, e.g. US Dollar. false
.minChargeAmount numeric Specifies the lowest possible payment amount in COINQVEST checkouts. false
.assetIssuers[] array A list of objects, representing asset issuers for this blockchain. false
.id string The asset issuer's unique id. false
.name string The asset issuer's name in plain text. false
.path string Invoke this endpoint to obtain more information about this asset issuer. See GET /asset-issuer. false
.default boolean Indicates whether this is the default asset issuer for payments originating from this blockchain. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/fiat-currencyprotected

Retrieves a fiat currency object based on the given assetCode.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/fiat-currency?assetCode=XXX'

Request Params

Key Type Description Default Mandatory
id string The unique assetCode of the selected fiat currency, e.g. USD, EUR or HKD. Given by GET /fiat-currencies. - mandatory

Success Response application/json

200 OK 
{
   "fiatCurrency":[
      {
         "name":"US Dollar",
         "assetCode":"USD",
         "assetName":"US Dollar",
         "minChargeAmount":"0.01",
         "assetIssuers":[
            {
               "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "path":"\/api\/v1\/asset-issuer?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "name":"AnchorUSD",
               "default":true
            }
         ]
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.fiatCurrency{} object An object containing information about this fiat currency. false
.name string Name of the fiat currency. false
.assetCode string Corresponding asset code. This is also the fiat currency's unique identifier. false
.assetName string Name of the fiat currency's native asset, e.g. US Dollar. false
.minChargeAmount numeric Specifies the lowest possible payment amount in COINQVEST checkouts. false
.assetIssuers[] array A list of objects, representing asset issuers for this blockchain. false
.id string The asset issuer's unique id. false
.name string The asset issuer's name in plain text. false
.path string Invoke this endpoint to obtain more information about this asset issuer. See GET /asset-issuer. false
.default boolean Indicates whether this is the default asset issuer for payments originating from this blockchain. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/blockchainsprotected

Returns a list of blockchains supported by the COINQVEST platform.

View Blockchains in UI

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/blockchains'

Success Response application/json

200 OK 
{
   "blockchains":[
      {
         "name":"Stellar Network",
         "nativeAssetCode":"XLM",
         "nativeAssetName":"Lumens",
         "minChargeAmount":"0.0001",
         "assetIssuers":[
            {
               "id":"XLM:NATIVE",
               "path":"\/api\/v1\/asset-issuer?id=XLM:NATIVE",
               "name":"Stellar Development Foundation (SDF)",
               "default":true
            }
         ]
      },
      {
         "name":"Ethereum",
         "nativeAssetCode":"ETH",
         "nativeAssetName":"Ether",
         "minChargeAmount":"0.05",
         "assetIssuers":[
            {
               "id":"ETH:GBETHKBL5TCUTQ3JPDIYOZ5RDARTMHMEKIO2QZQ7IOZ4YC5XV3C2IKYU",
               "path":"\/api\/v1\/asset-issuer?id=ETH:GBETHKBL5TCUTQ3JPDIYOZ5RDARTMHMEKIO2QZQ7IOZ4YC5XV3C2IKYU",
               "name":"Firefly",
               "default":false
            },
            {
               "id":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
               "path":"\/api\/v1\/asset-issuer?id=ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
               "name":"Papaya",
               "default":false
            },
            {
               "id":"ETH:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
               "path":"\/api\/v1\/asset-issuer?id=ETH:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
               "name":"Stellarport",
               "default":true
            }
         ]
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.blockchains[] array A list of supported blockchains. false
.name string Name of the blockchain. false
.nativeAssetCode string Asset code of the blockchain's native asset, e.g. XLM or BTC. This is also the blockchain's unique identifier. false
.nativeAssetName string Name of the blockchain's native asset, e.g. Lumens. false
.minChargeAmount numeric Specifies the lowest possible payment amount in COINQVEST checkouts. false
.assetIssuers[] array A list of objects, representing asset issuers for this blockchain. false
.id string The asset issuer's unique id. false
.name string The asset issuer's name in plain text. false
.path string Invoke this endpoint to obtain more information about this asset issuer. See GET /asset-issuer. false
.default boolean Indicates whether this is the default asset issuer for payments originating from this blockchain. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/blockchainprotected

Retrieves information about a blockchain object based on the given assetCode.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/blockchain?assetCode=XXX'

Request Params

Key Type Description Default Mandatory
assetCode string The nativeAssetCode of the selected blockchain, e.g. XLM, BTC, ETH, LTC or XRP. Given by GET /blockchains - mandatory

Success Response application/json

200 OK 
{
   "blockchain":[
      {
         "name":"Bitcoin",
         "nativeAssetCode":"BTC",
         "nativeAssetName":"Bitcoin",
         "minChargeAmount":"0.005",
         "assetIssuers":[
            {
               "id":"BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH",
               "path":"\/api\/v1\/asset-issuer?id=BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH",
               "name":"NaoBTC",
               "default":false
            },
            {
               "id":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
               "path":"\/api\/v1\/asset-issuer?id=BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
               "name":"Papaya",
               "default":false
            },
            {
               "id":"BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
               "path":"\/api\/v1\/asset-issuer?id=BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5",
               "name":"Stellarport",
               "default":true
            }
         ]
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.blockchain{} object An object containing information about this blockchain. false
.name string Name of the blockchain. false
.nativeAssetCode string Asset code of the blockchain's native asset, e.g. XLM or BTC. This is also the blockchain's unique identifier. false
.nativeAssetName string Name of the blockchain's native asset, e.g. Lumens. false
.minChargeAmount numeric Specifies the lowest possible payment amount in COINQVEST checkouts. false
.assetIssuers[] array A list of objects, representing asset issuers for this blockchain. false
.id string The asset issuer's unique id. false
.name string The asset issuer's name in plain text. false
.path string Invoke this endpoint to obtain more information about this asset issuer. See GET /asset-issuer. false
.default boolean Indicates whether this is the default asset issuer for payments originating from this blockchain. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/pingpublic

Sends a ping request to the API. This endpoint is a good starting place in trying to initially connect to the COINQVEST API.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/ping'

Success Response application/json

200 OK 
{
    "success":true
}

Success Response Attributes

Name Type Description Nullable
success boolean Indicates the request was processed successfully. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/timepublic

Returns a Unix timestamp with the current COINQVEST server time. Use this endpoint when generating the Digest-Auth signature for authentication if you feel time the between your server and the COINQVEST server is askew.

Request

cURL 
curl 'https://www.coinqvest.com/api/v1/time'

Success Response application/json

200 OK 
{
    "time":1525898643
}

Success Response Attributes

Name Type Description Nullable
time integer Unix timestamp with COINQVEST server time. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/auth-testprotected

Similar to the GET /ping endpoint except this requires authentication.

A good starting place to test your Basic-Auth or (recommended) Digest-Auth implementation. The below example demonstrates a Digest-Auth request. This endpoint accepts Basic-Auth but it is discouraged for production environments. To use Basic-Auth, replace the X-Digest headers with the X-Basic one (see Authentication).

Request

cURL 
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
X-Digest-Signature string Unique Digest-Auth signature (see authentication)
X-Digest-Timestamp integer Current Unix timestamp (also see GET /time).

Success Response application/json

200 OK 
{
    "success":true
}

Success Response Attributes

Name Type Description Nullable
success boolean Indicates the request was processed successfully. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/customersprotected

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

Request

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

Request Params

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

Success Response application/json

200 OK 
{
   "count":1,
   "limit":"250",
   "offset":"0",
   "customers":[
      {
         "id":"fd4f47a50c7f",
         "email":"john@doe.com",
         "firstname":"John",
         "lastname":"Doe",
         "name":"John Doe",
         "company":"ACME Inc.",
         "adr1":"810 Beach St",
         "adr2":"Finance Dept",
         "zip":"CA 94133",
         "city":"San Francisco",
         "countrycode":"US",
         "country":"United States",
         "phonenumber":"+14156226819",
         "taxid":"US1234567890",
         "note":"Always pays on time. Never late.",
         "meta":{
            "reference":123
         },
         "inserttime":"2018-12-10T16:16:18+00:00",
         "updatetime":"2018-12-11T17:34:09+00:00",
         "invoiceable":true
      }
   ]
}

Success Response Attributes

Name Type Description Nullable
.count integer The total number of customers 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
.customers[] array A list of customer objects. false
.id string(12) Unique identifier. false
.email string The customer's email address. false
.firstname string The customer's first name. true
.lastname string The customer's last name. true
.name string The customer's first name and last name conveniently concatenated into a single attribute. true
.company string The customer's company name. true
.adr1 string The customer's first address line. true
.adr2 string The customer's second address line. true
.zip string The customer's zip code. true
.city string The customer's city. true
.countrycode string(2) The customer's country in two character ISO format. true
.country string The customer's country in plain English. true
.phonenumber string The customer's phone number in international standard format (leading plus). true
.taxid string The customer's tax id. true
.note string An arbitrary note associated with the customer. true
.meta string An arbitrary JSON object associated with the customer. true
.inserttime timestamp W3C formatted time stamp with time zone (UTC) specifying when the customer was created. true
.updatetime timestamp W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated. true
.invoiceable boolean Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, adr1, zip, city, countrycode and either firstname and lastname or company. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

POST/customerprotected

Creates a customer object, which can be associated with checkouts, payments, and invoices. If a customer with the given email address already exists an update is performed. This endpoint can therefore be used as an alternative to PUT /customer.

Checkouts associated with a customer generate more transaction details, help with your accounting, and can automatically generate invoices for your customer and yourself.

The Merchant API implements endpoints to create (POST /customer), delete (DELETE /customer), and update (PUT /customer) your customers. You can also retrieve individual customers (GET /customer) as well as fetch a list of all your customers (GET /customers).

Example Request

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

Where payload.json is a JSON object.

Example Payload

application/json 
{
   "customer":{
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Request Params (POST)

PRO Tip

To make a customer invoiceable you need to provide a name or a company as well as a complete address with adr1, zip, city, and countrycode at a minimum.

Key Type Description Nullable Mandatory
customer{} object An object containing information about your customer. false mandatory
.email string The customer's email address. If a customer with the given email address already exists an update of below records is performed. false mandatory
.firstname string The customer's first name. true optional
.lastname string The customer's last name. true optional
.company string The customer's company name. true optional
.adr1 string The customer's first address line. Must be provided alongside zip, city, and countrycode true optional
.adr2 string The customer's second address line. true optional
.zip string The customer's zip code. Must be provided alongside adr1, city, and countrycode true optional
.city string The customer's city. Must be provided alongside adr1, zip, and countrycode true optional
.countrycode string The customer's country as two character ISO code. Must be provided alongside adr1, zip, and city true optional
.phonenumber string The customer's phone number. true optional
.taxid string The customer's tax id. Useful for accounting and invoicing purposes. true optional
.note string An arbitrary note associated with the customer. true optional
.meta object An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use. true optional

Success Response application/json

200 OK 
{
    "customerId":"fd4f47a50c7f"
}

Success Response Attributes

Name Type Description Nullable
.customerId string(12) Unique identifier of the new customer object. Store this persistently for later use. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

GET/customerprotected

Retrieves details of a given customer.

Request

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

Request Params

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

Success Response application/json

200 OK 
{
   "customer":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "name":"John Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "country":"United States",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      },
      "inserttime":"2018-12-10T16:16:18+00:00",
      "updatetime":"2018-12-11T17:34:09+00:00",
      "invoiceable":true
   }
}

Success Response Attributes

Name Type Description Nullable
.customer{} array An object with details about the customer. false
.id string(12) Unique identifier. false
.email string The customer's email address. false
.firstname string The customer's first name. true
.lastname string The customer's last name. true
.name string The customer's first name and last name conveniently concatenated into a single attribute. true
.company string The customer's company name. true
.adr1 string The customer's first address line. true
.adr2 string The customer's second address line. true
.zip string The customer's zip code. true
.city string The customer's city. true
.countrycode string(2) The customer's country in two character ISO format. true
.country string The customer's country in plain English. true
.phonenumber string The customer's phone number in international standard format (leading plus). true
.taxid string The customer's tax id. true
.note string An arbitrary note associated with the customer. true
.meta string An arbitrary JSON object associated with the customer. true
.inserttime timestamp W3C formatted time stamp with time zone (UTC) specifying when the customer was created. true
.updatetime timestamp W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated. true
.invoiceable boolean Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, adr1, zip, city, countrycode and either firstname and lastname or company. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

PUT/customerprotected

Updates an existing customer object.

All attributes besides id and email are optional. You can submit a partial customer object including the fields you wish to update only. To unset an attribute set its value to null.

Example Request

cURL 
curl -X PUT https://www.coinqvest.com/api/v1/customer \
-d "@payload.json"

Where payload.json is a JSON object.

Example Payload

application/json 
{
   "customer":{
      "id":"fd4f47a50c7f",
      "email":"john@doe.com",
      "firstname":"John",
      "lastname":"Doe",
      "company":"ACME Inc.",
      "adr1":"810 Beach St",
      "adr2":"Finance Dept",
      "zip":"CA 94133",
      "city":"San Francisco",
      "countrycode":"US",
      "phonenumber":"+14156226819",
      "taxid":"US1234567890",
      "note":"Always pays on time. Never late.",
      "meta":{
         "reference":123
      }
   }
}

Request Params (PUT)

PRO Tip

To make a customer invoiceable you need to provide a name or a company as well as a complete address with adr1, zip, city, and countrycode at a minimum.

Key Type Description Nullable Mandatory
customer{} object The customer object to be included in the request. false mandatory
.id string(12) The customer's unique identifier as given by POST /customer. false mandatory
.email string The customer's email address. false optional
.firstname string The customer's first name. true optional
.lastname string The customer's last name. true optional
.company string The customer's company name. true optional
.adr1 string The customer's first address line. Must be provided alongside zip, city, and countrycode true optional
.adr2 string The customer's second address line. true optional
.zip string The customer's zip code. Must be provided alongside adr1, city, and countrycode true optional
.city string The customer's city. Must be provided alongside adr1, zip, and countrycode true optional
.countrycode string The customer's country as two character ISO code. Must be provided alongside adr1, zip, and city true optional
.phonenumber string The customer's phone number. true optional
.taxid string The customer's tax id. Useful for accounting and invoicing purposes. true optional
.note string An arbitrary note associated with the customer. true optional
.meta object An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use. true optional

Success Response application/json

200 OK 
{
    "success": true
}

Success Response Attributes

Name Type Description Nullable
success boolean Indicates that the request was processed successfully false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

DELETE/customerprotected

Deletes an existing customer object.

Example Request

cURL 
curl -X DELETE https://www.coinqvest.com/api/v1/customer \
-d "@payload.json"

Where payload.json is a JSON object.

Example Payload

application/json 
{
    "id":"fd4f47a50c7f"
}

Request Params

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

Success Response application/json

200 OK 
{
    "success":true
}

Success Response Attributes

Name Type Description Nullable
success boolean Indicates that request was processed successfully. false

Error Response application/json

4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

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

WEBHOOKpayment

Webhooks are responsible for posting information back to your server when certain events happen. They are sometimes called "callbacks". This webhook is invoked when a payment by your customer is successful and your account is credited.

You specify the webhook endpoint on your server in the initial call to POST /checkout or POST /checkout/hosted.

Once the checkout has been triggered, we start monitoring the payment blockchain for your customers payment. When we detect the payment and credit your account, we send an HTTP POST request to your server as specified below. Using the webhook, you can extract the payment information from the HTTP request body and mark the sale as completed in your system.

If you don't want to listen for webhooks on your server you can alternatively poll GET /checkout to obtain equivalent information as given by this webhook.

Webhook Payload Headers

HTTP Request Headers 
POST / HTTP/1.1
User-Agent: COINQVEST Webhook Engine 1.0.0
Host: www.merchant.com
Accept: */*
Content-Type: application/json
Connection: close
X-Webhook-Auth: 06b7ff792a30a172c51c163f666dd6908d85fdda78451b36de9f3f8e985412be
Content-Length: 532

PRO Tip

To add additional security to your endpoint and prevent spoofing, we recommend to parse the X-Webhook-Auth header and verify its value.

You can verify the request was sent by COINQVEST by creating a hash hash('sha256', YOUR_API_SECRET . WEBHOOK_REQUEST_BODY) (where the . symbol represents concatenation) and matching it against the header value.

Webhook Payload Body

HTTP Request Body 
{
  "id": "cb69affabf53",
  "type": "PAYMENT",
  "state":"RESOLVED",
  "timestamp": "2020-03-02T16:04:50+02:00",
  "creditAssetCode": "USD",
  "creditAssetIssuer": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
  "creditAmount": "0.0100000",
  "sourceAssetCode": "XLM",
  "sourceAssetIssuer": "XLM:NATIVE",
  "sourceAmount": "0.1728238",
  "sourceBlockchain": "XLM",
  "sourceAccount": "GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
  "sourceTxId": "0235acde7bb5c14536d534f816a69ccb66d4d4d95e8bbd5ca7b9c81c85790f7a",
  "customerId": "1acf0d0b10bd",
  "checkoutId": "87508a7a78c3"
}

IMPORTANT

Your endpoint should always invoke GET /checkout and inspect the state field in its response when processing a payment webhook. It is safest to credit your customer only when you confirm the state of the related checkout is COMPLETED.

This way, you protect yourself from unlikely situations when you receive a WEBHOOK payment for partial payments, underpaid amounts, or other exceptions.

Send 200 OK

Your server needs to respond with a status code of 200 in the HTTP response when it successfully parses the webhook payload. Otherwise, our system will keep sending webhook requests for up to 48 hours in increasing intervals until we detect a 200 status code.

PRO Tip

You can inspect webhook requests sent by COINQVEST along with your associated server responses in your .

Webhook Payload Attributes

Name Type Description Nullable
.id string(12) Unique identifier of this payment. false
.type string The payment type. Currently the only existing value is PAYMENT, which represents a payment sent by a customer. false
.state string RESOLVED or UNRESOLVED. Indicates whether this payment has been resolved and credited to your account. A payment is flagged as unresolved if the payment amount was below or above what was expected or another exception occurred. false
.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the payment was made. false
.creditAssetCode string The asset code credited to your account (e.g USD). false
.creditAssetIssuer string Identifier of the issuer of the asset credited to your account, see GET /asset-issuers. false
.creditAmount numeric The amount credited to your account. false
.sourceAssetCode string This field represents the asset used by your customer to make this payment (e.g. BTC, XLM, ETH, LTC, XRP). false
.sourceAssetIssuer string This field indicates the entity that processed this payment on your behalf, see GET /asset-issuers. false
.sourceAmount numeric This field displays the exact amount paid by your customer to make this payment. false
.sourceBlockchain string(3) References the blockchain from which this payment originated, see GET /blockchains. false
.sourceAccount string Specifies the blockchain account from which the payment originated. This account lives on the blockchain given in sourceBlockchain. true
.sourceTxId string Specifies the transaction id related to this payment. This transaction lives on the blockchain given in sourceBlockchain. true
.customerId string(12) References the customer related to this payment, see GET /customer. true
.checkoutId string(12) References the checkout related to this payment, see GET /checkout. false
© COINQVEST Ltd. 2018-2020 · Terms of Service · Privacy Policy · KYC/AML Policy · Anti-Fraud Policy · Data Processing © COINQVEST Ltd. 2018-2020 · Terms of Service · Privacy Policy · KYC/AML Policy · Anti-Fraud Policy · Data Processing