Skip to main content

Settings

Getting list of merchant's settings​

This request allows you to view the list of available settings for crypto payments.

GET https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
SwaggerAPI documentationHow to get access tokenContact to support

Response example

{
  "merchantPreferences": [
    {
      "key": "auto-withdrawal",
      "value": true,
      "created_at": "2023-06-18T10:05:02.000000Z",
      "updated_at": "2023-06-23T15:54:09.000000Z"
    },
    {
      "key": "new-tx-manual-approve",
      "value": true,
      "created_at": "2023-05-29T11:29:31.000000Z",
      "updated_at": "2023-07-04T18:06:08.000000Z"
    },
    {
      "key": "callback-url",
      "value": "https://localhost.ru",
      "created_at": "2023-05-29T11:29:31.000000Z",
      "updated_at": "2023-07-04T18:06:08.000000Z"
    },
    {
      "key": "max-fee-limit-auto-withdrawal-btc",
      "value": 1000,
      "created_at": "2023-05-29T11:29:31.000000Z",
      "updated_at": "2023-07-04T18:06:08.000000Z"
    },
    {
      "key": "processing-fee-btc",
      "value": 5.5,
      "created_at": "2023-05-29T11:29:31.000000Z",
      "updated_at": "2023-07-04T18:06:08.000000Z"
    }
  ]
}
ParameterData typeDescriptionExample
callback-urlstringURL where data is sent when a new transaction is received or its status changeshttps://example.com
new-tx-manual-approveboolMerchant manual confirmation is required to confirm all new transactionstrue
auto-withdrawalboolEnable auto withdrawal to a cold wallettrue
auto-withdrawal-destination-{CODE}stringThe address of the cold wallet for auto withdrawal. Each currency has its own cold wallet0x0000000000000000000000000000000000000000
max-fee-limit-auto-withdrawal-{CODE}stringMaximum blockchain processing fee limit. If current network fee is above then max-fee-limit-auto-withdrawal-{CODE} then auto withdrawal will not be made1000
min-confirmation-{CODE} *intThe minimum number of blockchain blocks required to confirm a transaction and move it to the confirmed status6
min-amount-{CODE} *stringThe minimum amount of a transaction that a merchant can accept100000
processing-fee-{CODE} *floatProcessing fee in percents1

* - Configurable by manager

Set callback URL from personal area​

You can set callback through the settings in your account. To set a callback URL for crypto payments, you need to go to the settings in the Integration tab and add the URL in the field

img

Set callback URL through API​

At the current moment, only the callback URL for crypto payments can be set through the API. A request will be sent to this URL when the payment status changes.

PATCH https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "key": "callback-url",
    "value": "https://example.com/callback"
}
SwaggerAPI documentationHow to get access tokenContact to support

Type of invocies​

XAMAX uses several types of crypto invoices, which different from each other.

What types are there?​

To processing has beed added 3 types of crypto invocies:

  • static
  • revolver
  • user

User can set a different invoice types for each invoice created.

What is each type for?​

Invoice type: static

With this type of invoice, current and subsequent invoices are created for one invoice wallet, until the balance of this wallet reaches the rotation amount and the wallet is rotated.
After rotation, this wallet is no longer used and is deactivated. Funds sent to it will be lost after deactivation.

Invoice type: revolver

With this type of invoice, the current and each subsequent transaction will be created to a new invoice wallet, until the transaction status for one of the wallets is set to Complete, after which this wallet will return to the “issue” and a transaction will be created for it.
When a balance in the rotation amount is reached, the wallet data will be rotated.
After rotation, this wallet is no longer used and is deactivated. Funds sent to it will be lost after deactivation.

Invoice type: user

With this type of invoice, the current and subsequent transactions will be created to a new invoice wallet.

Peculiarities:

  • The wallet does not rotate automatically, there is no expiration time, that is, the wallet is eternal until it is forcibly rotated
  • You can make multiple requests with the same code and txID and get the same wallet
  • Funds are withdrawn from the wallet when they reach the value from the wallet-rotate-amount-${CODE} setting
  • The merchant’s client can send any amount,not lower than the minimum value.

In this type of invoice, an invoice is created for the user (payer) and the user data can constantly interact with this invoice.

How to set invoice type by default?​

The user can set a default value for all created invoices using various options.

PATCH https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "key": "default-invoice-type",
    "value": "user"
}
SwaggerAPI documentationHow to get access tokenContact to support

How to create invoice by default type?​

After set of the setting and create new invoice may indicate in the request body:

POST https://api.xamax.io/v1/transaction/invoice HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "txId":"1",
  "code": "eth",
  "amount": "1000000000000000000",
  "type": "invoice_type_default"
}

Minimum number of blockchain confirmations​

The minimum number of blockchain blocks required to confirm a transaction and move it to the confirmed status.

It is configured for each cryptocurrency individually due to the name of the blockchain in the key. You need to specify cryptocurrency code {CODE}, for example btc

PATCH https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "key": "processing-fee-btc",
    "value": "6"
}
SwaggerAPI documentationHow to get access tokenContact to support

Auto approve transaction confirmation​

In some cases, when the payer sent funds to a previously received wallet, and an invoice has not been created, then for this operation, by default, the status will be set to “Approve Required”. When this setting is disabled, the XAMAX User must accept or reject the incoming transaction manually, in the XAMAX personal account.

When this setting is enabled, unidentified transactions will be automatically accepted.
The setting is switch off, by default

PATCH https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "key": "tx-manual-auto-approve",
    "value": "true"
}
SwaggerAPI documentationHow to get access tokenContact to support

Manual transaction confirmation​

Merchant manual confirmation is required to confirm all new transactions. All new transactions will come with the status approved_required

PATCH https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "key": "new-tx-manual-approve",
    "value": "true"
}
SwaggerAPI documentationHow to get access tokenContact to support

In case, if You've some restristions by location or countries, You can set restrictions for these list of countries. We'll be check of country(location) by IP address of client

POST https://api.xamax.io/v1/merchant/preferences HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "preferences": [
    {
      "key": "restricted-country-list",
      "value": "[\"AF\", \"AU\"]"
    }
  ]
}
Parametres
  1. key - restricted-country-list
  2. value* - list of countries, for users which we should to return information about unsupported the country

* - The value is passed as an escaped json array, example [\"AE\", \"AD\", \"AF\"], all quotes are preceded by a slash