Getting Started

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

The COINQVEST API connects your online business, e-commerce store, or web application with cryptocurrency payments. This documentation provides information on how to interact with the API.

Using the COINQVEST API

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

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

Creating Hosted Checkouts

Hosted checkouts are the simplest form of getting paid using the COINQVEST platform. The POST /checkout/hosted API endpoint creates and returns a payment URL for a dynamic checkout page on COINQVEST servers. Your application retrieves the checkout URL and directs your customer to the hosted checkout page to complete payment.

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

Example Request

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

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

Example Charge (minimal)

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

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

Example Response (application/json)

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

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

Receiving Payments

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

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

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

Example Webhook (application/json)

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

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

Creating Self-Hosted Checkouts

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

Software Development Kits

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

PHP
Official COINQVEST Merchant SDK for PHP

Ruby
Official COINQVEST Merchant SDK for Ruby

NodeJS
Official COINQVEST Merchant SDK for NodeJS

Developer Guides

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

COINQVEST Developer Guide
Cryptocurrency Payments with COINQVEST Merchant APIs

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

E-Commerce Integrations

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

Wordpress
Official COINQVEST Plugin for Wordpress

WooCommerce
Official COINQVEST Plugin for WooCommerce

Shopify
Official COINQVEST Integration for Shopify

Magento
Official COINQVEST Extension for Magento 2

Not a Developer?

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

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

Authentication

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

API Key and Secret

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

Digest-Auth

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

Request

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

Request Headers

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

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

X-Digest-Signature Components

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

Code Example (PHP)

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

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

Code Example (Ruby)

require 'openssl'

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

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

Code Example (NodeJS)

require('crypto');

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

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

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

Basic-Auth

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

Request

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

Request Headers

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

Code Example

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

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

IP Address Whitelisting

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

Software Development Kits (SDKs)

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

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

PHP
Official COINQVEST Merchant SDK for PHP

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

View on GitHub README.md

Ruby
Official COINQVEST Merchant SDK for Ruby

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

View on GitHub README.md

NodeJS
Official COINQVEST Merchant SDK for NodeJS

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

View on GitHub README.md

POST/checkoutprotected

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

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

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

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

Example Request

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

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

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "checkoutLanguage":"en",
   "webhook":"https://www.merchant.com/path/for/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"
   },
   "pageSettings":{
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   }
}

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`. 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`. 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
`.checkoutLanguage`	string	This specifies the language on your checkout page. For example, if you specify `de` as checkout language, your customer will be presented with a hosted checkout page in German language. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `pl` `fa` Query supported languages with endpoint `GET /languages`.	en	optional
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in webhook concepts.	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 checkout-completed`. 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
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional

Success Response application/json

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

Success Response Attributes

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

Next Step

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

Error Response application/json

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

Error Response Params

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

POST/checkout/commitprotected

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

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

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

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

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

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

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

Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params

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

Example Success Response for ETH application/json

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

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

Example Success Response for XLM application/json

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

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

Example Success Response for XRP application/json

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

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

Success Response Attributes

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

Next Step

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

Error Response application/json

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

Error Response Params

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

POST/checkout/hostedprotected

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

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

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

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

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

Example Request

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

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

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "checkoutLanguage":"en",
   "webhook":"https://www.merchant.com/path/for/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"
   },
   "pageSettings":{
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   }
}

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`. 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`. 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
`.checkoutLanguage`	string	This specifies the language on your checkout page. For example, if you specify `de` as checkout language, your customer will be presented with a hosted checkout page in German language. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `pl` `fa` Query supported languages with endpoint `GET /languages`.	en	optional
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in webhook concepts.	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 checkout-completed`. 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
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

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

GET/checkoutprotected

Retrieves information about a given checkout.

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

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

Request

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

Request Params

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

Success Response application/json

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

Success Response Attributes

