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