Brand Connect
Hosted Checkouts
Non-Developers
Merchant Payouts
Customer ManagementGET /networks
GET /assets
GET /currencies
GET /wallets
GET /wallet
POST /checkout/hosted
POST /checkout
POST /checkout/commit
GET /checkout
GET /checkouts
POST /deposit
POST /swap-deposit
POST /swap-deposit/commit
GET /deposit
GET /deposits
POST /swap
POST /swap/commit
GET /swap
GET /swaps
POST /withdrawal
POST /withdrawal/commit
GET /withdrawal
GET /withdrawals
POST /customer
GET /customer
PUT /customer
DELETE /customer
GET /customers
GET /refunds
GET /refund
GET /ping
GET /time
GET /auth-test
GET /languages
GET /exchange-rate
GET /exchange-rate-global
GET /address-validation
WEBHOOK checkout-completed
WEBHOOK checkout-underpaid
WEBHOOK underpaid-accepted
WEBHOOK refund-completed
WEBHOOK deposit-completed
COINQVEST enables you to accept payments in Bitcoin, Ethereum, Litecoin, Stellar Lumens, or any asset on the Stellar Network 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.
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.
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:
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:
{
"charge":{
"billingCurrency":"USD",
"lineItems":[
{
"description":"PCI Graphics Card",
"netAmount":169.99
}
]
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
Above example creates a charge for an item at 169.99 EUR. You can configure more details, such as shipping costs, discounts, taxes, the related customer, as well as your preferred settlement asset as documented here.
{
"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.
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).
{
"eventType":"CHECKOUT_COMPLETED",
"data":{
"checkout":{
"id":"efd667b61725",
"timestamp":"2020-09-16T21:34:28+00:00",
"state":"COMPLETED",
"type":"HOSTED",
"origin":"API",
"settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"settlementAmountRequired":"10.0000000",
"settlementAmountReceived":"10.0000000",
"settlementAmountFeePaid": "0",
"sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmountRequired":"0.0069518",
"sourceAmountReceived":"0.0069518",
"sourceNetwork": "ETHEREUM",
"sourceNetworkName": "Ethereum",
"depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "ETHEREUM",
"networkName": "Ethereum",
"timestamp": "2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:42+00:00",
"tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
"amount":"10.0000000",
"amountAssetCode":"USD",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"PCI Graphics Card",
"quantity":"1",
"netAmount":"169.99",
"productId":"P1234"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
}
}
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.
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.
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.
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.
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.
It's easy to receive cryptocurrency payments even if you are not a developer. Read our guide about hosted checkouts and direct invoicing.
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.
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.
Get API KeyDigest-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.
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"
| 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.
| 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.
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.
curl 'https://www.coinqvest.com/api/v1/auth-test' \
-H "X-Basic: BASIC_AUTH_HASH"
| Key | Type | Description | |
|---|---|---|---|
X-Basic |
string | SHA256 hash over YOUR_API_KEY:YOUR_API_SECRET |
mandatory |
$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';
$basicAuthHash = hash('sha256', $key . ':' . $secret);
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.
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.
1 include('CQMerchantClient.class.php');
2
3 $client = new CQMerchantClient(
4 'YOUR-API-KEY',
5 'YOUR-API-SECRET',
6 '/var/log/coinqvest.log'
7 );
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 )
1 require('coinqvest-merchant-sdk');
2
3 const client = new CoinqvestClient(
4 'YOUR-API-KEY',
5 'YOUR-API-SECRET'
6 );
Returns a list of blockchain and bank networks supported by the COINQVEST platform.
curl 'https://www.coinqvest.com/api/v1/networks'
{
"networks":[
{
"id":"BITCOIN",
"name":"Bitcoin",
"type":"BLOCKCHAIN",
"imageSrc":"/images/icon-btc-88.png",
"deposits":true,
"withdrawals":true,
"bridged": true,
"assets":[
"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
]
},
{
"id":"SWIFT",
"name":"SWIFT",
"type":"BANK",
"imageSrc":"/images/icon-swift-88.png",
"deposits":false,
"withdrawals":true,
"bridged": true,
"assets":[
"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V"
]
},
{
"id":"STELLAR",
"name":"Stellar",
"type":"BLOCKCHAIN",
"imageSrc":"/images/icon-xlm-88.png",
"deposits":true,
"withdrawals":true,
"bridged": false,
"assets":[
"XLM:NATIVE",
"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"ARS:GCYE7C77EB5AWAA25R5XMWNI2EDOKTTFTTPZKM2SR5DI4B4WFD52DARS",
"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP"
]
},
{
"id":"ETHEREUM",
"name":"Ethereum",
"type":"BLOCKCHAIN",
"imageSrc":"/images/icon-eth-88.png",
"deposits":true,
"withdrawals":true,
"bridged": true,
"assets":[
"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V"
]
},
{
"id":"LITECOIN",
"name":"Litecoin",
"type":"BLOCKCHAIN",
"imageSrc":"/images/icon-ltc-88.png",
"deposits":true,
"withdrawals":true,
"bridged": true,
"assets":[
"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP"
]
},
{
"id":"SEPA",
"name":"SEPA",
"type":"BANK",
"imageSrc":"/images/icon-sepa-88.png",
"deposits":false,
"withdrawals":true,
"bridged": true,
"assets":[
"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
]
},
{
"id":"CBU",
"name":"Argentine CBU/CVU",
"type":"BANK",
"imageSrc":"/images/icon-ars-88.png",
"deposits":false,
"withdrawals":true,
"bridged": true,
"assets":[
"ARS:GCYE7C77EB5AWAA25R5XMWNI2EDOKTTFTTPZKM2SR5DI4B4WFD52DARS"
]
},
{
"id":"PIX",
"name":"Brazilian PIX",
"type":"BANK",
"imageSrc":"/images/icon-brl-88.png",
"deposits":false,
"withdrawals":true,
"bridged": true,
"assets":[
"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP"
]
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.networks[] |
array | A list objects representing a blockchain or bank network. | false |
.id |
string | The network identifier. | false |
.name |
string | The network name. | false |
.type |
string | The network type. Can be either BLOCKCHAIN or BANK. |
false |
.imageSrc |
string | The URL of the COINQVEST icon depicting the network. A path relative to www.coinqvest.com. | false |
.deposits |
boolean | Indicates whether this network can be used as to originate payments towards checkouts and deposits. | false |
.withdrawals |
boolean | Indicates whether this network can be receive to transfers and withdrawals. | false |
.bridged |
boolean | Indicates whether this network is native to the COINQVEST platform or bridged via Stellar (SEP-6 or OTC). | false |
.assets |
array | A list of asset identifiers as given by GET /assets indicating the assets available for redemption and reception via the network. |
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns a list of Stellar assets supported by the COINQVEST platform. Assets can be redeemed to and received from the Stellar Network and other payment networks (if they are bridge assets).
For example, BTC assets are bridge assets and can be redeemed to and received from Stellar and the Bitcoin network directly. USDC assets are also bridge assets and can be redeemed to SWIFT and SEPA as well as the Stellar Network.
Inspect the network relations to identify supported networks for an asset.
curl 'https://www.coinqvest.com/api/v1/assets'
{
"assets":[
{
"id":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"assetCode":"BTC",
"assetIssuer":"GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"name":"Bitcoin",
"group":"BTC",
"groupImageSrc":"/images/icon-btc-88.png",
"issuerName":"Papaya",
"issuerDomain":"apay.io",
"issuerAddress":"Rapid SD Pty Ltd., Sydney, Australia",
"imageSrc":"/images/icon-btc-88.png",
"checkouts":true,
"deposits":true,
"settlement":true,
"swaps":true,
"transfers":true,
"hexColor":"#f7931a",
"riskLevel":"MEDIUM",
"bridge":true,
"networks":[
"STELLAR",
"BITCOIN"
]
},
{
"id":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"assetCode":"USDC",
"assetIssuer":"GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"name":"USD Coin",
"group":"USD",
"groupImageSrc":"/images/icon-usd-88.png",
"issuerName":"Centre",
"issuerDomain":"centre.io",
"issuerAddress":"Centre Consortium LLC, United States",
"imageSrc":"/images/icon-usdc-88.png",
"checkouts":true,
"deposits":true,
"settlement":true,
"swaps":true,
"transfers":true,
"hexColor":"#2775ca",
"riskLevel":"LOW",
"bridge":true,
"networks":[
"STELLAR",
"SWIFT",
"SEPA"
]
},
{
"id":"XLM:NATIVE",
"assetCode":"XLM",
"assetIssuer":"NATIVE",
"name":"Stellar Lumens",
"group":"XLM",
"groupImageSrc":"/images/icon-xlm-88.png",
"issuerName":"SDF",
"issuerDomain":"stellar.org",
"issuerAddress":"Stellar Development Foundation, San Francisco, CA, United States",
"imageSrc":"/images/icon-xlm-88.png",
"checkouts":true,
"deposits":true,
"settlement":true,
"swaps":true,
"transfers":true,
"hexColor":"#5894ca",
"riskLevel":"LOW",
"bridge":false,
"networks":[
"STELLAR"
]
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.assets[] |
array | A list objects representing a Stellar asset. | false |
.id |
string | The identifier of the asset. | false |
.assetCode |
string | The asset code. | false |
.assetIssuer |
string | The identifier of the asset issuer on the Stellar Network. | false |
.name |
string | The asset name. | false |
.group |
string | The group to which the asset belongs. For example, USDC and USDT belong to the USD group. BTC and BTCLN (Lightning) belong to the BTC group. | false |
.groupImageSrc |
string | The URL of the COINQVEST icon depicting the asset group. A path relative to www.coinqvest.com. | false |
.issuerName |
string | The asset issuer name in English plain text. | false |
.issuerDomain |
string | The asset issuer's web domain. | false |
.issuerAddress |
string | The asset issuer's physical address. | false |
.imageSrc |
string | The URL of the COINQVEST icon depicting the asset. A path relative to www.coinqvest.com. | false |
.checkouts |
boolean | Indicates whether this asset can be used as payment method in checkouts. | false |
.deposits |
boolean | Indicates whether this asset can be used as payment method in deposits. | false |
.swaps |
boolean | Indicates whether this asset can be used as source or target asset in swaps. | false |
.transfers |
boolean | Indicates whether this asset can be used as target assets in transfers and withdrawals. | false |
.hexColor |
string(7) | COINQVEST's color code for this asset. Useful for charts and other visualizations. | false |
.riskLevel |
string |
Indicating the assets risk level as LOW, MEDIUM, or HIGH. Your risk tolerance can be configured in the (browser-based) settlement settings in your account.
Assets with a LOW risk level are native to the Stellar Network and can be widely redeemed (e.g. XLM and USDC).
Assets with a MEDIUM risk level assets are bridged onto the Stellar network by trusted custodians (anchors) and can be redeemed via SEP-6 or OTC via COINQVEST (e.g. BTC, LTC, ETH, Bitcoin Lightning BTC).
Assets with a HIGH risk level are only available to you if manually enabled in your account settings (e.g. USDT).
|
false |
.bridge |
boolean | Indicates whether this asset is bridged via Stellar (SEP-6 or OTC). | false |
.networks |
array | A list of network identifiers as given by GET /networks indicating the networks on which payment transactions for this asset can be processed. |
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns a list of currencies supported by the COINQVEST platform.
curl 'https://www.coinqvest.com/api/v1/currencies'
{
"currencies": [
{
"assetCode": "BTC",
"name": "Bitcoin",
"type": "CRYPTO",
"billing": true,
"settlement": true,
"payment": true
},
{
"assetCode": "USD",
"name": "US Dollar",
"type": "FIAT",
"billing": true,
"settlement": true,
"payment": false
},
{
"assetCode": "XLM",
"name": "Stellar Lumens",
"type": "CRYPTO",
"billing": true,
"settlement": true,
"payment": true
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.currencies[] |
array | A list objects representing a currency. | false |
.assetCode |
string | The asset code of the currency. | false |
.name |
string | The name of the currency. | false |
.type |
string | The currency type. Either CRYPTO or FIAT. |
false |
.billing |
boolean | Indicates whether this currency can be specified as billing currency in checkout objects. | false |
.settlement |
boolean | Indicates whether this currency can be specified as settlement currency in checkout objects and deposits. | false |
.payment |
boolean | Indicates whether this currency can used as payment currency in checkout objects and deposits. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
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.
curl -X POST https://www.coinqvest.com/api/v1/checkout \
-d "@payload.json"
Where payload.json is a JSON object.
{
"charge":{
"billingCurrency":"EUR",
"lineItems":[
{
"description":"PCI Graphics Card",
"netAmount":169.99
}
]
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.
{
"charge":{
"customerId":"716dad4c5e5f",
"billingCurrency":"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
}
]
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"checkoutLanguage":"en",
"webhook":"https://www.your-server.com/path/to/webhook",
"pageSettings":{
"returnUrl":"https://www.merchant.com/path/to/complete/checkout",
"cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
"shopName":"The T-Shirt Store Ltd.",
"displayBuyerInfo":true,
"displaySellerInfo":true
},
"meta":{
"customAttribute":"customValue"
},
"anchors":{
"BITCOIN":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"ETHEREUM":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR"
}
}
PRO Tip #1 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 #2 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. Use 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 |
.billingCurrency |
string |
A currency code as given by GET /currencies. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.
|
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 |
.settlementAsset |
string |
An asset id as given by GET /assets. Specifies the asset you will be credited in when the checkout completes. Set to ORIGIN to get credited in the asset your customer pays in without any type of currency conversion.
|
ORIGIN | optional |
.checkoutLanguage |
string |
A language code as given by GET /languages. 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 fr fa |
en | optional |
.webhook |
string | A webhook URL on your server that listens for related checkout events as specified in webhook concepts. | null | optional |
.anchors{} |
object |
An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by GET /networks and the value being an anchored asset id as given by GET /assets.
|
null | optional |
.pageSettings{} |
object | An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any). | null | optional |
.returnUrl |
string |
Specifies the url to which to redirect the customer when the payment completes successfully.
Do not rely on this url to capture completed payments. Always confirm payment status with a call to GET /checkout or implement webhooks for reliable payment notifications in your application.
The checkout id, as given in above response, is automatically appended as GET parameter checkoutId to facilitate mapping in your application. You can specify arbitrary additional GET parameters.
|
null | optional |
.cancelUrl |
string |
Specifies the url to which to redirect the customer when he cancels 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 arbitrary additional GET parameters.
|
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 |
.meta |
object | A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced. | true | optional |
{
"id":"c1f4c3777d60",
"paymentMethods":[
{
"assetCode": "XLM",
"blockchain": "Stellar",
"network": "STELLAR",
"relatedAssetId": "XLM:NATIVE",
"paymentAmount": "9835.1414952",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "BTC",
"blockchain": "Bitcoin",
"network": "BITCOIN",
"relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"paymentAmount": "0.0457181",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "ETH",
"blockchain": "Ethereum",
"network": "ETHEREUM",
"relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"paymentAmount": "0.7693317",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "LTC",
"blockchain": "Litecoin",
"network": "LITECOIN",
"relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"paymentAmount": "23.3425586",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
}
]
}
| 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.
The payment methods and amounts should be displayed back to your customer, prompting him to select his desired form of payment. Upon selection, your application submits a POST /checkout/commit and obtains the deposit information and required for your customer to make the payment.
We recommend to apply your own sanity checks on the amounts given in this object and only proceed to the end user if you are satisfied with the quoted settlement and payment amounts. |
false |
.assetCode |
string | The corresponding payment asset code, e.g. BTC. Inspect GET /assets for a list of possible values. |
false |
.blockchain |
string | The blockchain name in plain text. | false |
.network |
string | The payment network identifier as given by GET /networks. Use this identifier to select the desired payment network in the next step at POST /checkout/commit. |
false |
.relatedAssetId |
string | An asset id as given by GET /assets. This asset identifies the Stellar SEP-6 anchor used for capturing the payment, if applicable. |
false |
.paymentAmount |
string | The required payment amount to display back to your customer. | false |
.settlement{} |
object | An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes. The quote is valid for 60 minutes. | false |
.assetId |
string | The asset credited to your account when the payment completes. Contains an asset id as given by GET /assets. |
false |
.amount |
string | The gross amount credited to your account when the payment completes. | false |
.netAmount |
string | The net amount credited to your account when the payment completes. This amount is constituted by the amount minus fee. |
false |
.fee |
string | The settlement fee collected by COINQVEST. | false |
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 the selected network identifier 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.
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
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 a networkId 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:
POST /checkout){
"id":"c1f4c3777d60",
"paymentMethods":[
{
"assetCode": "XLM",
"blockchain": "Stellar",
"network": "STELLAR",
"relatedAssetId": "XLM:NATIVE",
"paymentAmount": "9835.1414952",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "BTC",
"blockchain": "Bitcoin",
"network": "BITCOIN",
"relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"paymentAmount": "0.0457181",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "ETH",
"blockchain": "Ethereum",
"network": "ETHEREUM",
"relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"paymentAmount": "0.7693317",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
},
{
"assetCode": "LTC",
"blockchain": "Litecoin",
"network": "LITECOIN",
"relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"paymentAmount": "23.3425586",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.547598",
"netAmount": "1348.547598",
"fee": "0"
}
}
]
}
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 depositNetwork and checkoutId to receive deposit information for your customer to make the payment.
curl -X POST 'https://www.coinqvest.com/api/v1/checkout/commit'
-d "@payload.json"
Where payload.json is a JSON object.
{
"checkoutId":"6d55626309d6",
"network":"ETHEREUM"
}
| 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 |
{
"depositInstructions":{
"assetCode":"ETH",
"blockchain":"Ethereum",
"network":"ETHEREUM",
"amount":"0.0056804",
"address":"0xc85eBb197c8212C09B7d0905C3ce9e3fCe324F0B",
"memo":null,
"memoType":null
},
"settlement": {
"assetId": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
"amount": "19.2514345"
},
"expirationTime":"2020-02-26T18:49:33+00:00",
"checkoutId":"29d030183ce9"
}
When you customer selects a network *other than* STELLAR, then the relevant fields to make payment are address and amount. The response fields for memo and memoType are only relevant for payments on STELLAR.
{
"depositInstructions":{
"assetCode":"XLM",
"blockchain":"Stellar Network",
"network":"STELLAR",
"amount":"17.8639906",
"address":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
"memo":"snowy-hills",
"memoType":"text"
},
"settlement": {
"assetId": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
"amount": "2.3354345"
},
"expirationTime":"2020-02-26T18:48:58+00:00",
"checkoutId":"d95114c52bca"
}
When your customers select STELLAR 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.
| 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 | The selected payment asset code, e.g. BTC, ETH, XLM, or LTC. |
false |
.network |
string | The selected payment network as given by GET /networks. |
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 |
.settlement{} |
object | An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes. | false |
.assetId |
string | The asset credited to your account when the payment completes. Contains an asset id as given by GET /assets. |
false |
.amount |
string | The amount credited to your account when the payment completes. | false |
.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 |
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.
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
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. You can modify their appearance to match your corporate identity by using Brand Connect.
Hosted checkout URLs are unique and not re-usable. You should issue a new URL for every charge.
curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
-d "@payload.json"
Where payload.json is a JSON object.
{
"charge":{
"billingCurrency":"EUR",
"lineItems":[
{
"description":"PCI Graphics Card",
"netAmount":169.99
}
]
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.
{
"charge":{
"customerId":"716dad4c5e5f",
"billingCurrency":"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
}
]
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"checkoutLanguage":"en",
"webhook":"https://www.your-server.com/path/to/webhook",
"pageSettings":{
"returnUrl":"https://www.merchant.com/path/to/complete/checkout",
"cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
"shopName":"The T-Shirt Store Ltd.",
"displayBuyerInfo":true,
"displaySellerInfo":true
},
"meta":{
"customAttribute":"customValue"
},
"anchors":{
"BITCOIN":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"ETHEREUM":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR"
}
}
PRO Tip #1 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 #2 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. Use 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 |
.billingCurrency |
string |
A currency code as given by GET /currencies. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.
|
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 |
.settlementAsset |
string |
An asset id as given by GET /assets. Specifies the asset you will be credited in when the checkout completes. Set to ORIGIN to get credited in the asset your customer pays in without any type of currency conversion.
|
ORIGIN | optional |
.checkoutLanguage |
string |
A language code as given by GET /languages. 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 fr fa |
en | optional |
.webhook |
string | A webhook URL on your server that listens for related checkout events as specified in webhook concepts. | null | optional |
.anchors{} |
object |
An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by GET /networks and the value being an anchored asset id as given by GET /assets.
|
null | optional |
.pageSettings{} |
object | An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any). | null | optional |
.returnUrl |
string |
Specifies the url to which to redirect the customer when the payment completes successfully.
Do not rely on this url to capture completed payments. Always confirm payment status with a call to GET /checkout or implement webhooks for reliable payment notifications in your application.
The checkout id, as given in above response, is automatically appended as GET parameter checkoutId to facilitate mapping in your application. You can specify arbitrary additional GET parameters.
|
null | optional |
.cancelUrl |
string |
Specifies the url to which to redirect the customer when he cancels 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 arbitrary additional GET parameters.
|
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 |
.meta |
object | A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced. | true | optional |
{
"id":"b5bcf27e5482",
"url":"https://www.coinqvest.com/en/checkout?id=b5bcf27e5482",
"oracle":[
{
"assetCode": "XLM",
"blockchain": "Stellar",
"network": "STELLAR",
"relatedAssetId": "XLM:NATIVE",
"paymentAmount": "9835.0578507",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.5361725",
"netAmount": "1348.5361725",
"fee": "0"
}
},
{
"assetCode": "BTC",
"blockchain": "Bitcoin",
"network": "BITCOIN",
"relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"paymentAmount": "0.0457177",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.5361725",
"netAmount": "1348.5361725",
"fee": "0"
}
},
{
"assetCode": "ETH",
"blockchain": "Ethereum",
"network": "ETHEREUM",
"relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"paymentAmount": "0.7693252",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.5361725",
"netAmount": "1348.5361725",
"fee": "0"
}
},
{
"assetCode": "LTC",
"blockchain": "Litecoin",
"network": "LITECOIN",
"relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"paymentAmount": "23.3424109",
"settlement": {
"assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"amount": "1348.5361725",
"netAmount": "1348.5361725",
"fee": "0"
}
}
}
]
}
| 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. Returns branded URL if Brand Connect is enabled. |
false |
.oracle[] |
array |
Contains a list of available payment methods for this checkout alongside indicative payment amounts and corresponding indicative settlement amounts. The given amounts are an estimation and and based on the current liquidity and market making situation on COINQVEST's decentralized exchange provider. The payment amounts can deviate by the time the buyer initiates payment on the checkout page.
We recommend to apply your own sanity checks on the amounts given in this object and only display the checkout URL to the end user if you are satisfied with the quoted settlement and payment amount estimations. |
false |
.assetCode |
string | The asset code of the payment currency, e.g. BTC. |
false |
.blockchain |
string | The payment blockchain name in plain text. | false |
.network |
string | The payment network identifier as given by GET /networks. |
false |
.relatedAssetId |
string | An asset id as given by GET /assets. This asset identifies the Stellar SEP-6 anchor used for capturing the payment, if applicable. |
false |
.paymentAmount |
string | The required payment amount currently needed to fill your settlement amount. This amount can deviate on the customer facing payment page. | false |
.settlement{} |
object | An object containing information on the settlement asset and amount to be credited to your account when the payment completes. | false |
.assetId |
string | The asset credited to your account when the payment completes. Contains an asset id as given by GET /assets. |
false |
.amount |
string | The gross amount credited to your account when the payment completes. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal. | false |
.netAmount |
string | The net amount credited to your account when the payment completes. This amount is constituted by the amount minus fee. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal. |
false |
.fee |
string | The settlement fee collected by COINQVEST. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
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.
curl 'https://www.coinqvest.com/api/v1/checkout?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by POST /checkout or POST /checkout/hosted. |
null | mandatory |
{
"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",
"sourceNetwork":"ETHEREUM",
"sourceNetworkName":"Ethereum",
"depositAddress":"0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network":"ETHEREUM",
"networkName":"Ethereum",
"timestamp":"2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2020-09-16T21:34:42+00:00",
"tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
"amount":"10.0000000",
"amountAssetCode":"USD",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"T-Shirt",
"quantity":"1",
"netAmount":"10",
"productId":"yellow"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
}
| 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, RESOLVED_REFUNDED, RESOLVED_OTHER.
|
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 as given by GET /assets that 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. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method 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 Stellar representation of the source asset as given by GET /assets. Indicates the payment asset selected by your customer. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceAmountRequired |
string | Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceAmountReceived |
string | The total amount paid by the customer so far. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceNetwork |
string | A payment network id as given by (GET /networks). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceNetworkName |
string | The selected network name in English plain text. | true |
.depositAddress |
string |
The deposit address associated with this checkout. This field is null for checkouts in PENDING_CHARGE state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format:
{memo}:{memoType}@{stellarAccount}
|
true |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this checkout. | false |
.type |
string | The type of blockchain transaction. Can be either CHECKOUT_ORIGIN (blockchain payment transaction initiated by the sender, CHECKOUT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), or CHECKOUT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of checkout objects (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/checkouts?limit=250&offset=0'
| 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 |
{
"count":67,
"limit":1,
"offset":0,
"checkouts":[
{
"id":"efd667b61725",
"timestamp":"2020-09-16T21:34:28+00:00",
"state":"COMPLETED",
"type":"HOSTED",
"origin":"API",
"settlementAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"settlementAmountRequired":"10.0000000",
"settlementAmountReceived":"10.0000000",
"settlementAmountFeePaid": "0",
"sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmountRequired":"0.0069518",
"sourceAmountReceived":"0.0069518",
"sourceNetwork": "ETHEREUM",
"sourceNetworkName": "Ethereum",
"depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "ETHEREUM",
"networkName": "Ethereum",
"timestamp": "2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:42+00:00",
"tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
"amount":"10.0000000",
"amountAssetCode":"USD",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"T-Shirt",
"quantity":"1",
"netAmount":"10",
"productId":"yellow"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
]
}
| 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, RESOLVED_REFUNDED, RESOLVED_OTHER.
|
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 as given by GET /assets that 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. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method 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 Stellar representation of the source asset as given by GET /assets. Indicates the payment asset selected by your customer. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceAmountRequired |
string | Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceAmountReceived |
string | The total amount paid by the customer so far. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceNetwork |
string | A payment network id as given by (GET /networks). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is PENDING_CHARGE and the customer did not select a payment method yet. |
true |
.sourceNetworkName |
string | The selected network name in English plain text. | true |
.depositAddress |
string |
The deposit address associated with this checkout. This field is null for checkouts in PENDING_CHARGE state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format:
{memo}:{memoType}@{stellarAccount}
|
true |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this checkout. | false |
.type |
string | The type of blockchain transaction. Can be either CHECKOUT_ORIGIN (blockchain payment transaction initiated by the sender, CHECKOUT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), or CHECKOUT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns a list of wallet balances. Assets are grouped by their respective asset groups, e.g. `USDC` and `USDT` are listed within the `USD` group and so on.
curl 'https://www.coinqvest.com/api/v1/wallets'
{
"wallets":[
{
"assetCode":"XLM",
"type":"CRYPTO",
"balance":"950.9263842",
"active":true,
"assets":[
{
"id":"XLM:NATIVE",
"issuerName":"SDF",
"issuerDomain":"stellar.org",
"balance":"950.9263842"
}
]
},
{
"assetCode":"USD",
"type":"FIAT",
"balance":"20.7704502",
"active":true,
"assets":[
{
"id":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"issuerName":"Centre",
"issuerDomain":"centre.io",
"balance":"20.7606002",
"active":true
},
{
"id":"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"issuerName":"Tether\/Papaya",
"issuerDomain":"apay.io",
"balance":"0.0098500",
"active":true
}
]
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.wallets[] |
array | A list objects, representing the wallets in your account. | false |
.assetCode |
string(3) | The asset group identifier, 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 group, see below. | false |
.active |
boolean | Indicates whether this asset group is currently active. Asset groups can only be inactive if retired on the COINQVEST platform or not activated for production use yet. | false |
.assets[] |
array | A list of objects, representing the assets in this group, along with their corresponding balances. | false |
.id |
string | An asset identifier as given by GET /assets. |
false |
.issuerName |
string | The name of the asset issuer. | false |
.issuerDomain |
string | The asset issuer's domain. | false |
.balance |
string | The asset balance. | false |
.active |
boolean | Indicates whether this asset is currently active. Assets can only be inactive if retired on the COINQVEST platform or not activated for production use yet. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns an object containing assets and balances of the given asset group (specified by its asset code, e.g. `USD`).
curl 'https://www.coinqvest.com/api/v1/wallet?assetCode=XXX'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
assetCode |
string(3) | Specifies an asset group. Valid selectors are: ARS BRL BTC ETH EUR LTC SAT USD XLM. |
- | mandatory |
{
"wallet":{
"assetCode":"USD",
"type":"FIAT",
"balance":"20.7704502",
"active":true,
"assets":[
{
"id":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"issuerName":"Centre",
"issuerDomain":"centre.io",
"balance":"20.7606002",
"active":true
},
{
"id":"USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
"issuerName":"Tether\/Papaya",
"issuerDomain":"apay.io",
"balance":"0.0098500",
"active":true
}
]
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.wallet{} |
array | An object containing information about the wallet. | false |
.assetCode |
string(3) | The asset group identifier, 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 group, see below. | false |
.active |
boolean | Indicates whether this asset group is currently active. Asset groups can only be inactive if retired on the COINQVEST platform or not activated for production use yet. | false |
.assets[] |
array | A list of objects, representing the assets in this group, along with their corresponding balances. | false |
.id |
string | An asset identifier as given by GET /assets. |
false |
.issuerName |
string | The name of the asset issuer. | false |
.issuerDomain |
string | The asset issuer's domain. | false |
.balance |
string | The asset balance. | false |
.active |
boolean | Indicates whether this asset is currently active. Assets can only be inactive if retired on the COINQVEST platform or not activated for production use yet. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns an address for a direct deposit of an arbitrary amount by yourself. Direct deposits aren't associated with a checkout process or invoice and can be used to fund your account by yourself. The best analogy for its use case is a direct deposit to your bank account.
This endpoint credits you in the source currency. If you deposit BTC, for example, you will be credited in BTC. If you would like to get credited in a different currency than what you send, please use the POST /swap-deposit endpoint instead.
Deposit objects are not re-usable. You should create new deposit requests for each intended deposit transaction.
curl -X POST https://www.coinqvest.com/api/v1/deposit \
-d "@payload.json"
Where payload.json is a JSON object.
{
"sourceNetwork":"BITCOIN"
}
| Key | Type | Description | Nullable | Mandatory |
|---|---|---|---|---|
sourceNetwork |
string | Specifies the network you are going to use to make the deposit. And identifier as given by GET /networks. |
false | mandatory |
sourceAsset |
string | Optionally declares the specific asset that you would like to use during deposit. See GET /assets for available assets. |
true | optional |
.customerId |
string(12) | Specifies a customer related to this deposit, if any. Please use the identifier as given by POST /customer. |
true | optional |
.meta |
object | A custom object containing arbitrary information that you would like to associate with this deposit, if any. This object is included in associated webhook payloads and API responses whenever this deposit is referenced. | true | optional |
.webhook |
string | A webhook URL on your server that listens for related deposit events as specified in webhook concepts. | null | optional |
{
"deposit":{
"id":"5074f4ee055d",
"type":"DIRECT",
"state":"AWAITING_DEPOSIT",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":null,
"sourceNetwork":"BITCOIN",
"sourceNetworkName":"Bitcoin",
"depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
"sourceAmountRequired":"ARBITRARY_AMOUNT",
"sourceAmountReceived":"0",
"sourceAmountMin":"0.0002",
"sourceAmountMax":null,
"sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAmountGross":null,
"creditAmountFee":null,
"creditAmountNet":null,
"creditAmountNetReceived":"0",
"blockchainTransactions":[],
"customerId":null,
"meta":null,
"failover": false,
"failoverType": null,
"failoverParentId": null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.deposit{} |
object | An object with deposit information. | false |
.id |
string(12) | Unique identifier of this deposit. | false |
.type |
string | The deposit type. Either DIRECT for direct deposits without currency conversion or SWAP for deposits involving a currency swap. |
false |
.state |
string | The deposit state. The list of possible values is COMPLETED , AWAITING_DEPOSIT, PROCESSING, PENDING_API_COMMIT and FAILED. |
false |
.origin |
string | Indicates how the deposit was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type SWAP and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead. |
true |
.sourceNetworkName |
string | The network used to make the deposit in English plain text. | false |
.sourceNetwork |
string | The network identifier as given by GET /networks. |
false |
.depositAddress |
string |
The address to which the deposit is made. This field is null for swap deposits in PENDING_API_COMMIT state.
Info for Stellar Network Deposits Includes the memo and memo type in the following format: {memo}:{memoType}@{stellarAccount}
|
true |
.sourceAmountRequired |
string |
The amount required to complete the deposit.
For DIRECT deposits
Contains the string ARBITRARY_AMOUNT indicating that any arbitrary amount within the upper and lower bound specified in sourceAmountMin and sourceAmountMin is acceptable.
For SWAP deposits
Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead. |
false |
.sourceAmountReceived |
string | A numeric string indicating the total amount received for this deposit. | false |
.sourceAmountMin |
string | A numeric string indicating the minimum amount required during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no minimum payment amount is required. |
true |
.sourceAmountMax |
string | A numeric string indicating the maximum amount permitted during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no upper bound exists. |
false |
.sourceAssetIssuer |
string | A asset id indicating the source asset issuer used during the deposit. As given by GET /assets. |
false |
.creditAssetIssuer |
string | An asset id indicating the asset your account is credited in when the deposit is complete. As given by GET /assets |
false |
.creditAmountGross |
string | A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment). | true |
.creditAmountFee |
string | A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNet |
string | A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNetReceived |
string | A numeric string indicating the exact amount your account was credited in. Contains the same amount as creditAmountNet when the deposit is complete, or 0 otherwise. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this deposit. | false |
.type |
string | The type of blockchain transaction. Can be either DEPOSIT_ORIGIN (blockchain payment transaction initiated by the sender, DEPOSIT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), DEPOSIT_CONVERSION (atomic currency swap on the Stellar Network), or DEPOSIT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
.customerId |
string(12) | References the related customer, if any. | true |
.meta |
string | An arbitrary object containing external context information submitted by you when the deposit was created. | true |
.failover |
boolean | Indicates that a problem with the deposit referenced in failoverParentId occurred and an automatic failover mitigation was executed. A failover on a SWAP deposit credits you in the source currency and omits the currency conversion. |
false |
.failoverType |
string |
Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are:
ALREADY_CREDITED, SOURCE_ASSET_MISMATCH, SOURCE_AMOUNT_MISMATCH, INTERNAL_ERROR, EXCHANGE_RATE_EXPIRED, SWAP_ALREADY_IN_PROGRESS.
|
true |
.failoverParentId |
string(12) | References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the id attribute). |
true |
.webhook |
string | The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts). | true |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint invokes a cross-currency swap deposit. It enables you to send an asset (like native Bitcoin) and get credited in a different asset instead. Deposits aren't associated with a checkout process or invoice and can be used to fund your account by yourself or a customer.
Creating a swap deposit is a two-step process. In the first step, you submit the source amount and asset you are going to send as well as the desired target asset you want to be credited in. You receive a target amount, exchange rate, and deposit id in response. In the second step, you analyze the exchange rate and submit another request to POST /swap-deposit/commit to confirm acceptance and receive a deposit address in response.
Deposit objects are not re-usable. You should create new deposit requests for each intended deposit transaction.
curl -X POST https://www.coinqvest.com/api/v1/swap-deposit \
-d "@payload.json"
Where payload.json is a JSON object.
{
"sourceNetwork":"STELLAR",
"sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":100,
"targetNetwork":"BITCOIN"
}
{
"sourceNetwork":"BITCOIN",
"sourceAmount":0.1,
"targetAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
| Key | Type | Description | Nullable | Mandatory |
|---|---|---|---|---|
sourceNetwork |
string | Specifies the network you are going to use to make the deposit. And identifier as given by GET /networks. |
false | mandatory |
sourceAsset |
string | Optionally declares the specific asset that you would like to send. See GET /assets for available assets. |
true | optional |
.sourceAmount |
numeric | Specifies the source amount you are going to send. | false | mandatory |
targetAsset |
string | Declares the asset that you would like to be credited in when the deposit completes. See GET /assets for available assets. |
true | mandatory |
.customerId |
string(12) | Specifies a customer related to this deposit, if any. Please use the identifier as given by POST /customer. |
true | optional |
.meta |
object | A custom object containing arbitrary information that you would like to associate with this deposit, if any. This object is included in associated webhook payloads and API responses whenever this deposit is referenced. | true | optional |
.webhook |
string | A webhook URL on your server that listens for related deposit events as specified in webhook concepts. | null | optional |
{
"deposit":{
"id":"5074f4ee055d",
"type":"SWAP",
"state":"PENDING_API_COMMIT",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceNetwork":"BITCOIN",
"sourceNetworkName":"Bitcoin",
"depositAddress":null,
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"creditAmountGross":"5021.2837211",
"creditAmountFee":"0",
"creditAmountNet":"5021.2837211",
"creditAmountNetReceived":"0",
"blockchainTransactions":[],
"customerId":null,
"meta":null,
"failover": false,
"failoverType": null,
"failoverParentId": null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.deposit{} |
object | An object with deposit information. | false |
.id |
string(12) | Unique identifier of this deposit. | false |
.type |
string | The deposit type. Either DIRECT for direct deposits without currency conversion or SWAP for deposits involving a currency swap. |
false |
.state |
string | The deposit state. The list of possible values is COMPLETED , AWAITING_DEPOSIT, PROCESSING, PENDING_API_COMMIT and FAILED. |
false |
.origin |
string | Indicates how the deposit was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type SWAP and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead. |
true |
.sourceNetworkName |
string | The network used to make the deposit in English plain text. | false |
.sourceNetwork |
string | The network identifier as given by GET /networks. |
false |
.depositAddress |
string |
The address to which the deposit is made. This field is null for swap deposits in PENDING_API_COMMIT state.
Info for Stellar Network Deposits Includes the memo and memo type in the following format: {memo}:{memoType}@{stellarAccount}
|
true |
.sourceAmountRequired |
string |
The amount required to complete the deposit.
For DIRECT deposits
Contains the string ARBITRARY_AMOUNT indicating that any arbitrary amount within the upper and lower bound specified in sourceAmountMin and sourceAmountMin is acceptable.
For SWAP deposits
Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead. |
false |
.sourceAmountReceived |
string | A numeric string indicating the total amount received for this deposit. | false |
.sourceAmountMin |
string | A numeric string indicating the minimum amount required during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no minimum payment amount is required. |
true |
.sourceAmountMax |
string | A numeric string indicating the maximum amount permitted during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no upper bound exists. |
false |
.sourceAssetIssuer |
string | A asset id indicating the source asset issuer used during the deposit. As given by GET /assets. |
false |
.creditAssetIssuer |
string | An asset id indicating the asset your account is credited in when the deposit is complete. As given by GET /assets |
false |
.creditAmountGross |
string | A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment). | true |
.creditAmountFee |
string | A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNet |
string | A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNetReceived |
string | A numeric string indicating the exact amount your account was credited in. Contains the same amount as creditAmountNet when the deposit is complete, or 0 otherwise. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this deposit. | false |
.type |
string | The type of blockchain transaction. Can be either DEPOSIT_ORIGIN (blockchain payment transaction initiated by the sender, DEPOSIT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), DEPOSIT_CONVERSION (atomic currency swap on the Stellar Network), or DEPOSIT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
.customerId |
string(12) | References the related customer, if any. | true |
.meta |
string | An arbitrary object containing external context information submitted by you when the deposit was created. | true |
.failover |
boolean | Indicates that a problem with the deposit referenced in failoverParentId occurred and an automatic failover mitigation was executed. A failover on a SWAP deposit credits you in the source currency and omits the currency conversion. |
false |
.failoverType |
string |
Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are:
ALREADY_CREDITED, SOURCE_ASSET_MISMATCH, SOURCE_AMOUNT_MISMATCH, INTERNAL_ERROR, EXCHANGE_RATE_EXPIRED, SWAP_ALREADY_IN_PROGRESS.
|
true |
.failoverParentId |
string(12) | References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the id attribute). |
true |
.webhook |
string | The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts). | true |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint takes a depositId parameter as given by POST /swap-deposit. Upon successful completion, the deposit request is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to AWAITING_DEPOSIT and a deposit address is given.
In the previous step, POST /swap-deposit gave you an object like this:
POST /swap-deposit){
"deposit":{
"id":"5074f4ee055d",
"type":"SWAP",
"state":"PENDING_API_COMMIT",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceNetwork":"BITCOIN",
"sourceNetworkName":"Bitcoin",
"depositAddress":null,
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"creditAmountGross":"5021.2837211",
"creditAmountFee":"0",
"creditAmountNet":"5021.2837211",
"creditAmountNetReceived":"0",
"blockchainTransactions":[],
"customerId":null,
"meta":null,
"failover": false,
"failoverType": null,
"failoverParentId": null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
As a prerequisite to invoke this endpoint, you should have received a response as above from POST /swap-deposit. Its state is PENDING_API_COMMIT, which means that the deposit is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given creditAmountNet, you need to invoke POST /swap-deposit/commit (this endpoint) to confirm the target amount and receive a deposit address.
curl -X POST 'https://www.coinqvest.com/api/v1/swap-deposit/commit'
-d "@payload.json"
Where payload.json is a JSON object.
{
"depositId":"12d72c3c8145"
}
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
depositId |
string(12) | Unique identifier as given by POST /swap-deposit. |
null | mandatory |
{
"deposit":{
"id":"5074f4ee055d",
"type":"SWAP",
"state":"AWAITING_DEPOSIT",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceNetwork":"BITCOIN",
"sourceNetworkName":"Bitcoin",
"depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
"creditAmountGross":"5021.2837211",
"creditAmountFee":"0",
"creditAmountNet":"5021.2837211",
"creditAmountNetReceived":"0",
"blockchainTransactions":[],
"customerId":null,
"meta":null,
"failover": false,
"failoverType": null,
"failoverParentId": null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.deposit{} |
object | An object containing deposit information. | false |
.id |
string(12) | Unique identifier of this deposit. | false |
.type |
string | The deposit type. Either DIRECT for direct deposits without currency conversion or SWAP for deposits involving a currency swap. |
false |
.state |
string | The deposit state. The list of possible values is COMPLETED , AWAITING_DEPOSIT, PROCESSING, PENDING_API_COMMIT and FAILED. |
false |
.origin |
string | Indicates how the deposit was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type SWAP and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead. |
true |
.sourceNetworkName |
string | The network used to make the deposit in English plain text. | false |
.sourceNetwork |
string | The network identifier as given by GET /networks. |
false |
.depositAddress |
string |
The address to which the deposit is made. This field is null for swap deposits in PENDING_API_COMMIT state.
Info for Stellar Network Deposits Includes the memo and memo type in the following format: {memo}:{memoType}@{stellarAccount}
|
true |
.sourceAmountRequired |
string |
The amount required to complete the deposit.
For DIRECT deposits
Contains the string ARBITRARY_AMOUNT indicating that any arbitrary amount within the upper and lower bound specified in sourceAmountMin and sourceAmountMin is acceptable.
For SWAP deposits
Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead. |
false |
.sourceAmountReceived |
string | A numeric string indicating the total amount received for this deposit. | false |
.sourceAmountMin |
string | A numeric string indicating the minimum amount required during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no minimum payment amount is required. |
true |
.sourceAmountMax |
string | A numeric string indicating the maximum amount permitted during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no upper bound exists. |
false |
.sourceAssetIssuer |
string | A asset id indicating the source asset issuer used during the deposit. As given by GET /assets. |
false |
.creditAssetIssuer |
string | An asset id indicating the asset your account is credited in when the deposit is complete. As given by GET /assets |
false |
.creditAmountGross |
string | A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment). | true |
.creditAmountFee |
string | A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNet |
string | A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNetReceived |
string | A numeric string indicating the exact amount your account was credited in. Contains the same amount as creditAmountNet when the deposit is complete, or 0 otherwise. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this deposit. | false |
.type |
string | The type of blockchain transaction. Can be either DEPOSIT_ORIGIN (blockchain payment transaction initiated by the sender, DEPOSIT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), DEPOSIT_CONVERSION (atomic currency swap on the Stellar Network), or DEPOSIT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
.customerId |
string(12) | References the related customer, if any. | true |
.meta |
string | An arbitrary object containing external context information submitted by you when the deposit was created. | true |
.failover |
boolean | Indicates that a problem with the deposit referenced in failoverParentId occurred and an automatic failover mitigation was executed. A failover on a SWAP deposit credits you in the source currency and omits the currency conversion. |
false |
.failoverType |
string |
Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are:
ALREADY_CREDITED, SOURCE_ASSET_MISMATCH, SOURCE_AMOUNT_MISMATCH, INTERNAL_ERROR, EXCHANGE_RATE_EXPIRED, SWAP_ALREADY_IN_PROGRESS.
|
true |
.failoverParentId |
string(12) | References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the id attribute). |
true |
.webhook |
string | The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts). | true |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves details of a given deposit.
curl 'https://www.coinqvest.com/api/v1/deposit?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by GET /deposits or POST /deposit or POST /swap-deposit. |
null | mandatory |
{
"deposit":{
"id":"262785ce7dc1",
"type":"SWAP",
"state":"COMPLETED",
"origin":"API",
"createTime":"2021-05-14T15:53:14+00:00",
"completeTime":"2021-05-14T15:56:15+00:00",
"expireTime":"2021-05-14T16:53:14+00:00",
"sourceNetwork":"LITECOIN",
"sourceNetworkName":"Litecoin",
"depositAddress":"MUhBPBgjngzREm1NJfK3pUMTYSBDTx3v7X",
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0.1",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"creditAmountGross":"32.2564553",
"creditAmountFee":"0.3282536",
"creditAmountNet":"31.9282017",
"creditAmountNetReceived":"31.9282017",
"blockchainTransactions":[
{
"type":"DEPOSIT_ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "LITECOIN",
"networkName": "Litecoin",
"timestamp": "2021-05-14T15:53:14+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7eeaab614a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-14T15:53:19+00:00",
"tx":"5486e7e200acfb0a4dc1150e432ab9f716aa13b5982e08af78802a701e4d60c8",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_CONVERSION",
"typeDescription":"COINQVEST transaction converting source funds to target asset.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-14T15:53:24+00:00",
"tx":"2067ee5ddac84537596a35bfcea92f95ce5fe1e64d56f0435430775165c584a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-14T15:53:29+00:00",
"tx":"5a8c6de913a5675d3a5b35890a5938c9b2a3f78ca6f1d61b3f67190bab955797",
"amount":"32.2564553",
"amountAssetCode":"USDC"
}
],
"customerId":"3b25c712a52e",
"meta":{
"external_id":"df2ae36472ac"
},
"failover":false,
"failoverType":null,
"failoverParentId":null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.deposit{} |
object | An object containing deposit information. | false |
.id |
string(12) | Unique identifier of this deposit. | false |
.type |
string | The deposit type. Either DIRECT for direct deposits without currency conversion or SWAP for deposits involving a currency swap. |
false |
.state |
string | The deposit state. The list of possible values is COMPLETED , AWAITING_DEPOSIT, PROCESSING, PENDING_API_COMMIT and FAILED. |
false |
.origin |
string | Indicates how the deposit was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type SWAP and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead. |
true |
.sourceNetworkName |
string | The network used to make the deposit in English plain text. | false |
.sourceNetwork |
string | The network identifier as given by GET /networks. |
false |
.depositAddress |
string |
The address to which the deposit is made. This field is null for swap deposits in PENDING_API_COMMIT state.
Info for Stellar Network Deposits Includes the memo and memo type in the following format: {memo}:{memoType}@{stellarAccount}
|
true |
.sourceAmountRequired |
string |
The amount required to complete the deposit.
For DIRECT deposits
Contains the string ARBITRARY_AMOUNT indicating that any arbitrary amount within the upper and lower bound specified in sourceAmountMin and sourceAmountMin is acceptable.
For SWAP deposits
Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead. |
false |
.sourceAmountReceived |
string | A numeric string indicating the total amount received for this deposit. | false |
.sourceAmountMin |
string | A numeric string indicating the minimum amount required during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no minimum payment amount is required. |
true |
.sourceAmountMax |
string | A numeric string indicating the maximum amount permitted during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no upper bound exists. |
false |
.sourceAssetIssuer |
string | A asset id indicating the source asset issuer used during the deposit. As given by GET /assets. |
false |
.creditAssetIssuer |
string | An asset id indicating the asset your account is credited in when the deposit is complete. As given by GET /assets |
false |
.creditAmountGross |
string | A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment). | true |
.creditAmountFee |
string | A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNet |
string | A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNetReceived |
string | A numeric string indicating the exact amount your account was credited in. Contains the same amount as creditAmountNet when the deposit is complete, or 0 otherwise. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this deposit. | false |
.type |
string | The type of blockchain transaction. Can be either DEPOSIT_ORIGIN (blockchain payment transaction initiated by the sender, DEPOSIT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), DEPOSIT_CONVERSION (atomic currency swap on the Stellar Network), or DEPOSIT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
.customerId |
string(12) | References the related customer, if any. | true |
.meta |
string | An arbitrary object containing external context information submitted by you when the deposit was created. | true |
.failover |
boolean | Indicates that a problem with the deposit referenced in failoverParentId occurred and an automatic failover mitigation was executed. A failover on a SWAP deposit credits you in the source currency and omits the currency conversion. |
false |
.failoverType |
string |
Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are:
ALREADY_CREDITED, SOURCE_ASSET_MISMATCH, SOURCE_AMOUNT_MISMATCH, INTERNAL_ERROR, EXCHANGE_RATE_EXPIRED, SWAP_ALREADY_IN_PROGRESS.
|
true |
.failoverParentId |
string(12) | References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the id attribute). |
true |
.webhook |
string | The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts). | true |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of your deposits (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/deposits?limit=250&offset=0'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
limit |
integer | Maximum number of deposit objects to be retrieved. | 250 | optional |
offset |
integer | Specifies the pagination offset. | 0 | optional |
{
"count":2,
"limit":10,
"offset":0,
"deposits":[
{
"deposit":{
"id":"5074f4ee055d",
"type":"DIRECT",
"state":"AWAITING_DEPOSIT",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":null,
"sourceNetwork":"BITCOIN",
"sourceNetworkName":"Bitcoin",
"depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
"sourceAmountRequired":"ARBITRARY_AMOUNT",
"sourceAmountReceived":"0",
"sourceAmountMin":"0.0002",
"sourceAmountMax":null,
"sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"creditAmountGross":null,
"creditAmountFee":null,
"creditAmountNet":null,
"creditAmountNetReceived":"0",
"blockchainTransactions":[
],
"customerId":null,
"meta":null,
"failover":false,
"failoverType":null,
"failoverParentId":null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
},
{
"id":"262785ce7dc1",
"type":"SWAP",
"state":"COMPLETED",
"origin":"API",
"createTime":"2021-05-14T15:53:14+00:00",
"completeTime":"2021-05-14T15:56:15+00:00",
"expireTime":"2021-05-14T16:53:14+00:00",
"sourceNetwork":"LITECOIN",
"sourceNetworkName":"Litecoin",
"depositAddress":"MUhBPBgjngzREm1NJfK3pUMTYSBDTx3v7X",
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0.1",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"creditAmountGross":"32.2564553",
"creditAmountFee":"0.3282536",
"creditAmountNet":"31.9282017",
"creditAmountNetReceived":"31.9282017",
"blockchainTransactions":[
{
"type":"DEPOSIT_ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network":"LITECOIN",
"networkName":"Litecoin",
"timestamp":"2021-05-14T15:53:14+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7eeaab614a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:19+00:00",
"tx":"5486e7e200acfb0a4dc1150e432ab9f716aa13b5982e08af78802a701e4d60c8",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_CONVERSION",
"typeDescription":"COINQVEST transaction converting source funds to target asset.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:24+00:00",
"tx":"2067ee5ddac84537596a35bfcea92f95ce5fe1e64d56f0435430775165c584a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:29+00:00",
"tx":"5a8c6de913a5675d3a5b35890a5938c9b2a3f78ca6f1d61b3f67190bab955797",
"amount":"32.2564553",
"amountAssetCode":"USDC"
}
],
"customerId":"3b25c712a52e",
"meta":{
"external_id":"df2ae36472ac"
},
"failover":false,
"failoverType":null,
"failoverParentId":null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.count |
integer | The total number of deposits initiated in this account. | false |
.limit |
integer | The limit argument used in this request. | false |
.offset |
integer | The pagination offset used in this request. | false |
.deposits[] |
array | A list of deposit objects. | false |
.id |
string(12) | Unique identifier of this deposit. | false |
.type |
string | The deposit type. Either DIRECT for direct deposits without currency conversion or SWAP for deposits involving a currency swap. |
false |
.state |
string | The deposit state. The list of possible values is COMPLETED , AWAITING_DEPOSIT, PROCESSING, PENDING_API_COMMIT and FAILED. |
false |
.origin |
string | Indicates how the deposit was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type SWAP and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead. |
true |
.sourceNetworkName |
string | The network used to make the deposit in English plain text. | false |
.sourceNetwork |
string | The network identifier as given by GET /networks. |
false |
.depositAddress |
string |
The address to which the deposit is made. This field is null for swap deposits in PENDING_API_COMMIT state.
Info for Stellar Network Deposits Includes the memo and memo type in the following format: {memo}:{memoType}@{stellarAccount}
|
true |
.sourceAmountRequired |
string |
The amount required to complete the deposit.
For DIRECT deposits
Contains the string ARBITRARY_AMOUNT indicating that any arbitrary amount within the upper and lower bound specified in sourceAmountMin and sourceAmountMin is acceptable.
For SWAP deposits
Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead. |
false |
.sourceAmountReceived |
string | A numeric string indicating the total amount received for this deposit. | false |
.sourceAmountMin |
string | A numeric string indicating the minimum amount required during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no minimum payment amount is required. |
true |
.sourceAmountMax |
string | A numeric string indicating the maximum amount permitted during arbitrary DIRECT deposits or the exact payment amount required during SWAP deposits. Is set to null of no upper bound exists. |
false |
.sourceAssetIssuer |
string | A asset id indicating the source asset issuer used during the deposit. As given by GET /assets. |
false |
.creditAssetIssuer |
string | An asset id indicating the asset your account is credited in when the deposit is complete. As given by GET /assets |
false |
.creditAmountGross |
string | A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment). | true |
.creditAmountFee |
string | A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNet |
string | A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet. | true |
.creditAmountNetReceived |
string | A numeric string indicating the exact amount your account was credited in. Contains the same amount as creditAmountNet when the deposit is complete, or 0 otherwise. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this deposit. | false |
.type |
string | The type of blockchain transaction. Can be either DEPOSIT_ORIGIN (blockchain payment transaction initiated by the sender, DEPOSIT_TRANSFER (asset issuer fund transfer from native blockchain to Stellar Network), DEPOSIT_CONVERSION (atomic currency swap on the Stellar Network), or DEPOSIT_SETTLEMENT (Stellar transaction crediting your COINQVEST merchant account). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
.customerId |
string(12) | References the related customer, if any. | true |
.meta |
string | An arbitrary object containing external context information submitted by you when the deposit was created. | true |
.failover |
boolean | Indicates that a problem with the deposit referenced in failoverParentId occurred and an automatic failover mitigation was executed. A failover on a SWAP deposit credits you in the source currency and omits the currency conversion. |
false |
.failoverType |
string |
Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are:
ALREADY_CREDITED, SOURCE_ASSET_MISMATCH, SOURCE_AMOUNT_MISMATCH, INTERNAL_ERROR, EXCHANGE_RATE_EXPIRED, SWAP_ALREADY_IN_PROGRESS.
|
true |
.failoverParentId |
string(12) | References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the id attribute). |
true |
.webhook |
string | The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts). | true |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint invokes an asset swap and converts one of your assets in COINQVEST into another asset.
Invoking a swap a two-step process. In the first step, you specify the source asset you are going to send as well as the desired target asset you want to be credited in. Alongside, you can either specify the source amount you are willing to send or the target amount you wish to receive.
In the second step, you analyze the exchange rate in the response and submit another request to POST /swap/commit to confirm acceptance and execute the swap.
curl -X POST https://www.coinqvest.com/api/v1/swap \
-d "@payload.json"
Where payload.json is a JSON object.
{
"sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":100,
"targetAsset":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
}
Above example requests a swap of 100 USDC into Bitcoin. The API response contains the amount of BTC that will be credited to your account in exchange for 100 USD. Confirm the exchange rate by invoking POST /swap/commit.
{
"sourceAsset":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"targetAsset":"XLM:NATIVE",
"targetAmount":100
}
Above example requests a swap from BTC into 100 XLM. The API response contains the amount of BTC that will be debited from your account in exchange for 100 XLM. Confirm the exchange rate by invoking POST /swap/commit.
| Key | Type | Description | Nullable | Mandatory |
|---|---|---|---|---|
sourceAsset |
string | An asset identifier as given by GET /assets. Specifies the source asset in the swap. |
false | mandatory |
sourceAmount |
numeric |
Specifies the amount of sourceAsset you wish to debit from your account to make the swap. The API response contains the calculated target amount, which you can inspect and confirm by invoking a subsequent request to POST /swap/commit. If you would like to specify the exact target amount instead, please use the targetAmount attribute and don't specify a sourceAmount.
|
true | optional |
targetAsset |
string | An asset identifier as given by GET /assets. Specifies the target asset in the swap. |
false | mandatory |
targetAmount |
numeric |
Specifies the amount of targetAsset you wish to credit to your account when the swap completes. The API response contains the required source amount, which you can inspect and confirm by invoking a subsequent request to POST /swap/commit. If you would like to specify the exact source amount instead, please use the sourceAmount attribute and don't specify a targetAmount.
|
true | optional |
{
"swap":{
"id":"5074f4ee055d",
"state":"PENDING_API_COMMIT",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"100.0000000",
"targetAssetId":"XLM:NATIVE",
"targetAmount":"243.3928192",
"blockchainTransactions":[]
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.swap{} |
object | An object with swap information. | false |
.id |
string(12) | Unique identifier of this swap. | false |
.state |
string | The swap state. The list of possible values is COMPLETED , PENDING_API_COMMIT, PROCESSING, and FAILED. |
false |
.type |
string | The swap type. SOURCE_SPECIFIED indicates that you specified the source amount. TARGET_SPECIFIED indicates that you specified the target amount. |
false |
.origin |
string | Indicates how the swap was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution. | true |
.sourceAssetId |
string | The source asset in the swap. An asset id as given by GET /assets. |
false |
.sourceAmount |
string | A numeric string indicating the total amount of sourceAsset debited from your account on swap completion. |
false |
.targetAssetId |
string | The target asset in the swap. An asset id as given by GET /assets. |
false |
.targetAmount |
string | A numeric string indicating the total amount of targetAsset credited to your account on swap completion. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this swap. | false |
.type |
string | The type of blockchain transaction. This is always set to SWAP (blockchain transaction executing the currency swap). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint takes a swapId parameter as given by POST /swap. Upon successful completion, the swap request is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to AWAITING_DEPOSIT and your account is debited the source amount and asset and credited the target amount and asset.
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.
In the previous step, POST /swap gave you an object like this:
POST /swap){
"swap":{
"id":"5074f4ee055d",
"state":"PENDING_API_COMMIT",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"100.0000000",
"targetAssetId":"XLM:NATIVE",
"targetAmount":"243.3928192",
"blockchainTransactions":[]
}
}
As a prerequisite to invoke this endpoint, you should have received a response as above from POST /swap. Its state is PENDING_API_COMMIT, which means that the deposit is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given source and target amounts, you need to invoke POST /swap-deposit/commit (this endpoint) to execute the swap.
curl -X POST 'https://www.coinqvest.com/api/v1/swap/commit'
-d "@payload.json"
Where payload.json is a JSON object.
{
"swapId":"12d72c3c8145"
}
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
swapId |
string(12) | Unique identifier as given by POST /swap. |
null | mandatory |
{
"swap":{
"id":"5074f4ee055d",
"state":"COMPLETED",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":"2021-05-06T22:16:01+00:00",
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"100.0000000",
"targetAssetIssuer":"XLM:NATIVE",
"targetAmount":"243.3928192",
"blockchainTransactions":[
{
"type":"SWAP",
"typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-06T22:16:01+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
"amount":"243.3928192",
"amountAssetCode":"XLM"
}
]
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.swap{} |
object | An object containing swap information. | false |
.id |
string(12) | Unique identifier of this swap. | false |
.state |
string | The swap state. The list of possible values is COMPLETED , PENDING_API_COMMIT, PROCESSING, and FAILED. |
false |
.type |
string | The swap type. SOURCE_SPECIFIED indicates that you specified the source amount. TARGET_SPECIFIED indicates that you specified the target amount. |
false |
.origin |
string | Indicates how the swap was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution. | true |
.sourceAssetId |
string | The source asset in the swap. An asset id as given by GET /assets. |
false |
.sourceAmount |
string | A numeric string indicating the total amount of sourceAsset debited from your account on swap completion. |
false |
.targetAssetId |
string | The target asset in the swap. An asset id as given by GET /assets. |
false |
.targetAmount |
string | A numeric string indicating the total amount of targetAsset credited to your account on swap completion. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this swap. | false |
.type |
string | The type of blockchain transaction. This is always set to SWAP (blockchain transaction executing the currency swap). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves details of a given swap.
curl 'https://www.coinqvest.com/api/v1/swap?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by GET /deposits or POST /swap. |
null | mandatory |
{
"swap":{
"id":"5074f4ee055d",
"state":"COMPLETED",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":"2021-05-06T22:16:01+00:00",
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"100.0000000",
"targetAssetId":"XLM:NATIVE",
"targetAmount":"243.3928192",
"blockchainTransactions":[
{
"type":"SWAP",
"typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-06T22:16:01+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
"amount":"243.3928192",
"amountAssetCode":"XLM"
}
]
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.swap{} |
object | An object containing swap information. | false |
.id |
string(12) | Unique identifier of this swap. | false |
.state |
string | The swap state. The list of possible values is COMPLETED , PENDING_API_COMMIT, PROCESSING, and FAILED. |
false |
.type |
string | The swap type. SOURCE_SPECIFIED indicates that you specified the source amount. TARGET_SPECIFIED indicates that you specified the target amount. |
false |
.origin |
string | Indicates how the swap was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution. | true |
.sourceAssetId |
string | The source asset in the swap. An asset id as given by GET /assets. |
false |
.sourceAmount |
string | A numeric string indicating the total amount of sourceAsset debited from your account on swap completion. |
false |
.targetAssetId |
string | The target asset in the swap. An asset id as given by GET /assets. |
false |
.targetAmount |
string | A numeric string indicating the total amount of targetAsset credited to your account on swap completion. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this swap. | false |
.type |
string | The type of blockchain transaction. This is always set to SWAP (blockchain transaction executing the currency swap). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of your swaps (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/swaps?limit=250&offset=0'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
limit |
integer | Maximum number of swap objects to be retrieved. | 250 | optional |
offset |
integer | Specifies the pagination offset. | 0 | optional |
{
"count":2,
"limit":10,
"offset":0,
"deposits":[
{
"swap":{
"id":"23b4f4ee055d",
"state":"PENDING_API_COMMIT",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":null,
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"10.0000000",
"targetAssetId":"XLM:NATIVE",
"targetAmount":"24.1392819",
"blockchainTransactions":[]
}
},
{
"swap":{
"id":"5074f4ee055d",
"state":"COMPLETED",
"type":"SOURCE_SPECIFIED",
"origin":"API",
"createTime":"2021-05-06T22:15:37+00:00",
"completeTime":"2021-05-06T22:16:01+00:00",
"expireTime":"2021-05-06T23:15:37+00:00",
"sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"100.0000000",
"targetAssetId":"XLM:NATIVE",
"targetAmount":"243.3928192",
"blockchainTransactions":[
{
"type":"SWAP",
"typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2021-05-06T22:16:01+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
"amount":"243.3928192",
"amountAssetCode":"XLM"
}
]
}
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.count |
integer | The total number of swaps initiated in this account. | false |
.limit |
integer | The limit argument used in this request. | false |
.offset |
integer | The pagination offset used in this request. | false |
.swaps[] |
array | A list of swap objects. | false |
.id |
string(12) | Unique identifier of this swap. | false |
.state |
string | The swap state. The list of possible values is COMPLETED , PENDING_API_COMMIT, PROCESSING, and FAILED. |
false |
.type |
string | The swap type. SOURCE_SPECIFIED indicates that you specified the source amount. TARGET_SPECIFIED indicates that you specified the target amount. |
false |
.origin |
string | Indicates how the swap was initiated, either UI or API. |
false |
.createTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was created. | false |
.completeTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is COMPLETED and otherwise it is null. |
true |
.expireTime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution. | true |
.sourceAssetId |
string | The source asset in the swap. An asset id as given by GET /assets. |
false |
.sourceAmount |
string | A numeric string indicating the total amount of sourceAsset debited from your account on swap completion. |
false |
.targetAssetId |
string | The target asset in the swap. An asset id as given by GET /assets. |
false |
.targetAmount |
string | A numeric string indicating the total amount of targetAsset credited to your account on swap completion. |
false |
.blockchainTransactions[] |
array | A list of blockchain transactions associated with this swap. | false |
.type |
string | The type of blockchain transaction. This is always set to SWAP (blockchain transaction executing the currency swap). |
false |
.typeDescription |
string | An explanation of the above blockchain transaction type in English plain text. |
false |
.network |
string | The network id as given by (GET /networks). Indicates where this transaction was executed. |
false |
.networkName |
string | The network name in English plain text. | false |
.timestamp |
string | The timestamp at which this transaction was registered on COINQVEST. | false |
.tx |
string | The corresponding blockchain 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 |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint is invoked when you wish to withdraw funds from the COINQVEST platform into your own cryptocurrency wallets or fiat bank accounts.
Withdrawals are a two-step process. In the first step, you submit the source and target assets as well as the source amount. Upon successful completion, this endpoint returns a withdrawal object, which includes the guaranteed amount that will be deposited into the target account. In the second step, you analyze the exchange rate and confirm the withdrawal by submitting a subsequent request to the POST /withdrawal/commit endpoint.
curl -X POST https://www.coinqvest.com/api/v1/withdrawal \
-d "@payload.json"
Where payload.json is a JSON object.
{
"sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":10,
"targetNetwork":"STELLAR",
"targetAsset":"XLM:NATIVE",
"targetAccount":{
"account":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
"memo":"EXODUS",
"memoType":"text"
}
}
In above example 10 USDC are withdrawn from your COINQVEST wallet, converted into XLM and sent to the Stellar Network account GASKY...6EDCQ.
{
"sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":100,
"targetNetwork":"BITCOIN",
"targetAccount":{
"address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
},
"anchor":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
}
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 anchor BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5 to process this payment and convert the funds from their Stellar representation on COINQVEST into native Bitcoin. See GET /assets for available asset.
{
"sourceAsset":"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP",
"sourceAmount":10000,
"targetNetwork":"PIX",
"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.
| 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 | Specifies the network to which you want to withdraw. This field takes a network id as given by given by GET /networks. |
false | mandatory | ||||||||||||||||||||
.targetAsset |
string | This field is only relevant when the targetNetwork is set to STELLAR (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.) USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN for USDC by Circle. |
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 BITCOIN, ETHEREUM, LITECOIN
Field Attributes for withdrawals to LIGHTNING
Field Attributes for withdrawals to STELLAR (any Stellar asset)
Field Attributes for withdrawals to CBU/CVU (ARS)
Field Attributes for withdrawals to PIX (BRL)
|
false | mandatory | ||||||||||||||||||||
.anchor |
string | A an asset id to optionally declare a specific anchor to process this payment and convert the funds from their Stellar representation on COINQVEST into their native form. See GET /assets for available anchors. |
true | optional |
{
"withdrawal": {
"id": "5ff64e670169",
"type": "WITHDRAWAL",
"state": "PENDING_API_COMMIT",
"origin": "API",
"timestamp": "2022-06-25T03:24:31+03:00",
"sourceAssetCode": "USDC",
"sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount": "2000.0000000",
"targetAssetCode": "USDC",
"targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"targetAmount": "2000.0000000",
"fee": "0",
"targetNetwork": "STELLAR",
"transactionId": null,
"targetAccount": {
"account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
"memo": "custom-memo",
"memoType": "text"
}
}
}
Above response is issued in response to a withdrawal request over 2000 USDC to the Stellar Network.
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.
| 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 asset debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
false | ||||||||||||||||||||||||||||
.targetAmount |
string | This field displays the guaranteed amount received in the target account. | false | ||||||||||||||||||||||||||||
.fee |
string |
Mining or third party fees, if any. Your account is debited the equivalent of the sum of fee + targetAmount.
|
false | ||||||||||||||||||||||||||||
.targetNetwork |
string | A network identifier as given by GET /networks). |
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 BTC, ETH, LTC
Field attributes for withdrawals to XLM (any Stellar Network asset)
Field Attributes for withdrawals to ARS
Field Attributes for withdrawals to BRL
Field attributes for withdrawals to
EUR
Field attributes for withdrawals to NGN
Field attributes for withdrawals to USD
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
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 gave you an object like this:
POST /withdrawal){
"withdrawal": {
"id": "5ff64e670169",
"type": "WITHDRAWAL",
"state": "PENDING_API_COMMIT",
"origin": "API",
"timestamp": "2022-06-25T03:24:31+03:00",
"sourceAssetCode": "USDC",
"sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount": "2000.0000000",
"targetAssetCode": "USDC",
"targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"targetAmount": "2000.0000000",
"fee": "0",
"targetNetwork": "STELLAR",
"transactionId": null,
"targetAccount": {
"account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
"memo": "custom-memo",
"memoType": "text"
}
}
}
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 that the withdrawal is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given targetAmount, you need to invoke POST /withdrawal/commit (this endpoint) to confirm the withdrawal and submit it for processing.
curl -X POST 'https://www.coinqvest.com/api/v1/withdrawal/commit'
-d "@payload.json"
Where payload.json is a JSON object.
{
"withdrawalId":"12d72c3c8145"
}
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
withdrawalId |
string(12) | Unique identifier as given by POST /withdrawal. |
null | mandatory |
{
"withdrawal": {
"id": "5ff64e670169",
"type": "WITHDRAWAL",
"state": "COMPLETED",
"origin": "API",
"timestamp": "2022-06-25T03:24:31+03:00",
"sourceAssetCode": "USDC",
"sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount": "2000.0000000",
"targetAssetCode": "USDC",
"targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"targetAmount": "2000.0000000",
"fee": "0",
"targetNetwork": "STELLAR",
"transactionId": "1e9c0c0cec0e6d54ed67d0c9f7899e238409c1f053e96fa1d3647bddbfe8b3cf",
"targetAccount": {
"account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
"memo": "custom-memo",
"memoType": "text"
}
}
}
| 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 asset debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
false | ||||||||||||||||
.targetAmount |
string | This field displays the amount received in the target account. | false | ||||||||||||||||
.fee |
string |
Mining or third party fees, if any. Your account is debited the equivalent of the sum of fee + targetAmount.
|
false | ||||||||||||||||
.targetNetwork |
string | References the network to which this withdrawal was sent by id and as originally given in the request. See GET /networks) for more. |
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 targetNetwork.
Field attributes for withdrawals to BTC, ETH, LTC
Field attributes for withdrawals to XLM (any Stellar Network asset)
Field Attributes for withdrawals to ARS
Field Attributes for withdrawals to PIX
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves details of a given withdrawal.
curl 'https://www.coinqvest.com/api/v1/withdrawal?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by GET /withdrawals or POST /withdrawal. |
null | mandatory |
{
"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",
"targetNetwork":"NIBSS",
"transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
"targetAccount":{
"nuban":"4791494548",
"bankName":"FirstBank"
}
}
}
| 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 | Represents the withdrawal state. The list of possible values is COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. |
false | ||||||||||||||||
.origin |
string | Indicates how the withdrawal was initiated, either UI or API. |
false | ||||||||||||||||
.timestamp |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. | false | ||||||||||||||||
.sourceAssetCode |
string | The asset code debited from your account (e.g USD). |
false | ||||||||||||||||
.sourceAssetIssuer |
string | The asset id debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
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 | ||||||||||||||||
.targetNetwork |
string | A network identified as given by GET /networks). |
true | ||||||||||||||||
.transactionId |
string(64) | References the payout 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 targetNetwork.
Field attributes for withdrawals to BTC, ETH, LTC
Field attributes for withdrawals to XLM (any Stellar Network asset)
Field Attributes for withdrawals to ARS
Field Attributes for withdrawals to PIX
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of your withdrawals (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/withdrawals?limit=250&offset=0'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
limit |
integer | Maximum number of withdrawal objects to be retrieved. | 250 | optional |
offset |
integer | Specifies the pagination offset. | 0 | optional |
{
"count":2,
"limit":10,
"offset":0,
"withdrawals":[
{
"id":"b35c97c377f9",
"type":"WITHDRAWAL",
"state":"COMPLETED",
"origin":"UI",
"timestamp":"2020-03-04T17:22:39+02:00",
"sourceAssetCode":"XLM",
"sourceAssetIssuer":"XLM:NATIVE",
"sourceAmount":"0.1765850",
"targetAssetCode":"XLM",
"targetAssetIssuer":"XLM:NATIVE",
"targetAmount":"0.1765850",
"withdrawalFee":"0",
"targetNetwork":"STELLAR",
"transactionId":"b7bb615cabf971d1e00256ae87249333e4deb9ef1ad5dad80ee2af0ea21d050b",
"targetAccount":{
"account":"GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
"memo":"EXODUS",
"memoType":"text"
}
},
{
"id":"12d72c3c8145",
"type":"WITHDRAWAL",
"state":"COMPLETED",
"origin":"UI",
"timestamp":"2020-03-04T19:54:47+02:00",
"sourceAssetCode":"USDC",
"sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount":"1.4231566",
"targetAssetCode":"NGNT",
"targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
"targetAmount":"315.0909904",
"withdrawalFee":"200.0000000",
"targetNetwork":"NIBSS",
"transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
"targetAccount":{
"nuban":"4791494548",
"bankName":"FirstBank"
}
}
]
}
| Name | Type | Description | Nullable | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
.count |
integer | The total number of withdrawals sent from this account. | false | ||||||||||||||||
.limit |
integer | The limit argument used in this request. | false | ||||||||||||||||
.offset |
integer | The pagination offset used in this request. | false | ||||||||||||||||
.withdrawals[] |
array | A list of withdrawal objects. | false | ||||||||||||||||
.id |
string(12) | Unique identifier of this withdrawal. | false | ||||||||||||||||
.type |
string | The debit type. Currently, the only existing value is WITHDRAWAL. |
false | ||||||||||||||||
.state |
string | Represents the withdrawal state. The list of possible values is COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. |
false | ||||||||||||||||
.origin |
string | Indicates how the withdrawal was initiated, either UI or API. |
false | ||||||||||||||||
.timestamp |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. | false | ||||||||||||||||
.sourceAssetCode |
string | The asset code debited from your account (e.g USD). |
false | ||||||||||||||||
.sourceAssetIssuer |
string | The asset id debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
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 | ||||||||||||||||
.targetNetwork |
string | A network identified as given by GET /networks). |
true | ||||||||||||||||
.transactionId |
string(64) | References the payout 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 targetNetwork.
Field attributes for withdrawals to BTC, ETH, LTC
Field attributes for withdrawals to XLM (any Stellar Network asset)
Field Attributes for withdrawals to ARS
Field Attributes for withdrawals to PIX
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of your refunds (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/refunds?limit=250&offset=0'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
limit |
integer | Maximum number of refund objects to be retrieved. | 250 | optional |
offset |
integer | Specifies the pagination offset. | 0 | optional |
{
"count":2,
"limit":10,
"offset":0,
"refunds":[
{
"id":"9476b254eff8",
"type":"REFUND",
"state":"COMPLETED",
"origin":"UI",
"context":"UNDERPAID_CHECKOUT",
"checkoutId":"9552e1c011fe",
"customerId":"3b25c712a52e",
"timestamp":"2020-11-18T00:37:05+03:00",
"sourceAssetCode":"ETH",
"sourceAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmount":"0.0000000",
"targetAssetCode":"ETH",
"targetAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"targetAmount":"0.0105601",
"fee":"0.0010115",
"targetNetwork":"ETHEREUM",
"transactionId":"9bea8240257448974c6067076c9f4d90c9505e69efaf130cb832d8dbb2183e77",
"targetAccount":{
"address":"0xA2Bf179E09C503262E418FC72261837726f68E36"
}
},
{
"id":"16452d3d830d",
"type":"REFUND",
"state":"COMPLETED",
"origin":"UI",
"context":"UNDERPAID_CHECKOUT",
"checkoutId":"fb715abd870e",
"customerId":"3b25c712a52e",
"timestamp":"2020-11-18T02:41:13+03:00",
"sourceAssetCode":"ETH",
"sourceAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmount":"0.0000000",
"targetAssetCode":"XLM",
"targetAssetIssuer":"XLM:NATIVE",
"targetAmount":"5.4806182",
"fee":"0",
"targetNetwork":"STELLAR",
"transactionId":"3410fd5a32c0a72df0c6b5e324170aaa1e138b696fe60cd2c328e45a43361db0",
"targetAccount":{
"account":"GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNA6",
"memo":"REFUND",
"memoType":"text"
}
}
]
}
| Name | Type | Description | Nullable | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
.count |
integer | The total number of refunds sent from this account. | false | ||||||||
.limit |
integer | The limit argument used in this request. | false | ||||||||
.offset |
integer | The pagination offset used in this request. | false | ||||||||
.refunds[] |
array | A list of refund objects. | false | ||||||||
.id |
string(12) | Unique identifier of this refund. | false | ||||||||
.type |
string | The debit type. Currently, the only existing value is REFUND. |
false | ||||||||
.state |
string | This field represents the refund state. Currently, the only possible values are COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. |
false | ||||||||
.origin |
string | This field indicates how the refund was initiated, either UI or API. |
false | ||||||||
.context |
string | This field indicates indicates in what context the refund was initiated, either COMPLETED_CHECKOUT, UNDERPAID_CHECKOUT, or OVERPAID_TX. It's important to keep in mind that only refunds with a context of CHECKOUT_COMPLETED are debited from your wallet balance. Otherwise your account was never credited in the first place and the associated sourceAmount is zero. |
false | ||||||||
.checkoutId |
string(12) | Unique identifier of the associated checkout. | false | ||||||||
.customerId |
string(12) | Unique identifier of the associated customer (if any). | true | ||||||||
.timestamp |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the refund was initiated. | false | ||||||||
.sourceAssetCode |
string | The asset code debited from your account (e.g USD). |
false | ||||||||
.sourceAssetIssuer |
string | Identifier of the asset debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
false | ||||||||
.targetAmount |
string | This field displays the amount received in the target account. | false | ||||||||
.fee |
string |
Mining or third party fees, if any. Your account is debited the equivalent of the sum of fee + targetAmount.
|
false | ||||||||
.targetNetwork |
string | A network identifier as given by GET /networks. |
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.
Field attributes for refunds to BTC, ETH, LTC
Field attributes for refunds to XLM (any Stellar Network asset)
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves details of a given refund.
curl 'https://www.coinqvest.com/api/v1/refund?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by GET /refunds. |
null | mandatory |
{
"refund":{
"id":"9476b254eff8",
"type":"REFUND",
"state":"COMPLETED",
"origin":"UI",
"context":"UNDERPAID_CHECKOUT",
"checkoutId":"9552e1c011fe",
"customerId":"3b25c712a52e",
"timestamp":"2020-11-18T00:37:05+03:00",
"sourceAssetCode":"ETH",
"sourceAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmount":"0.0000000",
"targetAssetCode":"ETH",
"targetAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"targetAmount":"0.0105601",
"fee":"0.0010115",
"targetNetwork":"ETHEREUM",
"transactionId":"9bea8240257448974c6067076c9f4d90c9505e69efaf130cb832d8dbb2083e77",
"targetAccount":{
"address":"0xA2Bf179E09C503262E418FC72261837726f68E36"
}
}
}
| Name | Type | Description | Nullable | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
.refund{} |
object | An object with details about the refund. | false | ||||||||
.id |
string(12) | Unique identifier of this refund. | false | ||||||||
.type |
string | The debit type. Currently, the only existing value is REFUND. |
false | ||||||||
.state |
string | This field represents the refund state. Currently, the only possible values are COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. |
false | ||||||||
.origin |
string | This field indicates how the refund was initiated, either UI or API. |
false | ||||||||
.context |
string | This field indicates indicates in what context the refund was initiated, either COMPLETED_CHECKOUT, UNDERPAID_CHECKOUT, or OVERPAID_TX. It's important to keep in mind that only refunds with a context of CHECKOUT_COMPLETED are debited from your wallet balance. Otherwise your account was never credited in the first place and the associated sourceAmount is zero. |
false | ||||||||
.checkoutId |
string(12) | Unique identifier of the associated checkout. | false | ||||||||
.customerId |
string(12) | Unique identifier of the associated customer (if any). | true | ||||||||
.timestamp |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the refund was initiated. | false | ||||||||
.sourceAssetCode |
string | The asset code debited from your account (e.g USD). |
false | ||||||||
.sourceAssetIssuer |
string | Identifier of the asset debited from your account, see GET /assets. |
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 | The target asset identifier, see GET /assets. |
false | ||||||||
.targetAmount |
string | This field displays the amount received in the target account. | false | ||||||||
.fee |
string |
Mining or third party fees, if any. Your account is debited the equivalent of the sum of fee + targetAmount.
|
false | ||||||||
.targetNetwork |
string | A network identifier as given by GET /networks. |
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.
Field attributes for refunds to BTC, ETH, LTC
Field attributes for refunds to XLM (any Stellar Network asset)
|
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Sends a ping request to the API. This endpoint is a good starting place in trying to initially connect to the COINQVEST API.
curl 'https://www.coinqvest.com/api/v1/ping'
{
"success":true
}
| Name | Type | Description | Nullable |
|---|---|---|---|
success |
boolean | Indicates the request was processed successfully. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Validates public keys (addresses or accounts) on supported blockchains. Can be used as an utility endpoint to validate user input in your application.
curl 'https://www.coinqvest.com/api/v1/address-validation?network=BITCOIN&address=bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
network |
string | A network identifier as given by GET /networks, e.g. BITCOIN, STELLAR, ETHEREUM, or LITECOIN. |
null | mandatory |
address |
string | An address or account public key corresponding to the selected network. | null | mandatory |
{
"valid":true
}
| Name | Type | Description | Nullable |
|---|---|---|---|
valid |
boolean | Indicates whether the given address or account public key is valid. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
This endpoint returns the current exchange rate between two assets at a given amount while taking into account current liquidity and order book situation on the Stellar Decentralized Exchange (which COINQVEST implements on its platform). This endpoint can be used to calculate the tentative exchange rate during checkouts or swaps on COINQVEST.
To query the global average exchange rate between two arbitrary currencies, please use the GET /exchange-rate-global endpoint instead.
curl 'https://www.coinqvest.com/api/v1/exchange-rate?sourceAsset=USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN&targetAsset=BTC&amount=GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF&amount=5000'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
sourceAsset |
string | A source asset id as given by GET /assets. |
null | mandatory |
targetAsset |
string | A target asset id as given by GET /assets. |
null | mandatory |
amount |
numeric | The source amount in send-amount queries or the target amount in receive-amount queries (see switch). |
null | mandatory |
switch |
string |
Set to send-amount to indicate that you want to query the tentative amount of targetAsset you will receive for sending a given amount of sourceAsset.
Set to receive-amount to indicate that you want to query the tentative amount of sourceAsset you will have to send to receive a given amount of targetAsset.
|
send-amount | mandatory |
{
"sourceAsset": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"sourceAmount": "5000",
"targetAsset": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
"targetAmount": "0.1622371",
"pair": "BTC/USD",
"exchangeRate": "1:30819.0913175",
"deviation": "0.182",
"switch": "send-amount"
}
| Name | Type | Description | Nullable |
|---|---|---|---|
sourceAsset |
string | The given source asset. | false |
sourceAmount |
string | The given source amount for send-amount lookups, or the calculated source amount in receive-amount lookups. | false |
targetAsset |
string | The given target asset. | false |
targetAmount |
string | The given target amount for receive-amount lookups, or the calculated target amount in send-amount lookups. | false |
pair |
string | The currency pair. Base currency followed by the quote currency. | false |
exchangeRate |
string | A numeric string indicating the tentative exchange rate for the given assets and amount. | false |
deviation |
string | A numeric string indicating how much the given exchange rate deviates from the global average exchange rate in percentage points. A negative value indicates that the exchange rate is *better* than the global average and a positive value indicates that the exchange rate is *worse* than the global average. | false |
switch |
string | The given send-amount or receive-amount setting. |
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns the global average exchange rate between two arbitrary currencies. This endpoint is purely informative and does not reflect exchange rates available on COINQVEST. To query exchange rates as used by the COINQVEST platform, please use the GET /exchange-rate endpoint instead.
curl 'https://www.coinqvest.com/api/v1/exchange-rate-global?baseCurrency=CHF"eCurrency=EUR'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
baseCurrency |
string | The ISO code of the base currency. See below for a list of supported currencies. | null | mandatory |
quoteCurrency |
string | The ISO code of the quote (counter) currency. See below for a list of supported currencies. | null | mandatory |
timestamp |
string | A timestamp in the format YYYY-MM-DD (2019-01-01 or later). Defaults to the current time. |
null | optional |
| Asset Code | Name | Type |
|---|---|---|
AED | Emirati Dirham | FIAT |
ARS | Argentine Peso | FIAT |
AUD | Australian Dollar | FIAT |
BDT | Bangladeshi Taka | FIAT |
BHD | Bahraini Dinar | FIAT |
BMD | Bermudian Dollar | FIAT |
BRL | Brazilian Real | FIAT |
BTC | Bitcoin | CRYPTO |
CAD | Canadian Dollar | FIAT |
CHF | Swiss Franc | FIAT |
CLP | Chilean Peso | FIAT |
CNY | Chinese Yuan | FIAT |
CZK | Czech Koruna | FIAT |
DKK | Danish Krone | FIAT |
ETH | Ether | CRYPTO |
EUR | Euro | FIAT |
GBP | British Pound | FIAT |
HKD | Hong Kong Dollar | FIAT |
HUF | Hungarian Forint | FIAT |
IDR | Indonesian Rupiah | FIAT |
ILS | Israeli Shekel | FIAT |
INR | Indian Rupee | FIAT |
JPY | Japanese Yen | FIAT |
KRW | Korean Won | FIAT |
KWD | Kuwaiti Dinar | FIAT |
LKR | Sri Lankan Rupee | FIAT |
LTC | Litecoin | CRYPTO |
MMK | Myanmar Kyat | FIAT |
MXN | Mexican Peso | FIAT |
MYR | Malaysian Ringgit | FIAT |
NGN | Nigerian Naira | FIAT |
NOK | Norwegian Krone | FIAT |
NZD | New Zealand Dollar | FIAT |
PHP | Philippine Peso | FIAT |
PKR | Pakistani Rupee | FIAT |
PLN | Polish Zloty | FIAT |
RUB | Russian Ruble | FIAT |
SAR | Saudi Arabian Riyal | FIAT |
SAT | Satoshi | CRYPTO |
SEK | Swedish Krona | FIAT |
SGD | Singapore Dollar | FIAT |
THB | Thai Baht | FIAT |
TRY | Turkish Lira | FIAT |
TWD | Taiwan Dollar | FIAT |
UAH | Ukrainian Hryvnia | FIAT |
USD | US Dollar | FIAT |
VEF | Venezuelan Bolivar | FIAT |
VND | Vietnamese Dong | FIAT |
XLM | Stellar Lumens | CRYPTO |
XRP | XRP | CRYPTO |
ZAR | South African Rand | FIAT |
{
"baseCurrency": "CHF",
"quoteCurrency": "EUR",
"pair": "CHF/EUR",
"exchangeRate": "0.9339042",
"timestamp": "2021-09-04T21:29:10+00:00"
}
| Name | Type | Description | Nullable |
|---|---|---|---|
baseCurrency |
string | The base currency as given in the API request. | false |
quoteCurrency |
string | The quote (counter) currency as given in the API request. | false |
pair |
string | The currency pair used for this exchange. Base currency followed by the quote (counter) currency. | false |
exchangeRate |
numeric | The exchange rate at the given timestamp. | false |
timestamp |
string | W3C formatted timestamp at which the exchange rate was calculated. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns a Unix timestamp with the current COINQVEST server time. Use this endpoint when generating the Digest-Auth signature for authentication if you feel time the between your server and the COINQVEST server is askew.
curl 'https://www.coinqvest.com/api/v1/time'
{
"time":1525898643
}
| Name | Type | Description | Nullable |
|---|---|---|---|
time |
integer | Unix timestamp with COINQVEST server time. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Similar to the GET /ping endpoint except this requires authentication.
A good starting place to test your Basic-Auth or (recommended) Digest-Auth implementation. The below example demonstrates a Digest-Auth request. This endpoint accepts Basic-Auth but it is discouraged for production environments. To use Basic-Auth, replace the X-Digest headers with the X-Basic one (see Authentication).
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"
| Key | Type | Description |
|---|---|---|
X-Digest-Key |
string | Your COINQVEST API Key |
X-Digest-Signature |
string | Unique Digest-Auth signature (see authentication) |
X-Digest-Timestamp |
integer | Current Unix timestamp (also see GET /time). |
{
"success":true
}
| Name | Type | Description | Nullable |
|---|---|---|---|
success |
boolean | Indicates the request was processed successfully. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Returns a list of languages supported by endpoints POST /checkout/hosted and POST /checkout.
curl 'https://www.coinqvest.com/api/v1/languages'
{
"languages":[
{
"name":"English",
"languageCode":"en",
"countryCode":"EN",
"locale":"en_US"
},
{
"name":"Português",
"languageCode":"pt",
"countryCode":"PT",
"locale":"pt_PT"
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.languages[] |
array | A list of supported languages. | false |
.name |
string | Name of the language. | false |
.languageCode |
string | ISO-639 language code. | false |
.countryCode |
string | ISO-3166 country code. | false |
.locale |
string | Code of the locale. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves a list of customers (in descending order from newest to oldest).
curl 'https://www.coinqvest.com/api/v1/customers?limit=250&offset=0'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
limit |
integer | Maximum number of customer objects to be retrieved. | 250 | optional |
offset |
integer | Specifies the pagination offset. | 0 | optional |
{
"count":1,
"limit":"250",
"offset":"0",
"customers":[
{
"id":"fd4f47a50c7f",
"email":"john@doe.com",
"firstname":"John",
"lastname":"Doe",
"name":"John Doe",
"company":"ACME Inc.",
"adr1":"810 Beach St",
"adr2":"Finance Dept",
"zip":"CA 94133",
"city":"San Francisco",
"countrycode":"US",
"country":"United States",
"phonenumber":"+14156226819",
"taxid":"US1234567890",
"note":"Always pays on time. Never late.",
"meta":{
"reference":123
},
"inserttime":"2018-12-10T16:16:18+00:00",
"updatetime":"2018-12-11T17:34:09+00:00",
"invoiceable":true
}
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.count |
integer | The total number of customers in existence for this account. | false |
.limit |
integer | The limit argument used in this request. | false |
.offset |
integer | The pagination offset used in this request. | false |
.customers[] |
array | A list of customer objects. | false |
.id |
string(12) | Unique identifier. | false |
.email |
string | The customer's email address. | false |
.firstname |
string | The customer's first name. | true |
.lastname |
string | The customer's last name. | true |
.name |
string | The customer's first name and last name conveniently concatenated into a single attribute. | true |
.company |
string | The customer's company name. | true |
.adr1 |
string | The customer's first address line. | true |
.adr2 |
string | The customer's second address line. | true |
.zip |
string | The customer's zip code. | true |
.city |
string | The customer's city. | true |
.countrycode |
string(2) | The customer's country in two character ISO format. | true |
.country |
string | The customer's country in plain English. | true |
.phonenumber |
string | The customer's phone number in international standard format (leading plus). | true |
.taxid |
string | The customer's tax id. | true |
.note |
string | An arbitrary note associated with the customer. | true |
.meta |
string | An arbitrary JSON object associated with the customer. | true |
.inserttime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the customer was created. | true |
.updatetime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated. | true |
.invoiceable |
boolean | Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, adr1, zip, city, countrycode and either firstname and lastname or company. |
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Creates a customer object, which can be associated with checkouts, payments, and invoices. If a customer with the given email address already exists an update is performed. This endpoint can therefore be used as an alternative to PUT /customer.
Checkouts associated with a customer generate more transaction details, help with your accounting, and can automatically generate invoices for your customer and yourself.
The Merchant API implements endpoints to create (POST /customer), delete (DELETE /customer), and update (PUT /customer) your customers. You can also retrieve individual customers (GET /customer) as well as fetch a list of all your customers (GET /customers).
curl -X POST https://www.coinqvest.com/api/v1/customer \
-d "@payload.json"
Where payload.json is a JSON object.
{
"customer":{
"email":"john@doe.com",
"firstname":"John",
"lastname":"Doe",
"company":"ACME Inc.",
"adr1":"810 Beach St",
"adr2":"Finance Dept",
"zip":"CA 94133",
"city":"San Francisco",
"countrycode":"US",
"phonenumber":"+14156226819",
"taxid":"US1234567890",
"note":"Always pays on time. Never late.",
"meta":{
"reference":123
}
}
}
PRO Tip
To make a customer invoiceable you need to provide a name or a company as well as a complete address with adr1, zip, city, and countrycode at a minimum.
| Key | Type | Description | Nullable | Mandatory |
|---|---|---|---|---|
customer{} |
object | An object containing information about your customer. | false | mandatory |
.email |
string | The customer's email address. If a customer with the given email address already exists an update of below records is performed. | false | mandatory |
.firstname |
string | The customer's first name. | true | optional |
.lastname |
string | The customer's last name. | true | optional |
.company |
string | The customer's company name. | true | optional |
.adr1 |
string | The customer's first address line. Must be provided alongside zip, city, and countrycode |
true | optional |
.adr2 |
string | The customer's second address line. | true | optional |
.zip |
string | The customer's zip code. Must be provided alongside adr1, city, and countrycode |
true | optional |
.city |
string | The customer's city. Must be provided alongside adr1, zip, and countrycode |
true | optional |
.countrycode |
string | The customer's country as two character ISO code. Must be provided alongside adr1, zip, and city |
true | optional |
.phonenumber |
string | The customer's phone number. | true | optional |
.taxid |
string | The customer's tax id. Useful for accounting and invoicing purposes. | true | optional |
.note |
string | An arbitrary note associated with the customer. | true | optional |
.meta |
object | An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use. | true | optional |
{
"customerId":"fd4f47a50c7f"
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.customerId |
string(12) | Unique identifier of the new customer object. Store this persistently for later use. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Retrieves details of a given customer.
curl 'https://www.coinqvest.com/api/v1/customer?id=xxx'
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by POST /customer. |
null | mandatory |
{
"customer":{
"id":"fd4f47a50c7f",
"email":"john@doe.com",
"firstname":"John",
"lastname":"Doe",
"name":"John Doe",
"company":"ACME Inc.",
"adr1":"810 Beach St",
"adr2":"Finance Dept",
"zip":"CA 94133",
"city":"San Francisco",
"countrycode":"US",
"country":"United States",
"phonenumber":"+14156226819",
"taxid":"US1234567890",
"note":"Always pays on time. Never late.",
"meta":{
"reference":123
},
"inserttime":"2018-12-10T16:16:18+00:00",
"updatetime":"2018-12-11T17:34:09+00:00",
"invoiceable":true
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.customer{} |
array | An object with details about the customer. | false |
.id |
string(12) | Unique identifier. | false |
.email |
string | The customer's email address. | false |
.firstname |
string | The customer's first name. | true |
.lastname |
string | The customer's last name. | true |
.name |
string | The customer's first name and last name conveniently concatenated into a single attribute. | true |
.company |
string | The customer's company name. | true |
.adr1 |
string | The customer's first address line. | true |
.adr2 |
string | The customer's second address line. | true |
.zip |
string | The customer's zip code. | true |
.city |
string | The customer's city. | true |
.countrycode |
string(2) | The customer's country in two character ISO format. | true |
.country |
string | The customer's country in plain English. | true |
.phonenumber |
string | The customer's phone number in international standard format (leading plus). | true |
.taxid |
string | The customer's tax id. | true |
.note |
string | An arbitrary note associated with the customer. | true |
.meta |
string | An arbitrary JSON object associated with the customer. | true |
.inserttime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the customer was created. | true |
.updatetime |
timestamp | W3C formatted time stamp with time zone (UTC) specifying when the customer was last updated. | true |
.invoiceable |
boolean | Indicates whether this customer can be invoiced. To qualify for invoices the following fields must be set, adr1, zip, city, countrycode and either firstname and lastname or company. |
false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Updates an existing customer object.
All attributes besides id and email are optional. You can submit a partial customer object including the fields you wish to update only. To unset an attribute set its value to null.
curl -X PUT https://www.coinqvest.com/api/v1/customer \
-d "@payload.json"
Where payload.json is a JSON object.
{
"customer":{
"id":"fd4f47a50c7f",
"email":"john@doe.com",
"firstname":"John",
"lastname":"Doe",
"company":"ACME Inc.",
"adr1":"810 Beach St",
"adr2":"Finance Dept",
"zip":"CA 94133",
"city":"San Francisco",
"countrycode":"US",
"phonenumber":"+14156226819",
"taxid":"US1234567890",
"note":"Always pays on time. Never late.",
"meta":{
"reference":123
}
}
}
PRO Tip
To make a customer invoiceable you need to provide a name or a company as well as a complete address with adr1, zip, city, and countrycode at a minimum.
| Key | Type | Description | Nullable | Mandatory |
|---|---|---|---|---|
customer{} |
object | The customer object to be included in the request. | false | mandatory |
.id |
string(12) | The customer's unique identifier as given by POST /customer. |
false | mandatory |
.email |
string | The customer's email address. | false | optional |
.firstname |
string | The customer's first name. | true | optional |
.lastname |
string | The customer's last name. | true | optional |
.company |
string | The customer's company name. | true | optional |
.adr1 |
string | The customer's first address line. Must be provided alongside zip, city, and countrycode |
true | optional |
.adr2 |
string | The customer's second address line. | true | optional |
.zip |
string | The customer's zip code. Must be provided alongside adr1, city, and countrycode |
true | optional |
.city |
string | The customer's city. Must be provided alongside adr1, zip, and countrycode |
true | optional |
.countrycode |
string | The customer's country as two character ISO code. Must be provided alongside adr1, zip, and city |
true | optional |
.phonenumber |
string | The customer's phone number. | true | optional |
.taxid |
string | The customer's tax id. Useful for accounting and invoicing purposes. | true | optional |
.note |
string | An arbitrary note associated with the customer. | true | optional |
.meta |
object | An arbitrary JSON object associated with the customer. Useful for storing additional reference information for later use. | true | optional |
{
"success": true
}
| Name | Type | Description | Nullable |
|---|---|---|---|
success |
boolean | Indicates that the request was processed successfully | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Deletes an existing customer object.
curl -X DELETE https://www.coinqvest.com/api/v1/customer \
-d "@payload.json"
Where payload.json is a JSON object.
{
"id":"fd4f47a50c7f"
}
| Key | Type | Description | Default | Mandatory |
|---|---|---|---|---|
id |
string(12) | Unique identifier as given by POST /customer. |
null | mandatory |
{
"success":true
}
| Name | Type | Description | Nullable |
|---|---|---|---|
success |
boolean | Indicates that request was processed successfully. | false |
{
"errors":[
"Service unavailable."
]
}
| Name | Type | Description | Nullable |
|---|---|---|---|
errors[] |
string[ ] | A list of strings explaining the error. | false |
Webhooks are responsible for posting information back to your server when certain events happen. Such events include completed payments or payment exceptions when the checkout was underpaid for example.
Webhooks are crucial if you want to automate certain workflows within your application as they enable you to trigger procedures, such as marking a customer checkout as completed and initiating the shipping of goods or services.
The webhook URL on your server is specified in your initial API call to POST /checkout or POST /checkout/hosted. When a webhook URL is present in your checkout configuration, our system automatically notifies you via an HTTP POST request to the given URL when certain events occur.
A webhook event is triggered and sends an HTTP POST request to your server when a checkout successfully completes (WEBHOOK checkout-completed) or an exception occurs, such as the customer underpaying (WEBHOOK checkout-underpaid). We'll be adding more webhook events in the future so check back often. You can see a find a list of webhook events in the menu on the left hand side.
A webhook is a standard HTTP POST request sent from us to your server. The request includes HTTP headers, which can help you verify that it was sent by us, and an HTTP body that contains the actual data payload, such as the webhook event type and associated information.
POST / HTTP/1.1
User-Agent: COINQVEST Webhook Engine 1.0.1
Host: www.merchant.com
Accept: */*
Content-Type: application/json
Connection: close
X-Webhook-Auth: 06b7ff792a30a172c51c163f666dd6908d85fdda78451b36de9f3f8e985412be
Content-Length: 532
{
"eventType": "CHECKOUT_COMPLETED",
"data": {...}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type. Different types have different payloads and you should implement a parser for each event type. Can currently be CHECKOUT_COMPLETED or CHECKOUT_UNDERPAID. |
false |
.data |
string |
An object containing the payload associated with this event type. Valid types are:
CHECKOUT_COMPLETED, CHECKOUT_UNDERPAID, UNDERPAID_ACCEPTED, REFUND_COMPLETED, DEPOSIT_COMPLETED.
|
false |
Webhook payloads differ between event types. Your system should inspect the eventType and implement a parser for each event type you want to support. At a minimum you should listen for WEBHOOK checkout-completed events.
Example: Parsing Based on Event Type (PHP)$payload = json_decode(file_get_contents("php://input"), true);
$type = $payload['eventType'];
$data = $payload['data'];
switch($type) {
case('CHECKOUT_COMPLETED'):
// do something when a checkout was successfully completed
break;
case('CHECKOUT_UNDERPAID'):
// do something when a checkout was underpaid
break;
case('UNDERPAID_ACCEPTED'):
// do something when an underpaid checkout was manually accepted
break;
case('REFUND_COMPLETED'):
// do something when a refund completed
break;
case('DEPOSIT_COMPLETED'):
// do something when a deposit completed
break;
break;
}
Add additional security to your endpoint and prevent spoofing by parsing the X-Webhook-Auth header and verifying its value.
Verify the request was sent by the COINQVEST platform by creating a hash hash('sha256', YOUR_API_SECRET . WEBHOOK_REQUEST_BODY) (where the . symbol represents concatenation) and matching it against the X-Webhook-Auth header value.
Example: Authentication Check (PHP)$authHeader = $_SERVER['HTTP_X_WEBHOOK_AUTH'];
$payload = file_get_contents("php://input");
if ($authHeader != hash('sha256', $yourApiSecret . $payload)) {
// this is not a valid webhook
}
Send 200 OK. Your server must respond with a status code of 200 in the HTTP response after it successfully parsed and persisted the webhook payload. Otherwise, our system will keep sending webhook requests for up to 48 hours in increasing intervals until we detect a 200 status code. If we don't receive an HTTP status code of 200 for longer than that, the webhook expires and stops posting.
PRO Tip
Inspect webhooks sent by COINQVEST along with your HTTP responses in the platform's webhook logs.
This can be extremely useful during implementation phase because it helps to debug issues in the HTTP requests and responses.
This webhook event is triggered when a customer payment successfully completed, your COINQVEST wallet was credited, and it is safe to ship any goods or services.
Please read the concepts to learn more about how to work with webhooks.
{
"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",
"sourceNetwork": "ETHEREUM",
"sourceNetworkName": "Ethereum",
"depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "ETHEREUM",
"networkName": "Ethereum",
"timestamp": "2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:42+00:00",
"tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
"amount":"10.0000000",
"amountAssetCode":"USD",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"T-Shirt",
"quantity":"1",
"netAmount":"10",
"productId":"yellow"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type (CHECKOUT_COMPLETED). Different types have different payloads and you should implement a parser for each event type, as documented here. |
false |
.data |
object | Contains an object of type checkout. |
false |
.checkout |
object | An object of type checkout with a COMPLETED state as documented in GET checkout |
false |
This webhook event is triggered when a customer payment was captured but the payment amount was less than expected. In this situation funds have not been credited to your account and you should not ship any goods or services yet.
Unresolved payments are listed in your UI dashboard and contain action options, such as issuing a refund or accepting the underpaid checkout by issuing a custom discount.
If this is a checkout of type HOSTED and you associated a customer with this checkout, our system automatically notifies the customer with instructions on how to complete checkout and pay the remaining difference.
If this is a checkout of type SELF-HOSTED or you did not associate it with a customer, you should notify your user to send another payment covering the difference between sourceAmountRequired and sourceAmountReceived. The payment should be sent to the same deposit address originally associated with this checkout.
Please read the concepts to learn more about how to work with webhooks.
{
"eventType":"CHECKOUT_UNDERPAID",
"data":{
"checkout":{
"id":"e905a6d2f9a4",
"timestamp":"2020-09-16T21:52:31+00:00",
"state":"UNRESOLVED_UNDERPAID",
"type":"HOSTED",
"origin":"API",
"settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
"settlementAmountRequired":"10.0000000",
"settlementAmountReceived":"0",
"settlementAmountFeePaid": "0",
"sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmountRequired":"0.0069543",
"sourceAmountReceived":"0.0010000",
"sourceNetwork": "ETHEREUM",
"sourceNetworkName": "Ethereum",
"depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "ETHEREUM",
"networkName": "Ethereum",
"timestamp": "2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"T-Shirt",
"quantity":"1",
"netAmount":"10",
"productId":"yellow"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type (CHECKOUT_UNDERPAID). Different types have different payloads and you should implement a parser for each event type, as documented here. |
false |
.data |
object | Contains an object of type checkout. |
false |
.checkout |
object | An object of type checkout with a UNRESOLVED_UNDERPAID state as documented in GET checkout |
false |
This webhook event is triggered when you manually accept an underpaid checkout via the COINQVEST platform UI or have automatic settlement of underpaid checkouts enabled in your account settings. In these events your account is credited a partial amount of the originally requested settlement amount.
The settlementAmountReceived attribute field provides the exact amount credited to your account. The sourceAmountRequired and sourceAmountReceived fields indicate by how much the checkout was underpaid.
Please read the concepts to learn more about how to work with webhooks.
{
"eventType":"UNDERPAID_ACCEPTED",
"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":"8.7260122",
"settlementAmountFeePaid": "0",
"sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmountRequired":"0.0069518",
"sourceAmountReceived":"0.0060000",
"sourceNetwork": "ETHEREUM",
"sourceNetworkName": "Ethereum",
"depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
"blockchainTransactions":[
{
"type":"ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network": "ETHEREUM",
"networkName": "Ethereum",
"timestamp": "2020-09-16T21:34:32+00:00",
"tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:37+00:00",
"tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
"amount":"0.0069518",
"amountAssetCode":"ETH",
"exception":null
},
{
"type":"SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network": "STELLAR",
"networkName": "Stellar",
"timestamp": "2020-09-16T21:34:42+00:00",
"tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
"amount":"10.0000000",
"amountAssetCode":"USD",
"exception":null
}
],
"payload":{
"charge":{
"lineItems":[
{
"description":"T-Shirt",
"quantity":"1",
"netAmount":"10",
"productId":"yellow"
}
],
"billingCurrency":"USD",
"customerId":"a2df67b61725"
},
"settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}
}
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type (UNDERPAID_ACCEPTED). Different types have different payloads and you should implement a parser for each event type, as documented here. |
false |
.data |
object | Contains an object of type checkout. |
false |
.checkout |
object | An object of type checkout with a COMPLETED state as documented in GET checkout |
false |
This webhook event is triggered when a refund was successfully completed.
Please read the concepts to learn more about how to work with webhooks.
{
"eventType":"REFUND_COMPLETED",
"data":{
"checkout":{
"id":"9476b254eff8",
"type":"REFUND",
"state":"COMPLETED",
"origin":"UI",
"context":"UNDERPAID_CHECKOUT",
"checkoutId":"9552e1c011fe",
"customerId":"3b25c712a52e",
"timestamp":"2020-11-18T00:37:05+03:00",
"sourceAssetCode":"ETH",
"sourceAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"sourceAmount":"0.0000000",
"targetAssetCode":"ETH",
"targetAssetIssuer":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
"targetAmount":"0.0105601",
"fee":"0.0010115",
"targetBlockchain":"ETH",
"transactionId":"9bea8240257448974c6067076c9f4d90c9505e69efaf130cb832d8dbb2083e77",
"targetAccount":{
"address":"0xA2Bf179E09C503262E418FC72261837726f68E36"
}
}
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type (REFUND_COMPLETED). Different types have different payloads and you should implement a parser for each event type, as documented here. |
false |
.data |
object | Contains an object of type refund. |
false |
.refund |
object | An object of type refund with a COMPLETED state as documented in GET refund |
false |
This webhook event is triggered when a deposit was successfully completed.
Please read the concepts to learn more about how to work with webhooks.
{
"eventType":"DEPOSIT_COMPLETED",
"data":{
"deposit":{
"id":"262785ce7dc1",
"type":"SWAP",
"state":"COMPLETED",
"origin":"API",
"createTime":"2021-05-14T15:53:14+00:00",
"completeTime":"2021-05-14T15:56:15+00:00",
"expireTime":"2021-05-14T16:53:14+00:00",
"sourceNetwork":"LITECOIN",
"sourceNetworkName":"Litecoin",
"depositAddress":"MUhBPBgjngzREm1NJfK3pUMTYSBDTx3v7X",
"sourceAmountRequired":"0.1",
"sourceAmountReceived":"0.1",
"sourceAmountMin":"0.1",
"sourceAmountMax":"0.1",
"sourceAssetIssuer":"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
"creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
"creditAmountGross":"32.2564553",
"creditAmountFee":"0.3282536",
"creditAmountNet":"31.9282017",
"creditAmountNetReceived":"31.9282017",
"blockchainTransactions":[
{
"type":"DEPOSIT_ORIGIN",
"typeDescription":"Blockchain payment transaction initiated by customer.",
"network":"LITECOIN",
"networkName":"Litecoin",
"timestamp":"2021-05-14T15:53:14+00:00",
"tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7eeaab614a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_TRANSFER",
"typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:19+00:00",
"tx":"5486e7e200acfb0a4dc1150e432ab9f716aa13b5982e08af78802a701e4d60c8",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_CONVERSION",
"typeDescription":"COINQVEST transaction converting source funds to target asset.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:24+00:00",
"tx":"2067ee5ddac84537596a35bfcea92f95ce5fe1e64d56f0435430775165c584a7",
"amount":"0.1000000",
"amountAssetCode":"LTC"
},
{
"type":"DEPOSIT_SETTLEMENT",
"typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
"network":"STELLAR",
"networkName":"Stellar",
"timestamp":"2021-05-14T15:53:29+00:00",
"tx":"5a8c6de913a5675d3a5b35890a5938c9b2a3f78ca6f1d61b3f67190bab955797",
"amount":"32.2564553",
"amountAssetCode":"USDC"
}
],
"customerId":"3b25c712a52e",
"meta":{
"external_id":"df2ae36472ac"
},
"failover":false,
"failoverType":null,
"failoverParentId":null,
"webhook":"https://www.your-server.com/path/to/webhook"
}
}
}
| Name | Type | Description | Nullable |
|---|---|---|---|
.eventType |
string | Indicates the webhook event type (DEPOSIT_COMPLETED). Different types have different payloads and you should implement a parser for each event type, as documented here. |
false |
.data |
object | Contains an object of type deposit. |
false |
.deposit |
object | An object of type deposit with a COMPLETED state as documented in GET deposit |
false |
PHP SDK Ruby SDK NodeJS SDK
Wordpress
WooCommerce
Shopify
Magento
Licensed and Regulated in the EU
© COINQVEST LLC 2018-2022 · Terms of Service · Privacy Policy · KYC/AML Policy · Anti-Fraud Policy · Data Processing · License