Name	Type	Description	Nullable
`.checkout{}`	array	The checkout object.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset (`GET /assets`) you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. Is `null` when the customer did not select a payment currency yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.settlementAmountFeePaid`	string	The processing fee collected by COINQVEST.	false
`.sourceAssetId`	string	The payment asset (`GET /assets`) used for this checkout. Indicates the blockchain and payment method selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchain`	string	The payment blockchain (`GET /blockchains`) selected by the customer in English plain text. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be either `ORIGIN` (blockchain payment transaction initiated by customer), `TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), or `SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `CONVERSION_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Error Response application/json

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

Error Response Params

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

GET/checkoutsprotected

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

Request

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

Request Params

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

Success Response application/json

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

Success Response Attributes

Name	Type	Description	Nullable
`.count`	integer	The total number of checkout URLs in existence for this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.checkouts[]`	array	A list of checkout objects.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset (`GET /assets`) you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. Is `null` when the customer did not select a payment currency yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.settlementAmountFeePaid`	string	The processing fee collected by COINQVEST.	false
`.sourceAssetId`	string	The payment asset (`GET /assets`) used for this checkout. Indicates the blockchain and payment method selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchain`	string	The payment blockchain (`GET /blockchains`) selected by the customer in English plain text. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be either `ORIGIN` (blockchain payment transaction initiated by customer), `TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), or `SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `CONVERSION_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Error Response application/json

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

Error Response Params

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

GET/walletsprotected

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

Request

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

Success Response application/json

{
   "wallets":[
      {
         "assetCode":"XLM",
         "type":"CRYPTO",
         "balance":"950.9263842",
         "assets":[
            {
               "id":"XLM:NATIVE",
               "issuerName":"Stellar Development Foundation (SDF)",
               "issuerDomain":"stellar.org",
               "balance":"950.9263842",
               "path":"/api/v1/asset?id=XLM:NATIVE"
            }
         ]
      },
      {
         "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`	string	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

{
    "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 '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

{
   "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`	string	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

{
    "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 -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)

{
   "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)

{
   "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)

{
   "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)

{
   "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)

{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"NGN",
   "targetAccount":{
      "nuban":"4791494548",
      "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 4791494548 at FirstBank.

Example Payload (Withdrawal to an BRL Bank Account via PIX)

{
   "sourceAsset":"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP",
   "sourceAmount":10000,
   "targetNetwork":"BRL",
   "targetAccount":{
      "pixKey":"email@example.org",
      "taxId":"528.963.222-01"
   }
}

In above example 10,000 BRL are withdrawn from your COINQVEST wallet, converted into Brazilian Real (BRL) and sent to the bank account associated with the PIX key email@example.org.

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 (e.g.) 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 ARS

`cbu`	The recipient's bank account number (CBU or CVU). This CBU must match the account information verified on COINQVEST.
`cuitPersonal`	Your personal tax id associated with the target CBU and your COINQVEST account.
`cuitCompany`	Business accounts need to provide an additional CUIT, issued towards the company that owns the bank account and is verified on COINQVEST.

Field Attributes for withdrawals to BRL

`pixKey`	The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key.
`taxId`	The recipient's tax id. CNPJ format (`00.000.000/0000-00`) for corporate identities or CPF format (`000.000.000-00`) for individuals.

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. Can be one of the below. `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

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "fee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":null,
      "targetAccount":{
         "nuban":"4791494548",
         "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 string 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 string This field displays the guaranteed amount received in the target account. false

.fee string This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account is debited the equivalent of the sum of
fee + 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 ARS

cbu The recipient's bank account number (CBU).

Field Attributes for withdrawals to BRL

`accountNumber`	The recipient's bank account number.
`branchNumber`	The recipient bank's branch number.
`bankNumber`	The recipient bank's financial institution number (3 digits).

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

{
    "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.

Important: Please note that this endpoint requires a long timeout setting (we recommend 120 seconds) as it waits for blockchain confirmation before returning a response.

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 and a blockchain transaction id is returned.

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

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

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "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":"4791494548",
         "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 -X POST 'https://www.coinqvest.com/api/v1/withdrawal/commit'
    -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

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

{
   "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":"4791494548",
         "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 string 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 string This field displays the amount received in the target account. false

.fee string 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
fee + 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 ARS

cbu The recipient's bank account number (CBU).

Field Attributes for withdrawals to BRL

`accountNumber`	The recipient's bank account number.
`branchNumber`	The recipient bank's branch number.
`bankNumber`	The recipient bank's financial institution number (3 digits).

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

{
    "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 '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

{
   "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",
      "fee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
      "targetAccount":{
         "nuban":"4791494548",
         "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 debit 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