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

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

{
   "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 API Request Logs.

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

Read our Guide

To learn more about creating checkouts and getting paid using the COINQVEST Merchant API, read our developers guide, Mastering Cryptocurrency Checkouts.

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 '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` requests. Set `null` for `GET` requests.

Code Example

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

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

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

Concepts

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

View Integrations in UI

Software Development Kits (SDKs)

We're continuously updating convenient software development kits (SDKs) to make your life as easy as possible.

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

PHP

include('CQMerchantClient.class.php');

$client = new CQMerchantClient(
    'YOUR-API-KEY',
    'YOUR-API-SECRET',
    '/var/log/coinqvest.log'
);

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

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

Example Payload (Full)

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

Request Params (POST)

PRO Tip #1 Auto-Conversion

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

PRO Tip #2 Customer Object Relation

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

PRO Tip #3 Total Amount Formula

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

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Us the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The 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.	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 is one of the most important key settings in COINQVEST checkouts. It specifies the currency you want to have credited to your account 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 cryptocurrency your customer paid with. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in AnchorUSD tokens, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in `WEBHOOK payment`.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, Litecoin or XRP Ledger networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK payment`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional

Success Response application/json

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

Success Response Attributes

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

Next Step

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

Error Response application/json

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

Error Response Params

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

POST/checkout/commitprotected

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

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

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

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

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

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

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

Request

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

Where payload.json is a JSON object.

Example Payload

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

Request Params

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

Example Success Response for ETH application/json

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

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

Example Success Response for XLM application/json

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

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

Example Success Response for XRP application/json

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

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

Success Response Attributes

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

Next Step

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

Error Response application/json

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

Error Response Params

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

POST/checkout/hostedprotected

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

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

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

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

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

Example Request

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

Where payload.json is a JSON object.

Example Payload (Minimal)

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

Explanation of Above Payload Configuration

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

Example Payload (Full)

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

Request Params (POST)

PRO Tip #1 Auto-Conversion

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

PRO Tip #2 Customer Object Relation

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

PRO Tip #3 Total Amount Formula

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

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Us the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The 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.	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 is one of the most important key settings in COINQVEST checkouts. It specifies the currency you want to have credited to your account 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 cryptocurrency your customer paid with. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. Alternative expert setting: You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in AnchorUSD tokens, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.webhook`	string	A webhook URL on your server that listens for payment events as specified in `WEBHOOK payment`.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, Litecoin or XRP Ledger networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK payment`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional

Success Response application/json

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

Success Response Attributes

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

Error Response application/json

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

Error Response Params

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

GET/checkoutprotected

Retrieves information about a given checkout.

The response of this endpoint contains 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 '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":"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_CHARGE`	Charge has been created and is awaiting customer payment.
`IN_PROGRESS`	Payment has been detected on the blockchain and is awaiting confirmation.
`COMPLETED`	Payment has been confirmed and deposited to your account.
`EXPIRED`	Charge has expired without a payment.
`UNRESOLVED_GENERIC`	Payment has diverged from what was expected or a generic error occurred.
`UNRESOLVED_UNDERPAID`	Payment amount was less than expected.
`UNRESOLVED_OVERPAID`	Payment amount was more than expected.
`DELAYED_COMPLETED`	Payment has successfully completed after the charge expired.
`DELAYED_UNDERPAID`	Payment arrived after the charge expired and was less than expected.
`DELAYED_OVERPAID`	Payment arrived after the charge expired and was more than expected.
`RESOLVED`	Payment has been marked as resolved by the merchant.

false

.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

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