openapi: 3.1.1
info:
title: 'Changelly Pay API'
version: ''
x-logo:
url: /images/logo.png
altText: Logo
description: |
# Overview
Changelly Pay is a reliable cryptocurrency payment solution, operating on a
C2C (crypto-to-crypto) model, engineered to simplify transactions for merchants
across a variety of goods. Integrating our API allows merchants to accept a wide
range of cryptocurrencies for their goods or services with ease.
The Changelly Pay API makes integrating cryptocurrency payments into your
business straightforward. It enables customers to pay directly from their
computer or mobile device, using the blockchain as the settlement network.
With Changelly Pay, there's no need to build and maintain infrastructure to
monitor the blockchain. We create payment addresses for you, and continuously
monitor the blockchain to identify when payments have been made.
# Coins
Specify the combination of `currency` and `network` codes from ones below:
| Currency code | Currency Name | Network code | Network name | Network protocol |
|---------------|-----------------------|--------------|---------------------|------------------|
| 1INCH | 1INCH | ETH | Ethereum | ERC-20 |
| AAVE | Aave | ETH | Ethereum | ERC-20 |
| ADA | Cardano | ADA | Cardano | ADA |
| ALGO | Algorand | ALGO | Algorand | ALGO |
| APE | ApeCoin | ETH | Ethereum | ERC-20 |
| ATOM | Cosmos | ATOM | Cosmos | ATOM |
| AVAX | Avalanche | AVAX | Avalanche X-Chain | AVAX |
| AVAX | Avalanche | AVAC | Avalanche C-Chain | AVAC |
| AXS | Axie Infinity | ETH | Ethereum | ERC-20 |
| BCH | Bitcoin Cash ABC | BCH | Bitcoin Cash | BCH |
| BLUR | Blur | ETH | Ethereum | ERC-20 |
| BNB | Binance Coin | BSC | Binance Smart Chain | BSC |
| BTC | Bitcoin | BTC | Bitcoin | BTC |
| CELO | Celo | CELO | Celo | CELO |
| CHZ | Chiliz | ETH | Ethereum | ERC-20 |
| COMP | Compound | ETH | Ethereum | ERC-20 |
| CORE | Core DAO | CORE | Core DAO | CORE |
| CRV | Curve DAO Token | ETH | Ethereum | ERC-20 |
| CSC | CasinoCoin | XRP | Ripple | TOKEN |
| CVX | Convex Finance | ETH | Ethereum | ERC-20 |
| DAI | Dai | ETH | Ethereum | ERC-20 |
| DASH | Dash | DASH | Dash | DASH |
| DOGE | Dogecoin | DOGE | Dogecoin | DOGE |
| DOT | Polkadot New | DOT | Polkadot | DOT |
| DYDX | dYdX | DYDX | dYdX | DYDX |
| EGLD | MultiversX | EGLD | MultiversX | EGLD |
| ENJ | Enjin Coin Mainnet | ENJ | Enjin | ENJ |
| EOS | EOS | EOS | EOS Network | EOS |
| ETH | Ethereum | ETH | Ethereum | ETH |
| FIL | Filecoin | FIL | Filecoin | FIL |
| GALA | Gala | ETH | Ethereum | ERC-20 |
| GMX | GMX | AVAC | Avalanche C-Chain | ERC-20 |
| GNO | Gnosis | ETH | Ethereum | ERC-20 |
| GRT | The Graph | ETH | Ethereum | ERC-20 |
| HBAR | Hedera Hashgraph | HBAR | Hedera | HBAR |
| HMSTR | Hamster Kombat | TON | Toncoin | JETTON |
| ICP | Internet Computer | ICP | Internet Computer | ICP |
| IMX | Immutable X | ETH | Ethereum | ERC-20 |
| INJ | Injective Protocol | INJ | Injective Protocol | INJ |
| IOTX | IoTeX | IOTX | IoTeX | IOTX |
| KAVA | Kava | KAVA | Kava | KAVA |
| KSM | Kusama | KSM | Kusama | KSM |
| LDO | Lido DAO Token | ETH | Ethereum | ERC-20 |
| LIME | iMe Lab | BSC | Binance Smart Chain | BEP-20 |
| LINK | Chainlink | ETH | Ethereum | ERC-20 |
| LRC | Loopring | ETH | Ethereum | ERC-20 |
| LTC | Litecoin | LTC | Litecoin | LTC |
| MANA | Decentraland | ETH | Ethereum | ERC-20 |
| MELANIA | Official Melania Meme | SOL | Solana | SPL |
| NEAR | NEAR Protocol | NEAR | Near | NEAR |
| NEXO | Nexo | ETH | Ethereum | ERC-20 |
| NOT | Notcoin | TON | Toncoin | JETTON |
| OMG | OMG Network | ETH | Ethereum | ERC-20 |
| OP | Optimism | OP | Optimism | ERC-20 |
| POL | Polygon (ex-MATIC) | ETH | Ethereum | ERC-20 |
| POL | Polygon (ex-MATIC) | POLYGON | Polygon (Matic) | POLYGON |
| QNT | Quant (QNT) | ETH | Ethereum | ERC-20 |
| QTUM | QTUM | QTUM | Qtum | QTUM |
| RVN | Ravencoin | RVN | Ravencoin | RVN |
| SAND | The Sandbox | ETH | Ethereum | ERC-20 |
| SFP | SafePal | BSC | Binance Smart Chain | BEP-20 |
| SHIB | SHIBA INU | ETH | Ethereum | ERC-20 |
| SOL | Solana | SOL | Solana | SOL |
| SUI | SUI | SUI | Sui | SUI |
| SUSHI | SushiSwap | ETH | Ethereum | ERC-20 |
| SXP | Solar mainnet | SXP | Solar | SXP |
| THETA | THETA | THETA | Theta Network | THETA |
| TON | Toncoin | TON | Toncoin | TON |
| TRUMP | OFFICIAL TRUMP | SOL | Solana | SPL |
| TRX | TRON | TRX | Tron | TRX |
| TWT | Trust Wallet Token | BSC | Binance Smart Chain | BEP-20 |
| UNI | Uniswap | ETH | Ethereum | ERC-20 |
| USDC | USD Coin | ARB | Arbitrum One | ERC-20 |
| USDC | USD Coin | AVAC | Avalanche C-Chain | ERC-20 |
| USDC | USD Coin | BASE | Base | ERC-20 |
| USDC | USD Coin | BSC | Binance Smart Chain | BEP-20 |
| USDC | USD Coin | ETH | Ethereum | ERC-20 |
| USDC | USD Coin | NEAR | Near | NEP141 |
| USDC | USD Coin | OP | Optimism | ERC-20 |
| USDC | USD Coin | POLYGON | Polygon (Matic) | ERC-20 |
| USDC | USD Coin | SOL | Solana | SPL |
| USDC | USD Coin | XLM | Stellar | TOKEN |
| USDT | Tether | AVAC | Avalanche C-Chain | ERC-20 |
| USDT | Tether | BSC | Binance Smart Chain | BEP-20 |
| USDT | Tether | ETH | Ethereum | ERC-20 |
| USDT | Tether | NEAR | Near | NEP141 |
| USDT | Tether | SOL | Solana | SPL |
| USDT | Tether | TON | Toncoin | JETTON |
| USDT | Tether | TRX | Tron | TRC-20 |
| USDT | Tether | XTZ | Tezos | FA2 |
| VENOM | Venom | VENOM | Venom chain | VENOM |
| VET | VeChain | VET | VeChain Network | VET |
| WAVES | Waves | WAVES | WAVES | WAVES |
| XEC | eCash | XEC | eCash | XEC |
| XEM | NEM | XEM | NEM | XEM |
| XLM | Stellar | XLM | Stellar | XLM |
| XMR | Monero | XMR | Monero | XMR |
| XRP | Ripple | XRP | Ripple | XRP |
| XTZ | Tezos | XTZ | Tezos | XTZ |
| XYM | Symbol | XYM | Symbol | XYM |
| YFI | yearn.finance | ETH | Ethereum | ERC-20 |
| ZEC | Zcash | ZEC | Zcash | ZEC |
| ZIL | Zilliqa | ZIL | Zilliqa | ZIL |
| ZRX | 0x Protocol | ETH | Ethereum | ERC-20 |
Note: [Get currencies](#tag/Currencies/operation/getCurrencies) to determine the
exact current list of supported coins.
Send us a request to add new coins.
# Fees
## Payment Network Fee
Fixed fee determined based on the deposit currency used by the customer. Once
the funds are received, the fee is applied regardless of the amount deposited.
If the customer deposits in a different currency (such as BTC), the deposit fee
will be taken in that currency before any conversion to the target currency
(like USDT) takes place.
## Payment Processing Fee
Determined by commercial terms and calculated using equations.
If the payment does not involve exchange (holding and nominal currencies are the
same):
**Payment fee** =
**Payment fee %** · (**Payin amount** - **Payment Network Fee**),
where \
**Payment fee %** — the percentage in accordance with the commercial terms for
payments without exchange \
**Payin amount** — the size of the client's deposit (how much the client sent in
funds \
**Payment Network Fee** — the amount of the network fee depending on the coin
and network used by the client if the payment involves an exchange
For example, if the payment is direct:
* a deposit of X USDT has been received
* deposit fee (`payins.fee`) is deducted in USDT (e.g. 0.005 USDT)
* from the remaining amount, a processing fee (`payment_fee`) is charged as a
percentage, which is 0.5% for direct payments
Therefore, the total amount credited to the merchant's balance is:
0.5% · (X - 0.005)
If the payment involves exchange (holding and nominal currencies are different):
**Payment fee** =
**Rate** · **Payment fee %** · (**Payin amount** - **Payment Network Fee**)
where \
**Payment fee %** — the percentage in accordance with the commercial terms for
payments involving an exchange \
**Rate** — the exchange rate between the coin the client is paying with and the
one that will be received in the merchant's balance \
**Payin amount** — the amount of the client's deposit (how much the client sent
in funds) \
**Payment Network Fee** — the amount of the network fee depending on the coin
and network used by the client if the payment involves an exchange
None: Fees may be considerably high of even exceed the sum as the result of an
exchange.
For example:
* a deposit of X BTC has been received
* deposit fee (`payins.fee`) is deducted in BTC (e.g. 0.000025 BTC)
* the remaining amount is then converted to USDT:
(X - 0.000025) · 67158.2646977895 = Y USDT
* from the USDT amount, a processing fee (`payment_fee`) is charged as a
percentage, which is 0.8% for exchange payments.
Therefore, the total amount credited to the merchant's balance is:
0.8% * Y
## Fee payer
### Invoices
For invoices, the `fees_payer` parameter significantly impacts the total amount
the user sees and is required to send. Unlike deposits, where the nominal amount
credited to the user may differ from the actual amount sent, invoices present a
fixed sum that the user must pay, which includes any applicable transaction
fees.
For example, if an invoice is for 100 USDT (TRC20) and the transaction fee
is 1 USDT:
* `fees_payer` = `MERCHANT`: The user will see an invoice for 100 USDT, and
they will send 100 USDT to the merchant. After deducting the fee, the
merchant will receive 99 USDT in their balance.
* `fees_payer` = `CUSTOMER`: The user will see an invoice for 101 USDT
(100 USDT for the invoice plus 1 USDT for the fee), and they will send
101 USDT to the merchant. In this case, the merchant will receive the full
100 USDT for the invoice, as the customer covers the transaction fee.
In both scenarios, the amount credited to the merchant's balance differs based
on who pays the transaction fee. The key difference is that the user sees a
fixed sum to send, which varies depending on whether the merchant or the
customer is responsible for the transaction fee.
### Deposits
For deposits, the `fees_payer` parameter primarily affects the calculation of
the nominal amount credited to the user. However, it does not influence the
actual amount sent by the user to the address.
For example, if a user sends 100 USDT (TRC20) with a transaction fee
of 1 USDT and the nominal currency is USD ($):
1. `fees_payer` = `MERCHANT`: The nominal amount credited to the user will be
$100, while the merchant will receive 99 USDT in their balance after
deducting the fee.
1. `fees_payer` = `CUSTOMER`: The nominal amount credited to the user will be
$99, and the merchant will also receive 99 USDT in their balance.
In both scenarios, the amount credited to the merchant's balance remains the
same (99 USDT). The only difference lies in how much the merchant chooses to
credit the user, depending on whether they cover the transaction fee or not. If
the merchant covers the fee, the user receives the full nominal amount. If the
customer covers the fee, the nominal amount credited to the user is reduced by
the fee.
## Swap fee
There're 2 ways exchanges can occur:
* via the dashboard (also can be done with [Swaps](#tag/Swaps)
* automatically during a withdrawal
In both cases we charge a fee that is defined by commercial and market
conditions. That is withhold in the target currency (one to which an exchange is
being made).
For example: if the commercial fee in the dashboard is 1$, and you exchange USDT
to USDC:
**Swap Fee** = **Swap Fee %** · **Rate** · **Amount From**,
where \
**Swap Fee** — calculated and hold in USDC \
**Swap fee %** — commercial fee equal 1% \
**Rate** — exchange rate from USDT to USDC \
**Amount From** — the sum exchanged
## Withdrawal fee
The network fee for withdrawals is always taken in the withdrawn cryptocurrency.
This fee depends on the state of the network and therefore changes over time.
For example, the withdrawal fee for USDT on the TRX network and USDT on the ETH
network will differ, as the networks are different; however, in both cases, the
fee will be deducted in USDT.
The processing fee for withdrawals is set as a percentage and depends on
commercial terms.
If the withdrawal involves an exchange, it essentially consists of two
sequential actions: the exchange and the withdrawal. Accordingly, the exchange
fee will first be deducted in the target currency, followed by the withdrawal
fee for the target currency.
# Support
Changelly Pay provides a support option.
In case of any technical issues, difficulties during the integration process, or
other concerns, you can contact the support team at
[support@pay.changelly.com](support@pay.changelly.com).
## Refunds
In general in case of delayed or missing payins:
* wait for the refund to occur and then manually provide the service to their
customer
* offer the service manually to the customer for the underpaid amount
received, while the balance is later adjusted when the finance team
processes the refund
If payin is missing and the customer has proved they had actually committed a
payin by providing a transaction hash, contact the support team and attach:
* `customer_id`
* currency code (`currency`)
* network code (`network`)
* transaction hash
* screenshots
* the preferred method for processing a refund (if applicable): either to your
merchant balance or back to the buyer. If the refund is to be returned to
the buyer, please provide a convenient address for them to receive it
Note: If a payment is not completed, it does not necessarily mean it won't be
completed later. Please refrain from making manual transfers until we confirm
that the payment will not be completed.
Average ETA for refund is 5 days but may vary.
# Payments
There're the following types of payments:
* [deposits](#section/Deposits)
* [deposits with recommended amount](#section/Recommended-Amount)
* [invoices](#section/Invoices)
* [deposits to a static address](#section/Static-addresses)
## Payment deadline
To set the expiration date for a payment, include `pending_deadline_at` in a new
payment request. Once the payment expires, a customer visiting the checkout page
will see the message "Your link has expired," indicating that the initiated
payment has been canceled and can no longer be processed.
Note: This deadline cannot exceed the one determined by us (`deadline_at`).
# Deposits
One-off payments of an unspecified amount, i.e. the first crypto payin made to a
dynamic deposit address that exceeds the minimal boundary
(`minimum_payin_amount`).
Note: Your users must be informed that they access deposit addresses for limited
time only—it may eventually be allocated to another user or go out of the
address pool.
## Recommended Amount
Although deposits don't have nominal amount, you can set recommended sum and get
it recalculated for a given payment method. The customer will see this amount to
be sent which isn't mandatory.
Note: If the payin amount is insufficient to cover fees, it will fail.
Otherwise, it results in a successful payment regardless of the recommended
amount.
There are two options of how to display expected amount:
* our checkout page
* own frontend
## Our Checkout Page
Pass `recommended_amount.nominal` and type equal `DEPOSIT` in a new payment
request.
Expected price for the chosen payment methods will be displayed to the customer
on the checkout page (`payment_url`).
After the customer sends a payin, we send a callback with actual arrived amount
given the fees. This sum will be credited to your holding account.
## Own Frontend
Send a payment request with type equal `DEPOSIT`.
Get the expected amount for a given payment method and nominal amount (i.e.
recommended amount) in `expected_payin_amount`.
Display this sum to the customer of your frontend. Note that exchange rates can
be volatile causing this sum to change over time. Repeat requests to keep it up
to date.
We cannot decline payments based on the recommended price. To be able handle
underpayment, keep a record of the recommended price and the actual payment
amount arrived in the last successful callback. For example:
* scale amount of provided services
* scale the period of service
* credit bonuses instead of services
* offer a refund
You can use difference between the actual sum and the recommended one in the
following way:
* prolong customer plan
* credit bonuses
* offer a refund
# Invoices
This payment method is ideal for purchasing goods with a fixed price tag. Upon
payment, you'll receive a notification—a callback, which provides the status,
payment amount, and hash.
* If the payment isn't made, a `CANCELED` status will be sent.
* If the exact amount is paid, a `COMPLETED` status will be sent.
* If a lesser amount is sent, a `FAILED` status will be sent.
Customers have the option to cover the remaining amount within the payment
expiration time frame.
On the payment page, customers will be alerted about any additional amount due.
If the balance isn't covered, a callback with a `FAILED` status and details will
be sent upon invoice expiration.
To allow underpayment, specify its relative or absolute maximum value in the
cabinet (**Orders** > **Create new order** > **Advanced settings**) or in a
payment request (`underpayment_config` field).
You can set the maximum underpayment allowed from your customers due to crypto volatility.
The more restrictive of the thresholds will be applied for each payment.
Your customers will not see these thresholds.
To allow overpayment, specify its relative or absolute maximum value in the
cabinet (**Orders** > **Create new order** > **Advanced settings**) or in a
payment request (`overpayment_config` field).
You can set the maximum overpayment allowed from your customers due to crypto volatility.
The more restrictive of the thresholds will be applied for each payment.
Your customers will not see these thresholds.
# Static addresses
Static addresses are perfect for accepting multiple deposits from a single user
—for example, topping up the balance. This address is associated with a certain
customer and can be used for a long period of time.
However, we can revoke an address if not detecting incoming transactions for a
long time (to find out the current period, ask our support team). It means each
payin prolongs address availability for certain period. This period extends to
all merchants and counts for the combination of customer, currency, and network.
Another reason you would wish to sync address info is the fact networks change
its state and parameters between payments. When request a new address you get
network `minimum_payin_amount` and determine if payins are not suspended
(`payin_enabled` equal `false`)—if they are, we return a validation error.
To prevent misdirected payins, never store the address on your side—instead,
invoke allocation of a new address each time when displaying it to the user. You
will receive the same address and an indication it hasn't changed
(`new_address_generated` equal `false`) if the address still reserved for a
customer. Otherwise, we allocate a new address and send a flag indicating that
(`new_address_generated` equal `true`).
Single address is never shared across multiple payins. If the goal is to keep
getting payins from the same customer over a relatively prolonged period of
time, prefer allocating a static deposit address over committing deposits. After
a payin to the static address is received, it will be automatically credited to
merchant balance and the deposit callback will be sent.
### VM compatibility
We support static addresses with cross-chain mapping, as on the table below.
This means that once you create a deposit address with a designated "managing
coin" on a specific blockchain, you can receive any token supported within that
ecosystem at that one address.
For example, if you create an Ethereum deposit address, you can receive ETH,
USDT (as an ERC‑20 token), USDC, and some other ERC‑20 tokens. The same
principle applies to a few other networks: Solana, Tron, and TON.
So if TRX is sent to a static deposit address set up for USDT on the Tron
network, our system will correctly map the transaction, ensuring that the funds
are accurately credited. In contrast, one-time payment addresses lack this
mapping functionality and may lead to unidentified or misdirected deposits.
| Currency (network) | Managing network |
|--------------------|------------------|
| ETH (ETH) | ETH |
| USDT (AVAC) | ETH |
| USDT (BSC) | ETH |
| USDT (ETH) | ETH |
| USDC (ARB) | ETH |
| USDC (BSC) | ETH |
| USDC (ETH) | ETH |
| BNB (BSC) | ETH |
| POL (ETH) | ETH |
| POL (POLYGON) | ETH |
| — | — |
| SOL (SOL) | SOL |
| USDC (SOL) | SOL |
| USDT (SOL) | SOL |
| — | — |
| TRX (TRX) | TRX |
| USDT (TRX) | TRX |
| — | — |
| TON (TON) | TON |
| USDT (TON) | TON |
| NOT (TON) | TON |
# Withdrawals
Allows users to withdraw their funds to an external crypto wallet.
See the [Withdrawals](/#tag/Withdrawals) section.
## Idempotency
When you repeat an operation using the same idempotency key (`idempotency_key`),
the system will return the result obtained from the previous call, even if the
request fields have changed. This may lead to confusion.
Idempotency key usage rules:
* If you repeat a request with the same `idempotency_key`, the same result
that was returned previously will be provided.
* To create a new operation, a new `idempotency_key` must be used.
Please follow these guidelines to avoid misunderstandings when working with the
system.
# Authentication
In each call, the merchant provides the following credentials:
* API key (a public key that identifies the combination of merchant and
project)
* signature (basically, the request payload signed by a private key)
The **Integrations** page contains the list of API keys and the callback
configuration.
This page allows creating, editing, and deleting API keys and modifying the
callbacks' configuration.
## API keys
All requests detected from the merchant to us must contain the header
`X-Api-Key` with an API key (i.e., public key) unique to a project.
API keys do not affect reporting in any way (the key associated with a
payment, withdrawal, etc., is not indicated). The primary purpose of having
multiple API keys is to assign different access rights (permissions): one key
may be allowed to make withdrawals, while another may not, and so on.
In [the cabinet](app.pay.changelly.com):
1. Click **Integrations** in the sidebar
1. In the **API Keys** section, click **Generate API Key**
1. In the **Create API Key** pop-up, enter a title
1. Configure permissions.
1. Enter a 2FA code
1. Click **Continue**
1. Click **Copy** icon next to the generated public and private keys or scan QR
codes
1. Click **I saved Private Key, continue**
1. Save the keys in a secure storage
## Sign a request
In addition to an API key, each request directed to us must contain a signature.
The signature should be passed via `X-Signature` header and be formed as
follows:
1. Create a payload using the request data and desired expiration timestamp:
`PAYLOAD` = `METHOD` + `":"` + `PATH` + `":"` + [EncodeBase64(`BODY`)] + `":"` + `TIMESTAMP`,
where\
`METHOD`—an HTTP method, for example: `"POST"`,\
`PATH`—call URL, for example: `"/api/payment/v1/payments"`,\
`BODY`—request JSON payload stored in a string. Must always be provided,\
`TIMESTAMP`—expiration UNIX timestamp in seconds.
1. Generate a hash from the payload and sign it with the private key and
serialize it:
`SIGNATURE` = EncodeBase64(RSASign(SHA256(`PAYLOAD`), `PRIVATE_KEY`)),
where\
`PRIVATE_KEY`—the private key from the API key with PEM delimiters,\
EncodeBase64()—encoding with Base64 algorithm (RFC 4648 compatible),\
RSASign()—signing the SHA-256 hash with the private key (PKIX format is
suggested),\
SHA256()—generating an SHA-256 hash from the request payload.
1. Append the expiration timestamp to the signature and serialize the
result:
EncodeBase64(`SIGNATURE` + `":"` + `TIMESTAMP`),
where\
`SIGNATURE`—an SHA-256 hash signed with the private key.
1. Put the resulting sequence to the `X-Signature` header of the request
Note:
* Request body is always a string and cannot be transmitted as a programming
language structure.
* Operation of hashing and signing from step 2 are normally executed in a
single command.
**Node.js:**
```js
/**
* Signs a request payload using an RSA private key and sends it to the server.
*
* @param {string} privateKey - The base64-encoded RSA private key.
* @param {string} method - The HTTP method of the request (e.g. 'POST', 'GET').
* @param {string} path - The API endpoint path (e.g. '/api/payment/v1/payments').
* @param {object} bodyRaw - The raw request body data (e.g. an object with a nominal currency
and amount).
* @param {number} window - The time period before the expiration in seconds.
* @param {string} BASE_URL - The base URL of the API endpoint.
* @param {string} PUBLIC_KEY - The X-API-Key for authentication.
*/
function sendRequestWithRSASigning(privateKey, method, path, bodyRaw, window, BASE_URL,
PUBLIC_KEY) {
// Request body
let bodyJSON = JSON.stringify(bodyRaw);
// Check if no body provided
// Body must be always present in the payload even as an empty string
let body = bodyJSON != '{}'
? Buffer.from(bodyJSON)
.toString('base64')
: '';
// Time period before the expiration in seconds
let timestamp = Math.floor(Date.now() / 1000) + window;
// Request payload
let payload = [
method,
path,
body,
timestamp
]
.join(':');
// Sign a SHA256 payload hash with the RSA private key
let signature = Buffer.from(
[
crypto.sign('RSA-SHA256', payload, privateKey)
.toString('base64'),
timestamp
]
.join(':')
)
.toString('base64');
// Send a request
let resource = BASE_URL + path;
let options = {
method: method,
headers: {
'X-Api-Key': PUBLIC_KEY,
'X-Signature': signature,
'Content-Type': 'application/json'
},
body: bodyJSON
};
return fetch(resource, options)
.then(response => response.json())
.catch(error => error);
}
```
**Example usage:**
```js
const crypto = require('crypto');
const privateKey = `
-----BEGIN PRIVATE KEY-----
${'your-private-key'}
-----END PRIVATE KEY-----
`;
const method = 'POST';
const path = '/api/payment/v1/payments';
const bodyRaw = {
nominal_currency: 'USDT',
nominal_amount: '14.08'
};
const window = 3600; // 60 minutes
const BASE_URL = 'api.pay.changelly.com';
const PUBLIC_KEY = 'your-public-key';
sendRequestWithRSASigning(privateKey, method, path, bodyRaw, window, BASE_URL, PUBLIC_KEY)
.then(response => console.log(response))
.catch(error => console.error(error));
```
# Callbacks
For keeping track of the payment state, a merchant solution catches our
callbacks arriving to a specified URL.
In [the cabinet](app.pay.changelly.com):
1. Click **Integrations** on the sidebar
1. In the **Callback URL configuration** section, click
**Set up Callback URL**
1. In the **Set up Callback URL** pop-up, enter a callback URL
1. Click **Save**
1. Click **Copy** icon next to the generated callback public key
1. Save the callback public key in a secured storage
## Testing
After a callback URL is set to, to send a test callback from
[the cabinet](app.pay.changelly.com):
1. Click **Integrations** on the sidebar
1. In the **Callback URL configuration** section, click
**Send a test callback**
1. Choose either a payment or withdrawal callback
1. Depending on how you handle the callback, the result pop-up will show up.
## Verify signature
We generate our callback request signatures in the same manner as merchants do
for their outgoing calls. As a server, a merchant solution must be capable of
verifying these signatures.
These signatures can be found in the `X-Signature` header and are all created
using the same process.
For keeping track of the payment state, catch our callbacks arriving to a
specified URL:
1. Click **Integrations** in the sidebar
1. In the **Callback URL configuration** section, click
**Set up Callback URL**
1. In the **Set up Callback URL** pop-up, enter a callback URL
1. Click **Save**
1. Click **Copy** icon next to the generated callback public key
1. Save the callback public key in a secured storage
To verify a signature, perform the following common steps:
1. De-serialize the signature sequence.
1. Split the resulting string by the semicolon and extract the first entry
of resulting array:
EncodeBase64(`SIGNATURE`) + `":"` + `TIMESTAMP` = DecodeBase64(`X-Signature`),
where\
DecodeBase64()—decoding with Base64 algorithm.
1. Append PEM delimiters to the callback public key copied in the cabinet.
1. Recreate the payload by concatenating the JSON body and the expiration
timestamp:
`PAYLOAD` = `BODY` + `":"` + `TIMESTAMP`
1. Generate an SHA-256 hash from the payload:
SHA256(`PAYLOAD`)
1. Verify the resulting hash against the provided signature using our public
key and the payload.
**Node.js:**
```js
/**
* Verifies a callback signature.
* @param {string} body - Request JSON body.
* @param {string} signatureHeader - The `X-Signature` header.
* @param {string} callbackPublicKey - The public key used for verification.
* @returns {boolean} The result of signature verification.
*/
const verifyCallbackSignature = (body, signatureHeader, callbackPublicKey) => {
// Append PEM delimiters
const publicKey = `
-----BEGIN PUBLIC KEY-----
${callbackPublicKey}
-----END PUBLIC KEY-----
`;
if (!signatureHeader) {
return false;
}
let [signature, timestamp] = Buffer
.from(signatureHeader, 'base64')
.toString('utf8')
.split(':');
signature = Buffer.from(signature, 'base64');
let payload = Buffer.from(`${body}:${timestamp}`);
return crypto.verify('RSA-SHA256', payload, publicKey, signature);
};
```
**Example usage:**
```js
const isValid = verifyCallbackSignature(
requestBody,
requestSignatureHeader,
CALLBACK_PUBLIC_KEY
);
```
## Retry policy
If your app couldn't handle a callback, we consequently resend it the following
way:
* 5 times in 1 minute
* 5 times in 5 minutes
* 5 times in 30 minutes
* 5 times in 5 hours
* 5 times in 24 hours
# CMS plugins
You can easily integrate our payment gateway into your existing site using our
ready-made CMS plugins. We currently support Shopify, WooCommerce, Wix, and
more.
Browse all available plugins here:
[app.pay.changelly.com/plugins](https://app.pay.changelly.com/plugins)
tags:
- name: Currencies
description: |
Currency and network details.
- name: Balances
description: |
Holding account balance details.
- name: Swaps
description: |
Instant exchanges.
- name: Withdrawals
description: |
Managing withdrawals from the holding account.
- name: Addresses
description: |
Managing static addresses for direct deposits.
- name: Payments
description: |
Managing new payments.
The primary API endpoint for all production environment requests is
`api.pay.changelly.com`.
To interact with the Changelly Pay API, you will need to obtain API keys
for authentication.
- name: On-Ramp
description: |
Information for fiat on-ramp payment methods.
- name: Callbacks
description: Payment state callbacks.
x-tagGroups:
- name: API Reference
description: |
This specification contains methods of interactions between a merchant and
our system, meaning that the merchant implements corresponding logic on
their solution and sends calls described below.
tags:
- Currencies
- Balances
- Swaps
- Withdrawals
- Addresses
- Payments
- On-Ramp
- Callbacks
servers:
- url: /api/payment/v1
paths:
/currencies:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
get:
tags:
- Currencies
operationId: getCurrencies
summary: Get currencies
description: |
Use it:
* to get the minimum payin amount
* to get supported currencies and networks
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
ℹ️ `minimum_payin_amount` pertains to payments that involve an exchange.
It represents the minimum amount required when a payment involves a
swap.
ℹ️ `minimum_direct_payin_amount` represents the minimum amount required
for payments that do not involve an exchange.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
additionalProperties:
x-additionalPropertiesName: currency
$ref: '#/components/schemas/payments_resCurrency'
example:
USDT:
name: Tether
code: USDT
crypto: true
precision: 6
priority: 1
crypto_explorer: http://omniexplorer.info/lookuptx.aspx?txid={tx}
networks:
- name: Avalanche C-Chain
code: AVAC
protocol: ERC-20
managing_coin:
currency: ETH
network: ETH
precision: 18
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.043451'
minimum_direct_payin_amount: '0.044'
- name: Binance Smart Chain
code: BSC
protocol: BEP-20
managing_coin:
currency: ETH
network: ETH
precision: 18
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.054451'
minimum_direct_payin_amount: '0.055'
crypto_explorer: https://bscscan.com/tx/{tx}
- name: Bitcoin
code: BTC
protocol: OMNI
precision: 8
payin_enabled: false
payout_enabled: false
minimum_payin_amount: '0.999451'
minimum_direct_payin_amount: '0'
- name: Ethereum
code: ETH
protocol: ERC-20
managing_coin:
currency: ETH
network: ETH
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '14.199451'
minimum_direct_payin_amount: '13.2'
crypto_explorer: https://etherscan.io/tx/{tx}
- name: Near
code: NEAR
protocol: NEP141
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.065451'
minimum_direct_payin_amount: '0.066'
- name: Solana
code: SOL
protocol: SPL
managing_coin:
currency: SOL
network: SOL
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.329451'
minimum_direct_payin_amount: '0.33'
crypto_explorer: https://solscan.io/tx/{tx}
- name: Toncoin
code: TON
protocol: JETTON
managing_coin:
currency: TON
network: TON
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.494451'
minimum_direct_payin_amount: '0.495'
address_tag_regex: ^[\w@\-\.:<>]{0,28}$
- name: Tron
code: TRX
protocol: TRC-20
managing_coin:
currency: TRX
network: TRX
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '1.879451'
minimum_direct_payin_amount: '0.88'
crypto_explorer: https://tronscan.org/#/transaction/{tx}
- name: Tezos
code: XTZ
protocol: FA2
precision: 6
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '4.299451'
minimum_direct_payin_amount: '3.3'
swappable_to:
- 1INCH
- AAVE
- ADA
- AGIX
- ALGO
- APE
- ATOM
- AVAX
- AXS
- BCH
- BLUR
- BNB
- BTC
- CELO
- CHZ
- COMP
- CORE
- CRV
- CVX
- DAI
- DASH
- EGLD
- ENJ
- EOS
- ETH
- EUR
- FIL
- GALA
- GMX
- GNO
- GRT
- HBAR
- HMSTR
- ICP
- ICX
- IMX
- INJ
- IOTX
- KAVA
- KSM
- LDO
- LIME
- LINK
- LRC
- LTC
- MANA
- MATIC
- MELANIA
- MINA
- NEAR
- DOT
- NEXO
- NOT
- OMG
- OP
- POL
- QNT
- QTUM
- RVN
- SAND
- SFP
- SHIB
- SOL
- SUI
- SUSHI
- SXP
- THETA
- TON
- TRUMP
- TRX
- TWT
- UNI
- USDC
- VET
- WAVES
- XEC
- XEM
- XLM
- XMR
- XRP
- XTZ
- XYM
- YFI
- ZEC
- ZIL
- ZRX
payin_enabled: true
payout_enabled: true
minimum_swap_amount: '0.999450367'
minimum_payin_amount: '14.199451'
minimum_direct_payin_amount: '13.2'
BTC:
name: Bitcoin
code: BTC
crypto: true
precision: 8
priority: 2
crypto_explorer: https://www.blockchain.com/btc/tx/{tx}
networks:
- name: Bitcoin
code: BTC
protocol: BTC
precision: 8
payin_enabled: true
payout_enabled: true
minimum_payin_amount: '0.00001869'
minimum_direct_payin_amount: '0.0000088'
address_regex: >-
^([13][a-km-zA-HJ-NP-Z1-9A-HJ-NP-Z]{25,34}|[bB][cC]1[a-zA-HJ-NP-Z0-9]{39,59})$
swappable_to:
- 1INCH
- AAVE
- ADA
- AGIX
- ALGO
- APE
- ATOM
- AVAX
- AXS
- BCH
- BLUR
- BNB
- CELO
- CHZ
- COMP
- CORE
- CRV
- CVX
- DAI
- DASH
- EGLD
- ENJ
- EOS
- ETH
- EUR
- FIL
- GALA
- GMX
- GNO
- GRT
- HBAR
- HMSTR
- ICP
- ICX
- IMX
- INJ
- IOTX
- KAVA
- KSM
- LDO
- LIME
- LINK
- LRC
- LTC
- MANA
- MATIC
- MELANIA
- MINA
- NEAR
- DOT
- NEXO
- NOT
- OMG
- OP
- POL
- QNT
- QTUM
- RVN
- SAND
- SFP
- SHIB
- SOL
- SUI
- SUSHI
- SXP
- THETA
- TON
- TRUMP
- TRX
- TWT
- UNI
- USDT
- USDC
- VET
- WAVES
- XEC
- XEM
- XLM
- XMR
- XRP
- XTZ
- XYM
- YFI
- ZEC
- ZIL
- ZRX
payin_enabled: true
payout_enabled: true
minimum_swap_amount: '0.000009881'
minimum_payin_amount: '0.00001869'
minimum_direct_payin_amount: '0.0000088'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/balances:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
get:
tags:
- Balances
operationId: getBalances
summary: Get balances
description: |
Returns balances for all available currencies including zero balances.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/payments_resBalance'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/balances/{currency}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthCurrency'
get:
tags:
- Balances
operationId: getBalance
summary: Get a balance
description: |
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resBalance'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/swaps/rate:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
get:
tags:
- Swaps
operationId: getSwapRate
summary: Get the swap rate
description: |
Returns an estimated or fixed swap rate.
Fixed swap rate (the one created with `fixed` equal `true`) is a promise
to swap on a returned rate within a `fixed_for` time period. To execute
a swap on a fixed rate, pass the exact amounts, rate and rate's ID
returned from this operation to the `POST /swaps/fixed` request.
⚠️ This fixed rate can expire due to high price volatility.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
parameters:
- $ref: '#/components/parameters/payments_qryCurrencyFrom'
- $ref: '#/components/parameters/payments_qryCurrencyTo'
- $ref: '#/components/parameters/payments_qryAmountFrom'
- $ref: '#/components/parameters/payments_qryAmountTo'
- $ref: '#/components/parameters/payments_qryFixed'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSwapRate'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/swaps/now:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Swaps
operationId: makeSwapNow
summary: Make a swap now
description: |
Makes a swap without the fixed price.
⚠️ Do not strictly validate response fields to avoid immediate failures
each time we add a new field.
⚠️ `amount_from` or `amount_to` is required.
⚠️ `amount_from` and `amount_to` are mutually exclusive.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqMakeSwapNow'
example:
currency_from: USDT
currency_to: BTC
amount_from: '2.37'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSwap'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/swaps/fixed:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Swaps
operationId: makeSwapFixed
summary: Make a fixed swap
description: |
Makes a swap at fixed price.
⚠️ Do not strictly validate response fields to avoid immediate failures
each time we add a new field.
⚠️ `amount_from` or `amount_to` is required.
⚠️ `amount_from` and `amount_to` are mutually exclusive.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqMakeSwapFixed'
example:
currency_from: USDT
currency_to: BTC
amount_from: '2.37'
rate: '30250.48'
rate_id: ac76f165-b96b-4a85-8ab2-0a878db73388
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSwap'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/onramp/providers:
get:
tags:
- On-Ramp
operationId: getOnRampProviders
summary: Get providers list
description: Get list of available providers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resGetOnRampProviders'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/onramp/methods:
get:
tags:
- On-Ramp
operationId: getOnRampMethods
summary: Get payment methods list
description: Get list of available payment methods
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resGetOnRampMethods'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/onramp/countries:
get:
tags:
- On-Ramp
operationId: getOnRampCountries
summary: Get countries
description: Get list of available countries
parameters:
- name: provider
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resGetOnRampCountries'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/swaps/{id}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
get:
tags:
- Swaps
operationId: getSwap
summary: Get a swap
description: |
Returns details of a swap.
⚠️ Do not strictly validate response fields to avoid immediate failures
each time we add a new field.
parameters:
- $ref: '#/components/parameters/payments_pthId-Swaps'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSwap'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/addresses:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
get:
tags:
- Addresses
operationId: getAddresses
summary: Get addresses
description: |
Returns the list of allocated static addresses.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
parameters:
- $ref: '#/components/parameters/payments_qryCurrency'
- $ref: '#/components/parameters/payments_qryNetwork'
- $ref: '#/components/parameters/payments_qryAddress'
- $ref: '#/components/parameters/payments_qryAddressTag'
- $ref: '#/components/parameters/payments_qryCustomerId'
- $ref: '#/components/parameters/payments_qryCreatedAtFrom'
- $ref: '#/components/parameters/payments_qryCreatedAtTo'
- $ref: '#/components/parameters/payments_qryCursor'
- $ref: '#/components/parameters/payments_qryLimit'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/payments_resCursors'
- required:
- addresses
- properties:
addresses:
type: array
items:
$ref: '#/components/schemas/payments_resAddress'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errCurrencyNotFound'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
post:
tags:
- Addresses
operationId: allocateAddress
summary: Allocate an address
description: >
Returns a static deposit address for a given combination of currency,
network, and customer.
⚠️ Before allocating a static address, read
[Payments to Static
Addresses](#section/Types-of-Payments/Payments-to-Static-Addresses).
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
ℹ️ If the existing address was de-allocated, allocates a new one.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqAllocateAddress'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resAddress'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errAddressAlreadyExists'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
description: Forbidden
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errMerchantIsDisabled'
- $ref: '#/components/schemas/payments_errAccountIsDisabled'
- $ref: '#/components/schemas/payments_errForbidden'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
description: Service Unavailable
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errNoFreeAddresses'
- $ref: '#/components/schemas/payments_errUnavailableNow'
security:
- payments_APIKeyAuth: []
/addresses/{address_id}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthAddressId'
get:
tags:
- Addresses
operationId: getAddress
summary: Get an address
description: |
Returns an allocated static deposit address.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resAddress'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
patch:
tags:
- Addresses
operationId: updateAddress
summary: Update an address
description: |
Updates an allocated static deposit address.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqUpdateAddress'
responses:
'204':
$ref: '#/components/responses/payments_res204'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'409':
$ref: '#/components/responses/payments_err409'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
delete:
tags:
- Addresses
operationId: deleteAddress
summary: Delete an address
description: |
De-allocates a static deposit address.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'204':
$ref: '#/components/responses/payments_res204'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/withdrawals/amounts/calc:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Withdrawals
operationId: calcAmounts
summary: Estimate the amount
description: >
Calculates estimated withdrawal amount, fees, and the exchange rate.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
⚠️ `receive`, `credit`, `nominal_receive` and `nominal_credit`
parameters are
mutually exclusive.
ℹ️ Provide `receive_currency` and `receive` to calculate the amount
reduced by fees and denominated in target currency.
ℹ️ Provide `credit_currency` and `credit` to calculate the amount that
includes fees and denominated in holding currency.
ℹ️ Provide `nominal_currency` and `nominal_receive` or `nominal_credit`
to calculate
the amount reduced by fees and denominated in fiat.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqCalcAmounts'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resCalcAmounts'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/withdrawals:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Withdrawals
operationId: createWithdrawal
summary: Create a withdrawal
description: |
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqCreateWithdrawal'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resWithdrawal'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errInsufficientBalance'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
description: Forbidden
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errAccountIsDisabled'
- $ref: '#/components/schemas/payments_errOperationBlocked'
- $ref: '#/components/schemas/payments_errForbidden'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/withdrawals/{txn_id}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthTxnId'
get:
tags:
- Withdrawals
operationId: getWithdrawal
summary: Get a withdrawal
description: |
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resWithdrawal'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/withdrawals/{txn_id}/callback:
parameters:
- $ref: '#/components/parameters/payments_pthTxnId'
post:
tags:
- Withdrawals
operationId: sendWithdrawalCallback
summary: Send a withdrawal callback
description: |
Triggers sending a callback notification with the withdrawal status.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
ℹ️ An owner or a team member with the necessary roles can resend through
the dashboard.
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/payments_resSendCallback'
- example:
request:
url: https://example.com/api/v1/payment/webhook
body: >-
{"callback_type":"WITHDRAWAL","id":"942557ee-a61b-4374-94a4-f58b2911230d","order_id":"34d3149b-8eb0-4898-971a-63464ae73f1e","receive_currency":"BTC","receive_network":"ETH","credit_currency":"USDT","receive_amount":"0.00007","credit_amount":"14.08","fee":"0.14","state":"FAILED","txn_id":"a0cdbe86-f568-4b7d-a696-8c31effe10b1","address_tag":"33672098-c31e-4790-b4ed-27fd48638a3e","created_at":"2023-03-22T15:23:56.876Z","updated_at":"2023-03-22T15:23:56.876Z"}
signature: >-
VzMyYzZDT0h3UVR2RFNwNENNMWh5ZE11S3VhWU42ajVEcDl6RG1GaG1pRDlnV25USHI0ZUovVDE4eHZwZGxLdXJmcnhKYSt5RElMelQ0RmRIZUYzVjZYcnNxdzZ3YzhKNi9lZXFyZzc1WnhJek0yN1ZjckFQVXNrazJ3WTFYUFJrK3BqWnpGcTVMRU5ZbHdESFpIOFRPaGtLUTVtbDBQUFFCaDUvVitYTG5BPToxNzEyMjI5NTM5
response:
code: 200
body: '{"ok":true}'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Payments
operationId: createPayment
summary: Create a payment
description: |
Initiates a new payment.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
⚠️ To create an invoice, provide `nominal_amount`, and omit it for
creating a deposit.
⚠️ To make a payin inside a deposit, the customer must follow the
`payment_url` and send crypto to a new address each time.
⚠️ To send crypto to the same address several times, allocate a static
deposit address by calling `POST /api/v1/payment/addresses` instead of
this call.
ℹ️ Provide `payment_method` to determine the payment method right away
and trigger allocation of a new deposit address.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_reqCreatePayment-Deposit'
- $ref: '#/components/schemas/payments_reqCreatePayment-Invoice'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resPayment'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errNominalAmountInvalid'
- $ref: '#/components/schemas/payments_errPaymentMethodNotSelected'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
description: Forbidden
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errForbidden'
- $ref: '#/components/schemas/payments_errAccountIsDisabled'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
get:
tags:
- Payments
operationId: getPayment
summary: Get a payment
description: |
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resPayment'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
patch:
tags:
- Payments
operationId: updatePayment
summary: Update a payment
description: |
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqUpdatePayment'
responses:
'200':
description: OK
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'409':
$ref: '#/components/responses/payments_err409'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/payment_methods:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
get:
tags:
- Payments
operationId: getPaymentMethods
summary: Get payment methods
description: |
Returns a list of payment methods available for a payment.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/payments_resPaymentMethod'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/payment_methods/onramp:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
get:
tags:
- Payments
operationId: getOnRampPaymentMethods
summary: Get fiat on-ramp payment methods
description: |
Returns a list of fiat on-ramp payment methods available for a payment.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/payments_resPaymentMethod'
example:
- name: US Dollar
code: USD
precision: 2
priority: 1
networks: []
- name: Euro
code: EUR
precision: 2
priority: 2
networks: []
- name: British Pound
code: GBP
precision: 2
priority: 3
networks: []
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/payment_methods/calc:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Payments
operationId: calcPaymentMethodAmounts
summary: Calculate payment method amounts
description: |
Returns needed amount in nominal currency given provided payin currency,
network, and amount.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
ℹ️ Provides all data available on `payment_url` to that be handled on
the merchant frontend.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqCalcPaymentMethodAmounts'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resAmount'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'409':
$ref: '#/components/responses/payments_err409'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/payment_methods/onramp/calc:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
post:
tags:
- Payments
operationId: calcOnRampPaymentMethodAmounts
summary: Calculate fiat on-ramp payment method amounts
description: |
Returns a list of available fiat on-ramp offers.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
⚠️ Available only for deposit payments at the moment.
ℹ️ Provides all data available on `payment_url` to that be handled on
the merchant frontend.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqCalcOnRampPaymentMethodAmounts'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/payments_resCalcOnRampPaymentMethodAmounts
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'409':
$ref: '#/components/responses/payments_err409'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/payment_methods/{currency}:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
- $ref: '#/components/parameters/payments_pthCurrency'
get:
tags:
- Payments
operationId: getPaymentMethodsAmounts
summary: Get expected amount
description: |
Returns an expected amount of the payment given the fees.
⚠️ Do not strictly validate response fields to avoid immediate failures
each time we add a new field.
parameters:
- $ref: '#/components/parameters/payments_qryNetwork'
- $ref: '#/components/parameters/payments_qryPayinAmount'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resAmount'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errBadRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/selected_payment_method:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
put:
tags:
- Payments
operationId: updatePaymentMethod
summary: Set payment method
description: |
Sets the payment method for a payment.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqSelectPaymentMethod'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSelectedPaymentMethod'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errInvalidRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
description: Forbidden
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errMerchantIsDisabled'
- $ref: '#/components/schemas/payments_errAccountIsDisabled'
- $ref: '#/components/schemas/payments_errForbidden'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
description: Service Unavailable
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errNoFreeAddresses'
- $ref: '#/components/schemas/payments_errUnavailableNow'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/selected_payment_method/onramp:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
put:
tags:
- Payments
operationId: updateOnRampPaymentMethod
summary: Set fiat on-ramp payment method
description: |
Sets the fiat on-ramp payment method for a payment.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payments_reqSelectOnRampPaymentMethod'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSelectedOnRampOffer'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInvalidRequestParameters'
- $ref: '#/components/schemas/payments_errInvalidRequest'
'401':
$ref: '#/components/responses/payments_err401'
'403':
description: Forbidden
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errMerchantIsDisabled'
- $ref: '#/components/schemas/payments_errAccountIsDisabled'
- $ref: '#/components/schemas/payments_errForbidden'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
description: Service Unavailable
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errNoFreeAddresses'
- $ref: '#/components/schemas/payments_errUnavailableNow'
security:
- payments_APIKeyAuth: []
/payments/{payment_id}/callback:
parameters:
- $ref: '#/components/parameters/payments_xSignature'
- $ref: '#/components/parameters/payments_pthPaymentId'
post:
tags:
- Payments
operationId: sendPaymentCallback
summary: Send a payment callback
description: |
Triggers sending a callback notification with the payment status.
⚠️ Do not strictly validate response fields to avoid immediate
failures each time we add a new field.
ℹ️ An owner or a team member with the necessary roles can resend through
the dashboard.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/payments_resSendCallback'
'400':
$ref: '#/components/responses/payments_err400'
'401':
$ref: '#/components/responses/payments_err401'
'403':
$ref: '#/components/responses/payments_err403'
'404':
$ref: '#/components/responses/payments_err404'
'429':
$ref: '#/components/responses/payments_err429'
'500':
$ref: '#/components/responses/payments_err500'
'503':
$ref: '#/components/responses/payments_err503'
security:
- payments_APIKeyAuth: []
webhooks:
/:
post:
parameters:
- $ref: '#/components/parameters/callbacks_xSignature'
tags:
- Callbacks
operationId: callback
summary: Callback notification
description: |
Incoming POST request containing a payment/withdrawal notification.
⚠️ Do not strictly validate request fields to avoid immediate failures
each time we add a new field.
ℹ️ Processing of this incoming request must be implemented on the
merchant's server side.
ℹ️ To receive callbacks, provide the URL in the cabinet.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/callbacks_reqCallback'
responses:
2XX:
description: Successful
4XX:
description: Client Error
5XX:
description: Server Error
security: []
components:
parameters:
payments_xSignature:
name: X-Signature
in: header
required: true
schema:
$ref: '#/components/schemas/payments_schSignature'
payments_pthCurrency:
name: currency
in: path
required: true
schema:
$ref: '#/components/schemas/payments_schCode-Currency'
description: Currency code.
payments_qryCurrency:
name: currency
in: query
schema:
$ref: '#/components/schemas/payments_schCode-Currency'
description: |
Currency code.
payments_qryNetwork:
name: network
in: query
schema:
$ref: '#/components/schemas/payments_schCode-Network'
payments_pthPaymentId:
name: payment_id
in: path
required: true
schema:
type: string
format: uuid
description: |
Payment ID.
example: 80036de2-7aef-4aaf-9205-992647ff730a
payments_qryCursor:
name: cursor
in: query
schema:
$ref: '#/components/schemas/payments_schCursor'
description: |
The cursor received in the previous response in the `cursor_next` field.
payments_qryLimit:
name: limit
in: query
schema:
type: integer
format: uint64
minimum: 1
maximum: 100
default: 20
description: |
The maximum number of items to return.
payments_pthAddressId:
name: address_id
in: path
required: true
schema:
$ref: '#/components/schemas/payments_schAddressId'
payments_pthTxnId:
name: txn_id
in: path
required: true
schema:
$ref: '#/components/schemas/payments_schTxnId'
payments_qryCurrencyFrom:
name: currency_from
in: query
required: true
schema:
$ref: '#/components/schemas/payments_schCode-Currency'
description: |
Source currency.
payments_qryCurrencyTo:
name: currency_to
in: query
required: true
schema:
$ref: '#/components/schemas/payments_schCode-Currency-To'
payments_qryFixed:
name: fixed
in: query
schema:
type: boolean
default: true
description: |
Flag indicating if the swap has a fixed price.
payments_pthId-Swaps:
name: id
in: path
required: true
schema:
$ref: '#/components/schemas/payments_schId-Swaps'
payments_qryAmountFrom:
name: amount_from
in: query
schema:
$ref: '#/components/schemas/payments_schAmountFrom'
payments_qryAmountTo:
name: amount_to
in: query
schema:
$ref: '#/components/schemas/payments_schAmountTo'
payments_qryAddress:
name: address
in: query
schema:
$ref: '#/components/schemas/payments_schAddress'
payments_qryAddressTag:
name: address_tag
in: query
schema:
$ref: '#/components/schemas/payments_schAddressTag'
payments_qryCustomerId:
name: customer_id
in: query
schema:
$ref: '#/components/schemas/payments_schCustomerId'
payments_qryCreatedAtFrom:
name: created_at_from
in: query
schema:
$ref: '#/components/schemas/payments_schTimestamp'
description: |
Start timestamp for `created_at`.
payments_qryCreatedAtTo:
name: created_at_to
in: query
schema:
$ref: '#/components/schemas/payments_schTimestamp'
description: |
End timestamp for `created_at`.
payments_qryPayinAmount:
name: payin_amount
in: query
schema:
$ref: '#/components/schemas/payments_schAmount'
description: |
Payin amount.
Format: decimal
callbacks_xSignature:
name: X-Signature
in: header
required: true
schema:
type: string
minLength: 16
maxLength: 512
description: |
Signature of a call passed to the receiver for verification of the call
origin.
schemas:
payments_schSignature:
title: Signature
type: string
minLength: 16
maxLength: 512
description: |
Signature of a call passed to the receiver for verification of the call
origin.
payments_schCode:
title: Code
type: string
pattern: ^[A-Z0-9]{2,16}$
minLength: 2
maxLength: 16
payments_schCode-Network:
title: Network code
allOf:
- $ref: '#/components/schemas/payments_schCode'
description: |
Network code.
examples:
- ETH
payments_schName-Network:
title: Network name
type: string
description: |
Network name.
examples:
- Ethereum
payments_schCode-Currency:
title: Currency code
allOf:
- $ref: '#/components/schemas/payments_schCode'
description: |
Currency code.
examples:
- USDT
payments_schName-Currency:
title: Name
type: string
description: |
Currency name.
example: Tether
payments_schAmount:
title: Amount
type: string
maxLength: 128
description: |
Amount.
Format: decimal
example: '14.08'
payments_ptyCode-Network:
title: Network code
type: object
properties:
code:
$ref: '#/components/schemas/payments_schCode-Network'
payments_ptyName-Network:
title: Network name
type: object
properties:
name:
$ref: '#/components/schemas/payments_schName-Network'
payments_ptyCode-Currency:
title: Currency code
type: object
properties:
code:
$ref: '#/components/schemas/payments_schCode-Currency'
payments_ptyName-Currency:
title: Currency name
type: object
properties:
name:
$ref: '#/components/schemas/payments_schName-Currency'
payments_schPrecision:
title: Precision
type: integer
format: uint64
description: |
The number of digits after the dot.
example: 8
payments_ptyPrecision:
title: Precision
type: object
properties:
precision:
$ref: '#/components/schemas/payments_schPrecision'
payments_schCode-Currency-To:
title: Currency to
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Target currency.
example: BTC
payments_ptySwappableTo:
title: Swappable to
type: object
properties:
swappable_to:
type: array
items:
$ref: '#/components/schemas/payments_schCode-Currency-To'
payments_schProtocol:
title: Protocol
type: string
description: |
The protocol or the standard powering the network.
example: ERC20
payments_ptyProtocol:
title: Protocol
type: object
properties:
protocol:
$ref: '#/components/schemas/payments_schProtocol'
payments_schAddressRegex:
title: Address regex
type: string
description: |
Regular expression for a deposit address.
example: ^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}$
payments_ptyAddressRegex:
title: Address regex
type: object
properties:
address_regex:
$ref: '#/components/schemas/payments_schAddressRegex'
payments_schAddressTagRegex:
title: Address tag regex
type: string
description: |
Regular expression for `address_tag`.
example: ^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}$
payments_ptyAddressTagRegex:
title: Address tag regex
type: object
properties:
address_tag_regex:
$ref: '#/components/schemas/payments_schAddressTagRegex'
payments_schNetworks:
title: Networks
allOf:
- $ref: '#/components/schemas/payments_ptyCode-Network'
- $ref: '#/components/schemas/payments_ptyName-Network'
- $ref: '#/components/schemas/payments_ptyProtocol'
- $ref: '#/components/schemas/payments_ptyPrecision'
- $ref: '#/components/schemas/payments_ptyPayinEnabled'
- $ref: '#/components/schemas/payments_ptyPayoutEnabled'
- $ref: '#/components/schemas/payments_ptyMinimumDirectPayinAmount'
- $ref: '#/components/schemas/payments_ptyAddressRegex'
- $ref: '#/components/schemas/payments_ptyAddressTagName'
- $ref: '#/components/schemas/payments_ptyAddressTagRegex'
- $ref: '#/components/schemas/payments_ptyCryptoExplorer'
- required:
- name
- code
- protocol
- precision
- payin_enabled
- payout_enabled
- properties:
minimum_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schMinimumPayinAmount'
description: |
Minimum payin amount.
ℹ️ If swaps are needed, equals to the sum of
`minimum_direct_payin_amount` and `minimum_swap_amount`.
Format: decimal
payments_ptyNetworks:
title: Networks
properties:
networks:
type: array
items:
$ref: '#/components/schemas/payments_schNetworks'
description: |
Networks supporting the currency.
payments_schCrypto:
title: Crypto
type: boolean
description: |
Flag indicating whether the currency is a cryptocurrency.
payments_ptyCrypto:
title: Crypto
type: object
properties:
crypto:
$ref: '#/components/schemas/payments_schCrypto'
payments_ptyMinimumSwapAmount:
title: Minimum swap amount
type: object
properties:
minimum_swap_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Minimum swap amount.
⚠️ Applied if nominal and holding currencies are different.
Format: decimal
example: '0.00001494652018679495'
payments_schMinimumPayinAmount:
title: Minimum payin amount
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Minimum payin amount.
Format: decimal
example: '0.00004244652018679495'
payments_ptyMinimumPayinAmount:
title: Minimum payin amount
type: object
properties:
minimum_payin_amount:
$ref: '#/components/schemas/payments_schMinimumPayinAmount'
payments_ptyMinimumDirectPayinAmount:
title: Minimum direct payin amount
type: object
properties:
minimum_direct_payin_amount:
$ref: '#/components/schemas/payments_schMinimumDirectPayinAmount'
payments_schMinimumDirectPayinAmount:
title: Minimum direct payin amount
type: string
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Minimum payin amount considering network fees.
example: '0.0000275'
payments_schPriority:
title: Priority
type: integer
minimum: 1
description: |
The absolute position of the currency in the currency list.
example: 1
payments_ptyPriority:
title: Priority
type: object
properties:
priority:
$ref: '#/components/schemas/payments_schPriority'
payments_schCryptoExplorer:
title: Crypto explorer
type: string
format: url
description: |
The link to the currency explorer with `{tx}` placeholder for a hash.
example: http://omniexplorer.info/lookuptx.aspx?txid={tx}
payments_ptyCryptoExplorer:
title: Crypto explorer
type: object
properties:
crypto_explorer:
$ref: '#/components/schemas/payments_schCryptoExplorer'
payments_schPayinEnabled:
title: Payin enabled
type: boolean
description: |
Flag indicating generating deposit addresses is allowed for the
currency.
payments_ptyPayinEnabled:
title: Payin enabled
type: object
properties:
payin_enabled:
$ref: '#/components/schemas/payments_schPayinEnabled'
payments_ptyPayoutEnabled:
title: Payout enabled
type: object
properties:
payout_enabled:
type: boolean
description: |
Flag indicating withdrawals are allowed for the currency.
payments_schAddressTagName:
title: Address tag name
type: string
description: |
The name of the auxiliary identifier used in the network for
identification of the receiver.
example: Memo
payments_ptyAddressTagName:
title: Address tag name
type: object
properties:
address_tag_name:
$ref: '#/components/schemas/payments_schAddressTagName'
payments_resCurrency:
title: Currency
allOf:
- $ref: '#/components/schemas/payments_ptyCode-Currency'
- $ref: '#/components/schemas/payments_ptyName-Currency'
- $ref: '#/components/schemas/payments_ptyCrypto'
- $ref: '#/components/schemas/payments_ptyPrecision'
- $ref: '#/components/schemas/payments_ptyPriority'
- $ref: '#/components/schemas/payments_ptyAddressTagName'
- $ref: '#/components/schemas/payments_ptyCryptoExplorer'
- $ref: '#/components/schemas/payments_ptyNetworks'
- $ref: '#/components/schemas/payments_ptySwappableTo'
- $ref: '#/components/schemas/payments_ptyPayinEnabled'
- $ref: '#/components/schemas/payments_ptyPayoutEnabled'
- $ref: '#/components/schemas/payments_ptyMinimumSwapAmount'
- required:
- code
- name
- crypto
- precision
- networks
- swappable_to
- payin_enabled
- payout_enabled
- properties:
minimum_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schMinimumPayinAmount'
description: |
Minimum payin amount.
ℹ️ If swaps are needed, equals to the sum of
`minimum_direct_payin_amount` and `minimum_swap_amount`.
minimum_direct_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schMinimumDirectPayinAmount'
description: |
Maximum `minimum_direct_payin_amount` among all networks.
payments_ptyCurrency:
title: Currency
type: object
properties:
currency:
$ref: '#/components/schemas/payments_schCode-Currency'
payments_ptyNetwork:
title: Network
type: object
properties:
network:
$ref: '#/components/schemas/payments_schCode-Network'
payments_ptyFiatEquivalentCurrency:
title: Fiat equivalent currency
type: object
properties:
fiat_equivalent_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Fiat currency code.
example: USD
payments_ptyFiatEquivalentAmount:
title: Fiat equivalent amount
type: object
properties:
fiat_equivalent_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Balance expressed in fiat.
payments_resBalance:
title: Balance response
allOf:
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyFiatEquivalentCurrency'
- $ref: '#/components/schemas/payments_ptyFiatEquivalentAmount'
- required:
- currency
- amount
- properties:
amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Balance.
Format: decimal
payments_resGetOnRampProviders:
type: array
items:
$ref: '#/components/schemas/payments_schOnRampProviderCode'
payments_resGetOnRampMethods:
type: array
items:
$ref: '#/components/schemas/payments_schOnRampPaymentMethod'
payments_resGetOnRampCountries:
type: array
items:
$ref: '#/components/schemas/payments_schOnRampCountry'
payments_schOnRampCountry:
type: object
required:
- code
- name
properties:
code:
$ref: '#/components/schemas/payments_schCountry'
name:
type: string
example: United States
states:
type: array
items:
type: object
required:
- code
- name
properties:
code:
$ref: '#/components/schemas/payments_schCountryState'
name:
type: string
example: New York
payments_schCurrencyFrom:
title: Currency from
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Source currency.
payments_ptyCurrencyFrom:
title: Currency from
type: object
properties:
currency_from:
$ref: '#/components/schemas/payments_schCurrencyFrom'
payments_ptyCurrencyTo:
title: Currency to
type: object
properties:
currency_to:
$ref: '#/components/schemas/payments_schCode-Currency-To'
payments_schAmountFrom:
title: Amount from
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Amount in source currency.
example: '2.37'
payments_ptyAmountFrom:
title: Amount from
type: object
properties:
amount_from:
$ref: '#/components/schemas/payments_schAmountFrom'
payments_schAmountTo:
title: Amount to
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Estimated amount in target currency.
example: '0.00007'
payments_ptyAmountTo:
title: Amount to
type: object
properties:
amount_to:
$ref: '#/components/schemas/payments_schAmountTo'
payments_ptyRate:
title: Rate
type: object
properties:
rate:
$ref: '#/components/schemas/payments_schRate'
payments_ptyFixedFor:
title: Fixed for
type: object
properties:
fixed_for:
type: integer
description: |
For how long in seconds the rate is fixed.
example: 120
payments_resSwapRate:
title: Swap rate
allOf:
- $ref: '#/components/schemas/payments_ptyCurrencyFrom'
- $ref: '#/components/schemas/payments_ptyCurrencyTo'
- $ref: '#/components/schemas/payments_ptyAmountFrom'
- $ref: '#/components/schemas/payments_ptyAmountTo'
- $ref: '#/components/schemas/payments_ptyRate'
- $ref: '#/components/schemas/payments_ptyFixedFor'
- required:
- currency_from
- currency_to
- amount_from
- amount_to
- rate
- properties:
id:
$ref: '#/components/schemas/payments_schRateId'
payments_reqMakeSwapNow:
title: Make swap now request
allOf:
- $ref: '#/components/schemas/payments_ptyCurrencyFrom'
- $ref: '#/components/schemas/payments_ptyCurrencyTo'
- $ref: '#/components/schemas/payments_ptyAmountFrom'
- $ref: '#/components/schemas/payments_ptyAmountTo'
- required:
- currency_from
- currency_to
payments_schRateId:
title: Rate ID
type: string
format: uuid
description: |
Swap rate UUID.
example: 58380c1e-60e7-4d81-85ad-1867151641b2
payments_ptyRateId:
title: Rate ID
type: object
properties:
rate_id:
$ref: '#/components/schemas/payments_schRateId'
payments_reqMakeSwapFixed:
title: Make swap fixed
allOf:
- $ref: '#/components/schemas/payments_ptyCurrencyFrom'
- $ref: '#/components/schemas/payments_ptyCurrencyTo'
- $ref: '#/components/schemas/payments_ptyAmountFrom'
- $ref: '#/components/schemas/payments_ptyAmountTo'
- $ref: '#/components/schemas/payments_ptyRate'
- $ref: '#/components/schemas/payments_ptyRateId'
- required:
- currency_from
- currency_to
- rate
- rate_id
payments_schId-Swaps:
title: Swap ID
type: string
description: |
Swap ID.
example: '7189236'
payments_ptyId-Swaps:
title: Swap ID
type: object
properties:
id:
$ref: '#/components/schemas/payments_schId-Swaps'
payments_schStatus-Swaps:
title: Swap status
type: string
enum:
- PENDING
- COMPLETED
- FAILED
- ROLLED_BACK
description: |
Swap status.
payments_ptyStatus-Swaps:
title: Swap status
type: object
properties:
status:
$ref: '#/components/schemas/payments_schStatus-Swaps'
payments_resSwap:
title: Swap
allOf:
- $ref: '#/components/schemas/payments_ptyId-Swaps'
- $ref: '#/components/schemas/payments_ptyCurrencyFrom'
- $ref: '#/components/schemas/payments_ptyCurrencyTo'
- $ref: '#/components/schemas/payments_ptyAmountFrom'
- $ref: '#/components/schemas/payments_ptyAmountTo'
- $ref: '#/components/schemas/payments_ptyRate'
- $ref: '#/components/schemas/payments_ptyStatus-Swaps'
- required:
- id
- currency_from
- currency_to
- amount_from
- amount_to
- rate
- status
payments_schTimestamp:
title: Timestamp
type: string
format: date-time
example: '2023-03-22T15:23:56.876Z'
payments_schCursor:
title: Cursor
type: string
description: |
Pointer to an adjacent result page if any.
example: >-
MjAyMy0xMC0xOFQxMTo1ODowOS41OTRaXzA4MzQ2NDhhLWI5YzktNDIwOC1iMzQ2LWUzNjY3NDcwYzIzN19mYWxzZQ==
payments_resCursors:
title: Cursors
type: object
properties:
cursor_next:
$ref: '#/components/schemas/payments_schCursor'
cursor_prev:
$ref: '#/components/schemas/payments_schCursor'
payments_schAddress:
title: Address
type: string
description: |
Deposit address.
example: '0xb794f5ea0ba39494ce839613fffba74279579268'
payments_schAddressTag:
title: Address tag
type: string
description: |
Address tag value.
example: 33672098-c31e-4790-b4ed-27fd48638a3e
payments_schAddressId:
title: Address ID
type: string
format: uuid
description: |
Static deposit address UUID.
example: 75bca384-cf5e-4afb-b1d8-ba488b03bf1e
payments_ptyAddress:
title: Address
type: object
properties:
address:
$ref: '#/components/schemas/payments_schAddress'
payments_ptyAddressTag:
title: Address tag
type: object
properties:
address_tag:
$ref: '#/components/schemas/payments_schAddressTag'
payments_ptyPayinsEnabled:
title: Payins enabled
type: object
properties:
payins_enabled:
$ref: '#/components/schemas/payments_schPayinEnabled'
payments_schOrigin:
title: Origin
type: string
enum:
- API
- Cabinet
description: |
Flag indicating the way the address was created.
payments_ptyOrigin:
title: Origin
type: object
properties:
origin:
$ref: '#/components/schemas/payments_schOrigin'
payments_resAddress:
title: Address response
allOf:
- $ref: '#/components/schemas/payments_ptyProjectId'
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyNetwork'
- $ref: '#/components/schemas/payments_ptyAddress'
- $ref: '#/components/schemas/payments_ptyAddressTag'
- $ref: '#/components/schemas/payments_ptyPayinsEnabled'
- $ref: '#/components/schemas/payments_ptyMinimumPayinAmount'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- $ref: '#/components/schemas/payments_ptyOrigin'
- $ref: '#/components/schemas/payments_ptyNewAddressGenerated'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- required:
- id
- project_id
- currency
- network
- address
- payins_enabled
- minimum_payin_amount
- customer_id
- origin
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- new_address_generated
- properties:
id:
$ref: '#/components/schemas/payments_schAddressId'
created_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of the creation.
updated_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of the last update.
payments_schNewAddressGenerated:
title: New address generated
type: boolean
description: |
Flag indicating if customer deposit address was replaced with a new one.
payments_ptyNewAddressGenerated:
title: New address generated
type: object
properties:
new_address_generated:
$ref: '#/components/schemas/payments_schNewAddressGenerated'
payments_reqAllocateAddress:
title: Create address request
allOf:
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyNetwork'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- required:
- currency
- customer_id
- customer_ip_address
- customer_referer_domain
payments_reqUpdateAddress:
title: Update address request
allOf:
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- properties:
payment_data:
allOf:
- $ref: '#/components/schemas/payments_schData'
nullable: true
nominal_currency:
allOf:
- $ref: '#/components/schemas/payments_schNominalCurrency'
nullable: true
fees_payer:
allOf:
- $ref: '#/components/schemas/payments_schFeesPayer'
nullable: true
- required:
- customer_ip_address
- customer_referer_domain
payments_ptyReceiveNetwork:
title: Receive network
type: object
properties:
receive_network:
$ref: '#/components/schemas/payments_schCode-Network'
payments_reqCalcAmounts:
oneOf:
- $ref: '#/components/schemas/payments_reqCalcAmounts-Receive'
- $ref: '#/components/schemas/payments_reqCalcAmounts-Credit'
- $ref: '#/components/schemas/payments_reqCalcAmounts-NominalReceive'
- $ref: '#/components/schemas/payments_reqCalcAmounts-NominalCredit'
payments_ptyReceiveCurrency:
title: Receive currency
type: object
properties:
receive_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency-To'
description: |
The currency credited to the merchant as the result of a withdrawal.
payments_ptyCreditCurrency:
title: Credit currency
type: object
properties:
credit_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
The holding currency.
payments_ptyNominalReceiveCurrency:
title: Nominal currency
type: object
properties:
nominal_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency-To'
description: >
A fiat currency that denominates crypto the merchant receives or
credits as the
result of a withdrawal.
example: USD
payments_reqCalcAmounts-Receive:
title: Receive currency
allOf:
- $ref: '#/components/schemas/payments_ptyReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyCreditCurrency'
- $ref: '#/components/schemas/payments_ptyNominalReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyReceiveNetwork'
- required:
- receive_currency
- amount
- properties:
amount:
type: object
required:
- receive
properties:
receive:
allOf:
- $ref: '#/components/schemas/payments_schAmountTo'
description: |
The amount of crypto the merchant must receive as the result
of a withdrawals (fees not included).
Format: decimal
payments_reqCalcAmounts-Credit:
title: Credit currency
allOf:
- $ref: '#/components/schemas/payments_ptyReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyCreditCurrency'
- $ref: '#/components/schemas/payments_ptyNominalReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyReceiveNetwork'
- required:
- credit_currency
- amount
- properties:
amount:
type: object
required:
- credit
properties:
credit:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
The amount of crypto the merchant withdraws from the holding
account (fees included).
Format: decimal
payments_reqCalcAmounts-NominalReceive:
title: Nominal receive currency
allOf:
- $ref: '#/components/schemas/payments_ptyReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyCreditCurrency'
- $ref: '#/components/schemas/payments_ptyNominalReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyReceiveNetwork'
- required:
- nominal_currency
- amount
- properties:
amount:
type: object
required:
- nominal_receive
properties:
nominal_receive:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
The amount of fiat the merchant must receive as the
result of a withdrawals (fees not included).
Format: decimal
payments_reqCalcAmounts-NominalCredit:
title: Nominal credit currency
allOf:
- $ref: '#/components/schemas/payments_ptyReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyCreditCurrency'
- $ref: '#/components/schemas/payments_ptyNominalReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyReceiveNetwork'
- required:
- nominal_currency
- amount
- properties:
amount:
type: object
required:
- nominal_credit
properties:
nominal_credit:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: >
The amount of fiat equivalent the merchant withdraws from
the holding account (fees included).
Format: decimal
payments_ptyCreditAmount:
title: Credit amount
type: object
properties:
credit_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
The amount of crypto the merchant withdraws from the
holding account (fees included).
Format: decimal
payments_ptyReceiveAmount:
title: Receive amount
type: object
properties:
receive_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmountTo'
description: |
The amount of crypto the merchant must receive as the result of
a withdrawals (fees not included).
Format: decimal
payments_ptySwapRate:
title: Swap rate
type: object
properties:
swap_rate:
$ref: '#/components/schemas/payments_schRate'
payments_ptyFee:
title: Fee
type: object
properties:
fee:
type: string
description: |
Withdrawal fee amount.
Format: decimal
example: '0.14'
payments_resCalcAmounts:
title: Amounts
allOf:
- $ref: '#/components/schemas/payments_ptyCreditAmount'
- $ref: '#/components/schemas/payments_ptyReceiveAmount'
- $ref: '#/components/schemas/payments_ptySwapRate'
- $ref: '#/components/schemas/payments_ptyFee'
- required:
- credit_amount
- receive_amount
- fee
payments_ptyIdempotencyKey:
title: Idempotency key
type: object
properties:
idempotency_key:
type: string
description: |
A unique arbitrary key identifying the request used for avoiding
repeated operations (maintain idempotency).
example: 3f29dcb7-6b33-4fa6-9e37-b262d4810f31
payments_reqCreateWithdrawal:
title: Create withdrawal request
allOf:
- $ref: '#/components/schemas/payments_reqCalcAmounts'
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyAddress'
- $ref: '#/components/schemas/payments_ptyAddressTag'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyIdempotencyKey'
- $ref: '#/components/schemas/payments_ptyNote'
- required:
- address
- customer_ip_address
- customer_referer_domain
payments_schTxnId:
title: Transaction ID
type: string
format: uuid
description: |
Transaction UUID.
example: f4505800-772e-4502-88ed-48b1f9585070
payments_schState-Withdrawal:
title: State
type: string
enum:
- PENDING
- COMPLETED
- CANCELED
- FAILED
description: |
Withdrawal state.
Values:
* `PENDING`—a transaction has been created and either waiting to be sent
to the blockchain or has been sent to the blockchain and gains
confirmations;
* `CANCELED`—the transaction has been rolled back;
* `FAILED`—transaction has failed before being created or on latest
stages;
* `COMPLETED`—transaction has been successfully completed.
payments_ptyState-Withdrawal:
title: State
type: object
properties:
state:
$ref: '#/components/schemas/payments_schState-Withdrawal'
payments_schHash:
title: Hash
type: string
description: |
Network transaction hash.
example: 0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20
payments_ptyHash:
title: Hash
type: object
properties:
hash:
$ref: '#/components/schemas/payments_schHash'
payments_ptyId-Withdrawals:
title: Withdrawal ID
type: object
properties:
id:
$ref: '#/components/schemas/payments_schTxnId'
payments_schPayoutTxnTd:
title: Payout UUID
allOf:
- $ref: '#/components/schemas/payments_schTxnId'
description: |
UUID of the payout corresponding to this withdrawal.
example: a0cdbe86-f568-4b7d-a696-8c31effe10b1
payments_ptyPayoutTxnTd:
title: Payout UUID
type: object
properties:
payout_txn_id:
$ref: '#/components/schemas/payments_schPayoutTxnTd'
payments_schCanceledBy:
title: Canceled by
type: object
required:
- id
- name
- email
properties:
id:
type: string
format: uuid
description: |
Cabinet user UUID.
name:
type: string
description: |
Cabinet user name
email:
type: string
format: email
description: |
Cabinet user email.
payments_ptyNote:
title: Note
type: object
properties:
note:
type: string
description: |
Withdrawal text comment.
payments_resWithdrawal:
title: withdrawal response
allOf:
- $ref: '#/components/schemas/payments_resCalcAmounts'
- $ref: '#/components/schemas/payments_ptyId-Withdrawals'
- $ref: '#/components/schemas/payments_ptyAddress'
- $ref: '#/components/schemas/payments_ptyState-Withdrawal'
- $ref: '#/components/schemas/payments_ptyAddressTag'
- $ref: '#/components/schemas/payments_ptyReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyCreditCurrency'
- $ref: '#/components/schemas/payments_ptyNominalReceiveCurrency'
- $ref: '#/components/schemas/payments_ptyReceiveNetwork'
- $ref: '#/components/schemas/payments_ptyIdempotencyKey'
- $ref: '#/components/schemas/payments_ptyPayoutTxnTd'
- $ref: '#/components/schemas/payments_ptyHash'
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyNote'
- $ref: '#/components/schemas/payments_ptyError'
- required:
- id
- status
- address
- receive_currency
- credit_currency
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- properties:
created_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Withdrawal created.
canceled_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Transaction rolled back.
canceled_by:
allOf:
- $ref: '#/components/schemas/payments_schCanceledBy'
description: |
Identity of the cabinet user who canceled the withdrawal.
sent_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Transaction sent to the blockchain.
committed_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Transaction committed in the blockchain.
updated_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Withdrawal status updated.
payments_schData:
type: object
additionalProperties: true
description: |
Arbitrary metadata associated with the payment.
example:
order_id: 221163
customer_phone: '+999999999'
payments_schCustomerId:
title: Customer ID
type: string
minLength: 1
maxLength: 36
description: |
Arbitrary customer ID.
example: 24fc0740-c6c6-48d8-9735-6b5f42a350d4
payments_ptyCustomerId:
title: Customer ID
type: object
properties:
customer_id:
$ref: '#/components/schemas/payments_schCustomerId'
payments_schCustomerEmail:
type: string
format: email
maxLength: 255
description: |
Customer email.
example: johndoe@example.com
payments_ptyCustomerEmail:
title: Customer email
type: object
properties:
customer_email:
$ref: '#/components/schemas/payments_schCustomerEmail'
payments_ptyOrderId:
title: Order ID
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 36
description: |
Arbitrary operation ID generated of the merchant side.
example: 34d3149b-8eb0-4898-971a-63464ae73f1e
payments_schTitle:
title: Title
type: string
maxLength: 255
description: |
Payment custom name shown to the customer.
example: DBA
payments_ptyTitle:
title: Title
type: object
properties:
title:
$ref: '#/components/schemas/payments_schTitle'
payments_schDescription:
title: Description
type: string
maxLength: 4096
description: |
Payment custom description.
example: Lorem ipsum dolor sit amet consectetur adipiscing elit...
payments_ptyDescription:
title: Description
type: object
properties:
description:
$ref: '#/components/schemas/payments_schDescription'
payments_ptySuccessRedirectUrl:
title: Success redirect URL
type: object
properties:
success_redirect_url:
type: string
format: uri
description: |
Link to the merchant page displayed to the customer in the case
of success.
example: https://example.com/payment/success
payments_ptyFailureRedirectUrl:
title: Failure redirect URL
type: object
properties:
failure_redirect_url:
type: string
format: uri
description: |
Link to the merchant page displayed to the customer in the case
of failure.
example: https://example.com/payment/failure
payments_schNominalCurrency:
title: Nominal currency
type: string
description: |
The desired currency of payment.
ℹ️ This currency also denominates the amount specified in
`nominal_amount`.
example: USDT
payments_ptyNominalCurrency:
title: Nominal currency
type: object
properties:
nominal_currency:
$ref: '#/components/schemas/payments_schNominalCurrency'
payments_ptyNominalAmount:
title: Nominal amount
type: object
properties:
nominal_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
The desired amount of a payment.
⚠️ A payment will not complete until this amount is sent by
the customer.
Format: decimal
payments_schFeesPayer:
title: Fees payer
type: string
enum:
- MERCHANT
- CUSTOMER
description: |
The party that pays fees.
Values:
* `MERCHANT`—the amount of payment is not affected by fees;
* `CUSTOMER`—the amount of a payment is reduced by fees.
payments_ptyFeesPayer:
title: Fees payer
type: object
properties:
fees_payer:
$ref: '#/components/schemas/payments_schFeesPayer'
payments_ptyPaymentData:
title: Payment data
type: object
properties:
payment_data:
$ref: '#/components/schemas/payments_schData'
payments_schLossConfig:
title: Loss config
type: object
properties:
relative:
type: number
minimum: 0
maximum: 1
description: |
Maximum allowed underpaid percent of `expected_payin_amount`.
Calculated as 1 - 'remaining_payin_amount' / `expected_payin_amount`
where 'remaining_payin_amount' is the minimal accepted amount.
Format: decimal fraction (0.01 stands for 1%)
absolute:
type: object
required:
- currency
- amount
properties:
currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
enum:
- USD
- EUR
- GBP
- AUD
- BRL
- CAD
- INR
- RUB
- TRY
- UAH
description: |
Currency that denominates the absolute underpayment threshold.
ℹ️ To propose a new currency, contact our support team.
amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Maximum allowed underpaid amount.
Format: decimal
payments_ptyLossConfig:
title: Loss config
type: object
properties:
loss_config:
allOf:
- $ref: '#/components/schemas/payments_schLossConfig'
description: |
⚠️ If both `relative` and `absolute` are provided,
the lowest of two calculated amounts will be chosen.
ℹ️ If omitted, we apply underpayment settings from the cabinet; and
0%—if no settings submitted.
payments_schError:
title: Error
type: object
properties:
message:
type: string
description: |
Error message.
example: >-
The order has been failed because the payin amount is below the
minimum amount
payments_ptyError:
title: Error
type: object
properties:
error:
allOf:
- $ref: '#/components/schemas/payments_schError'
description: |
Error caused payment failure.
payments_ptyPendingDeadlineAt:
title: Pending deadline at
type: object
properties:
pending_deadline_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
The deadline for payments in the `PENDING` state.
ℹ️ If the provided deadline exceeds the one in `deadline_at`
for the chosen method, it will not take effect.
⚠️ If a payment violates the deadline, it will be
transferred to the `CANCELED` state.
example: '2023-03-22T15:23:56.876Z'
payments_ptyPaymentMethod:
title: Payment method
type: object
properties:
payment_method:
allOf:
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyNetwork'
- required:
- currency
- description: |
Payment method.
payments_ptyOnRampOffer:
title: On-ramp offer
type: object
properties:
onramp_offer:
$ref: '#/components/schemas/payments_reqSelectOnRampPaymentMethod'
payments_checkoutTemplateId:
title: Checkout template ID
type: object
properties:
checkout_template_id:
type: string
format: uuid
description: |
UUID of the template that will be displayed on the checkout page.
ℹ️ If not set, default template will be applied.
ℹ️ See the templates settings in **My Merchant** >
**Checkout templates** section in the app.
example: c1460010-ed46-49eb-8f02-4f0edd21c933
payments_reqCreatePayment-Deposit:
title: Deposit
allOf:
- $ref: '#/components/schemas/payments_ptyTitle'
- $ref: '#/components/schemas/payments_ptyDescription'
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyRecommendedAmount'
- $ref: '#/components/schemas/payments_ptySuccessRedirectUrl'
- $ref: '#/components/schemas/payments_ptyFailureRedirectUrl'
- $ref: '#/components/schemas/payments_ptyPendingDeadlineAt'
- $ref: '#/components/schemas/payments_ptyPaymentMethod'
- $ref: '#/components/schemas/payments_ptySelectedOnRampOffer'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_checkoutTemplateId'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- required:
- nominal_currency
- customer_ip_address
- customer_referer_domain
payments_reqCreatePayment-Invoice:
title: Invoice
allOf:
- $ref: '#/components/schemas/payments_ptyTitle'
- $ref: '#/components/schemas/payments_ptyDescription'
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptySuccessRedirectUrl'
- $ref: '#/components/schemas/payments_ptyFailureRedirectUrl'
- $ref: '#/components/schemas/payments_ptyPendingDeadlineAt'
- $ref: '#/components/schemas/payments_ptyPaymentMethod'
- $ref: '#/components/schemas/payments_ptySelectedOnRampOffer'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyNominalAmount'
- $ref: '#/components/schemas/payments_ptyLossConfig'
- $ref: '#/components/schemas/payments_checkoutTemplateId'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyUnderpaymentConfig'
- $ref: '#/components/schemas/payments_ptyOverpaymentConfig'
- required:
- nominal_currency
- nominal_amount
- customer_ip_address
- customer_referer_domain
payments_reqUpdatePayment:
title: Update payment request
allOf:
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyPaymentData'
- properties:
payment_title:
$ref: '#/components/schemas/payments_schTitle'
payment_description:
$ref: '#/components/schemas/payments_schDescription'
payments_ptyOtherData:
title: Other data
type: object
properties:
other_data:
$ref: '#/components/schemas/payments_schData'
payments_schCustomerIpAddress:
title: Customer IP address
type: string
description: |
IP address (IPv4 or IPv6) of the request sender.
⚠️ Currently our validator accepts empty values for this field, but this
is only temporary. In the next release, this field will become
mandatory. To avoid unexpected integration failures when validation is
enforced, please populate this field from the beginning of your
integration implementation.
ℹ️ Used for API requests only.
example: 0.0.0.0
payments_ptyCustomerIpAddress:
title: Customer IP address
type: object
properties:
customer_ip_address:
$ref: '#/components/schemas/callbacks_schCustomerIpAddress'
payments_schCustomerReferrerDomain:
title: Customer referrer domain
type: string
description: |
The URL of the domain where the buyer is located at the moment of the
request for creating a one-time payment, static address, or initiation
of withdrawal.
⚠️ Currently our validator accepts empty values for this field, but this
is only temporary. In the next release, this field will become
mandatory. To avoid unexpected integration failures when validation is
enforced, please populate this field from the beginning of your
integration implementation.
ℹ️ Used for API requests only.
payments_ptyCustomerReferrerDomain:
title: Customer referrer domain
type: object
properties:
customer_referer_domain:
$ref: '#/components/schemas/callbacks_schCustomerReferrerDomain'
payments_ptyUnderpaymentConfig:
title: Underpayment config
type: object
properties:
underpayment_config:
$ref: '#/components/schemas/payments_schLossConfig'
payments_ptyOverpaymentConfig:
title: Overpayment config
type: object
properties:
overpayment_config:
$ref: '#/components/schemas/payments_schLossConfig'
payments_schDetails:
title: Payment details
allOf:
- $ref: '#/components/schemas/payments_ptyTitle'
- $ref: '#/components/schemas/payments_ptyDescription'
- $ref: '#/components/schemas/payments_ptySuccessRedirectUrl'
- $ref: '#/components/schemas/payments_ptyFailureRedirectUrl'
- $ref: '#/components/schemas/payments_ptyOrderId'
- $ref: '#/components/schemas/payments_ptyCustomerId'
- $ref: '#/components/schemas/payments_ptyCustomerEmail'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyOtherData'
payments_ptyProjectId:
title: Project ID
type: object
properties:
project_id:
type: string
format: uuid
description: |
Project ID.
example: 007dd1e5-cc29-41cb-8522-ccfe13c27e7c
payments_schPaymentId:
title: Payment ID
type: string
format: uuid
description: |
Payment ID.
example: 1f04d164-73de-4b5d-a2b9-4bf1faa05973
payments_ptySelectedPaymentMethod:
title: Selected payment method
type: object
properties:
selected_payment_method:
$ref: '#/components/schemas/payments_resSelectedPaymentMethod'
payments_ptySelectedOnRampOffer:
title: Selected fiat on-ramp offer
type: object
properties:
selected_onramp_offer:
$ref: '#/components/schemas/payments_resSelectedOnRampOffer'
payments_ptyRecommendedAmount:
title: Recommended amount
type: object
properties:
recommended_amount:
type: object
description: |
Recommended amount.
See
[Recommended Amount](#section/Types-of-Payments/Recommended-Amount).
required:
- nominal
properties:
nominal:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Recommended sum of payment in nominal currency displayed to the
customer.
⚠️ The actual payment amount may not correspond to this sum.
ℹ️ Includes fees before being recalculated in payin currency.
ℹ️ Amount in payin currency displayed on our checkout page
(`payment_url`) or obtained via the
`POST /api/v1/payments/payment_methods/calc` call.
payments_ptyId-Payments:
title: ID
type: object
properties:
id:
$ref: '#/components/schemas/payments_schPaymentId'
payments_ptyDetails:
title: Details
type: object
properties:
details:
allOf:
- $ref: '#/components/schemas/payments_schDetails'
description: |
Additional payment details.
payments_ptyPaymentUrl:
title: Payment URL
type: object
properties:
payment_url:
type: string
format: uri
description: |
Link to an individual checkout page hosted by us when the
customer can choose a payment method.
example: https://dba.com/C1408A
payments_ptyCreatedAt-Payments:
title: Created at
type: object
properties:
created_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time the payment initiated.
payments_ptyUpdatedAt-Payments:
title: Updated at
type: object
properties:
updated_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time the payment state last update.
payments_ptyCompletedAt:
title: Completed at
type: object
properties:
completed_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of the transition to the `COMPLETED` state.
payments_ptyDeadlineAt:
title: Deadline at
type: object
properties:
deadline_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Our deadline for a payment in the `WAITING` state.
⚠️ If a payment violates the deadline, it will be transferred
to the `FAILED` state.
payments_resPayment-Deposit:
title: Deposit
allOf:
- $ref: '#/components/schemas/payments_ptyType'
- $ref: '#/components/schemas/payments_ptyId-Payments'
- $ref: '#/components/schemas/payments_ptyState-Payments'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyNominalAmount'
- $ref: '#/components/schemas/payments_ptyRecommendedAmount'
- $ref: '#/components/schemas/payments_ptySelectedPaymentMethod'
- $ref: '#/components/schemas/payments_ptySelectedOnRampOffer'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyPaymentUrl'
- $ref: '#/components/schemas/payments_ptyProjectId'
- $ref: '#/components/schemas/payments_ptyDetails'
- $ref: '#/components/schemas/payments_ptyCreatedAt-Payments'
- $ref: '#/components/schemas/payments_ptyUpdatedAt-Payments'
- $ref: '#/components/schemas/payments_ptyCompletedAt'
- $ref: '#/components/schemas/payments_ptyDeadlineAt'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyError'
- $ref: '#/components/schemas/payments_checkoutTemplateId'
- required:
- id
- project_id
- type
- state
- nominal_currency
- fees_payer
- loss_config
- details
- payment_url
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
payments_resPayment-Invoice:
title: Invoice
allOf:
- $ref: '#/components/schemas/payments_ptyType'
- $ref: '#/components/schemas/payments_ptyId-Payments'
- $ref: '#/components/schemas/payments_ptyState-Payments'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyNominalAmount'
- $ref: '#/components/schemas/payments_ptySelectedPaymentMethod'
- $ref: '#/components/schemas/payments_ptySelectedOnRampOffer'
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyLossConfig'
- $ref: '#/components/schemas/payments_ptyPaymentUrl'
- $ref: '#/components/schemas/payments_ptyProjectId'
- $ref: '#/components/schemas/payments_ptyDetails'
- $ref: '#/components/schemas/payments_ptyCreatedAt-Payments'
- $ref: '#/components/schemas/payments_ptyUpdatedAt-Payments'
- $ref: '#/components/schemas/payments_ptyCompletedAt'
- $ref: '#/components/schemas/payments_ptyDeadlineAt'
- $ref: '#/components/schemas/payments_ptyCustomerIpAddress'
- $ref: '#/components/schemas/payments_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/payments_ptyError'
- $ref: '#/components/schemas/payments_checkoutTemplateId'
- required:
- id
- project_id
- type
- state
- nominal_currency
- nominal_amount
- fees_payer
- loss_config
- details
- payment_url
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
payments_resPayment:
allOf:
- type: object
oneOf:
- $ref: '#/components/schemas/payments_resPayment-Deposit'
- $ref: '#/components/schemas/payments_resPayment-Invoice'
discriminator:
propertyName: type
mapping:
DEPOSIT: '#/components/schemas/payments_resPayment-Deposit'
INVOICE: '#/components/schemas/payments_resPayment-Invoice'
payments_ptyType:
title: Type
type: object
properties:
type:
$ref: '#/components/schemas/payments_schType'
payments_ptyState-Payments:
title: State
type: object
properties:
state:
$ref: '#/components/schemas/payments_schState'
payments_schType:
title: Type
type: string
enum:
- INVOICE
- DEPOSIT
description: |
Payment type.
Values:
* `INVOICE`—a payment of the predefined amount that succeeds only after
the total amount of all detected payins reaches this amount;
* `DEPOSIT`—a deposit of an arbitrary amount that succeeds after the
first detected payin.
payments_schState:
title: State
type: string
enum:
- CREATED
- CANCELED
- WAITING
- FAILED
- COMPLETED
description: |
Payment state.
Values:
* `CREATED`—the customer initiated a payment and picks a payment method;
* `CANCELED`—the merchant deadline specified in `pending_deadline_at` is
exceeded;
* `FAILED`—the payment expired our deadline or failed during processing;
* `WAITING`—a transaction corresponding to the payment is detected in
the blockchain and gains confirmations;
* `COMPLETED`—the payment successfully completed.
payments_resSelectedPaymentMethod:
title: Selected payment method
allOf:
- $ref: '#/components/schemas/payments_ptyHoldingCurrency'
- $ref: '#/components/schemas/payments_ptyHoldingAmount'
- $ref: '#/components/schemas/payments_ptyMinimumPayinAmount'
- required:
- selected_at
- holding_currency
- payin_currency
- payin_address
- minimum_payin_amount
- properties:
selected_at:
$ref: '#/components/schemas/payments_schTimestamp'
nominal_holding_swap:
allOf:
- $ref: '#/components/schemas/payments_schHoldingSwap'
- required:
- txn_id
description: |
Details of a swap created after the payment initialization which
is not guaranteed to be executed after successful payins.
payment_fee:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Fee charged for the payment.
ℹ️ A percent: `0.01` stands for 0.01%.
Format: decimal
example: '0.27'
holding_transfer_txn_id:
type: string
format: uuid
description: |
UUID of the final transfer to the holding account.
example: 8331c46a-56e4-4748-9dd9-7e5e23732cd6
payin_holding_swap:
allOf:
- $ref: '#/components/schemas/payments_schHoldingSwap'
description: |
Transaction produced as a result of the actually committed swap
at the latest stage of the payment.
payin_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Payin currency code.
payin_network:
$ref: '#/components/schemas/payments_schCode-Network'
expected_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Expected payment amount.
Format: decimal
payin_address:
$ref: '#/components/schemas/payments_schAddress'
payin_address_tag:
type: string
description: |
Additional ID of the payment apart from a deposit address.
example: lOqMs91JaKqlwM18Mkqolx
payins:
type: array
items:
$ref: '#/components/schemas/payments_schPayins'
description: |
Payins detected for an invoice payment.
remaining_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Payins amount remaining before we accept the payment.
Format: decimal
example: '0.01'
payments_schRate:
title: Swap rate
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Swap rate.
Format: decimal
example: '30250.48'
payments_schHoldingSwap:
title: Holding swap
type: object
required:
- rate
- time
properties:
rate:
$ref: '#/components/schemas/payments_schRate'
time:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of the swap from default holding currency to holding
currency.
txn_id:
allOf:
- $ref: '#/components/schemas/payments_schTxnId'
description: |
Swap operation UUID.
payments_ptyAmount:
title: Amount
type: object
properties:
amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Amount.
Format: decimal
payments_schPayins:
title: Payins
allOf:
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyNetwork'
- $ref: '#/components/schemas/payments_ptyAmount'
- required:
- amount
- fee
- currency
- network
- txn_hash
- declared_at
properties:
fee:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Deposit fee.
Format: decimal
example: '0.01'
txn_hash:
$ref: '#/components/schemas/payments_schHash'
declared_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of submitting the payin transaction to the
blockchain.
example: '2023-03-22T15:23:56.876Z'
confirmed_at:
allOf:
- $ref: '#/components/schemas/payments_schTimestamp'
description: |
Date and time of gathering sufficient number of confirmations.
example: '2023-03-22T15:23:56.876Z'
payments_resPaymentMethod:
title: Payment method
allOf:
- $ref: '#/components/schemas/payments_ptyCode-Currency'
- $ref: '#/components/schemas/payments_ptyName-Currency'
- $ref: '#/components/schemas/payments_ptyCrypto'
- $ref: '#/components/schemas/payments_ptyPrecision'
- $ref: '#/components/schemas/payments_ptyPriority'
- $ref: '#/components/schemas/payments_ptyAddressTagName'
- $ref: '#/components/schemas/payments_ptyCryptoExplorer'
- $ref: '#/components/schemas/payments_ptyNetworks'
- $ref: '#/components/schemas/payments_ptySwappableTo'
- $ref: '#/components/schemas/payments_ptyPayinEnabled'
- $ref: '#/components/schemas/payments_ptyPayoutEnabled'
- $ref: '#/components/schemas/payments_ptyMinimumSwapAmount'
- $ref: '#/components/schemas/payments_ptyMinimumPayinAmount'
- required:
- name
- code
- crypto
- precision
- networks
- swappable_to
- payin_enabled
- payout_enabled
payments_reqCalcPaymentMethodAmounts:
title: Calculate payment method amounts request
allOf:
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyPayinCurrency'
- $ref: '#/components/schemas/payments_ptyPayinNetwork'
- required:
- nominal_currency
- payin_currency
- amount
- properties:
amount:
oneOf:
- type: object
title: Nominal
required:
- nominal
properties:
nominal:
$ref: '#/components/schemas/payments_schAmount'
description: |
Nominal amount.
- type: object
title: Payin
required:
- payin
properties:
payin:
$ref: '#/components/schemas/payments_schAmount'
description: |
Payin amount.
payments_reqCalcOnRampPaymentMethodAmounts:
allOf:
- $ref: '#/components/schemas/payments_ptyFeesPayer'
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyAmount'
- $ref: '#/components/schemas/payments_ptyCountry'
- $ref: '#/components/schemas/payments_ptyCountryState'
- required:
- nominal_currency
- currency
- amount
- country
payments_ptyCountry:
title: Country
type: object
properties:
country:
$ref: '#/components/schemas/payments_schCountry'
payments_schCountry:
title: Country
type: string
description: ISO 3166-1 country code (Alpha-2)
example: US
payments_ptyCountryState:
title: State
properties:
state:
$ref: '#/components/schemas/payments_schCountryState'
payments_schCountryState:
title: State
type: string
description: ISO 3166-2 state code. Required for the US.
example: NY
payments_resCalcOnRampPaymentMethodAmounts:
type: object
properties:
offers:
type: array
items:
oneOf:
- $ref: '#/components/schemas/payments_schOnRampOffer'
- $ref: '#/components/schemas/payments_schOnRampOfferError'
required:
- offers
payments_schOnRampOffer:
allOf:
- type: object
properties:
offer_id:
$ref: '#/components/schemas/payments_schOnRampOfferId'
provider_code:
$ref: '#/components/schemas/payments_schOnRampProviderCode'
payment_method_code:
$ref: '#/components/schemas/payments_schOnRampPaymentMethod'
onramp_rate:
type: string
format: decimal
required:
- offer_id
- provider_code
- payment_method_code
- onramp_rate
- $ref: '#/components/schemas/payments_resAmount'
payments_schOnRampOfferError:
type: object
required:
- provider_code
- error
properties:
provider_code:
$ref: '#/components/schemas/payments_schOnRampProviderCode'
error:
type: string
examples:
- UNSUPPORTED_CURRENCY
- UNSUPPORTED_COUNTRY
- UNSUPPORTED_STATE
- UNSUPPORTED_PAYMENT_METHOD
- AMOUNT_TOO_LOW
- AMOUNT_TOO_HIGH
- AMOUNT_OUT_OF_LIMITS
- STATE_REQUIRED
- OTHER
payments_schOnRampOfferId:
title: Offer ID
description: On-Ramp offer ID
type: string
example: 42ee97c3-84ee-4759-b49b-2cb3d372ee85
payments_schOnRampOrderId:
title: Order ID
description: On-Ramp order ID
type: string
example: 29ba9a80-6c75-4a1a-a286-6f72ee979ade
payments_schOnRampProviderCode:
title: Provider
description: On-Ramp provider code
examples:
- banxa
- moonpay
- transak
payments_schOnRampPaymentMethod:
title: Payment Method
description: On-Ramp payment method code
examples:
- apple_pay
- card
- sepa_bank_transfer
payments_reqSelectPaymentMethod:
title: Set payment method
allOf:
- $ref: '#/components/schemas/payments_ptyCurrency'
- $ref: '#/components/schemas/payments_ptyNetwork'
- required:
- currency
payments_reqSelectOnRampPaymentMethod:
type: object
required:
- offer_id
- provider_code
- payment_method_code
- currency
- amount
- rate
- amount_expected
- country
properties:
offer_id:
$ref: '#/components/schemas/payments_schOnRampOfferId'
provider_code:
$ref: '#/components/schemas/payments_schOnRampProviderCode'
payment_method_code:
$ref: '#/components/schemas/payments_schOnRampPaymentMethod'
currency:
$ref: '#/components/schemas/payments_schCode-Currency'
amount:
$ref: '#/components/schemas/payments_schAmount'
rate:
type: string
format: decimal
amount_expected:
type: string
format: decimal
country:
$ref: '#/components/schemas/payments_schCountry'
state:
$ref: '#/components/schemas/payments_schCountryState'
payments_resSelectedOnRampOffer:
type: object
required:
- offer_order_id
- provider_code
- provider_name
- payment_method_code
- payment_method_name
- selected_at
- payin_address
- amount
- rate
- currency
- amount_expected
- country
- checkout_url
properties:
offer_order_id:
$ref: '#/components/schemas/payments_schOnRampOrderId'
provider_code:
$ref: '#/components/schemas/payments_schOnRampProviderCode'
provider_name:
type: string
example: Banxa
payment_method_code:
$ref: '#/components/schemas/payments_schOnRampPaymentMethod'
payment_method_name:
type: string
example: SEPA Bank Transfer
selected_at:
type: string
format: date-time
payin_address:
type: string
payin_address_tag:
type: string
amount:
type: string
format: decimal
rate:
type: string
format: decimal
currency:
$ref: '#/components/schemas/payments_schCode-Currency'
amount_expected:
type: string
format: decimal
country:
$ref: '#/components/schemas/payments_schCountry'
state:
$ref: '#/components/schemas/payments_schCountryState'
checkout_url:
type: string
payments_ptyHoldingCurrency:
title: Holding currency
type: object
properties:
holding_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Holding currency.
payments_ptyHoldingAmount:
title: Holding amount
type: object
properties:
holding_amount:
type: string
description: |
Amount credited to the holding account as a result of the
payment minus fees.
Format: decimal
example: '14.08'
payments_ptyPayinCurrency:
title: Payin currency
type: object
properties:
payin_currency:
allOf:
- $ref: '#/components/schemas/payments_schCode-Currency'
description: |
Payin currency.
ℹ️ Specified in `currency` parameter.
payments_ptyPayinNetwork:
title: Payin network
type: object
properties:
payin_network:
allOf:
- $ref: '#/components/schemas/payments_schCode-Network'
description: |
Payin network.
ℹ️ Specified in `network` parameter.
payments_resAmount:
title: Expected amount
allOf:
- $ref: '#/components/schemas/payments_ptyNominalCurrency'
- $ref: '#/components/schemas/payments_ptyNominalAmount'
- $ref: '#/components/schemas/payments_ptyHoldingCurrency'
- $ref: '#/components/schemas/payments_ptyHoldingAmount'
- $ref: '#/components/schemas/payments_ptyPayinCurrency'
- $ref: '#/components/schemas/payments_ptyPayinNetwork'
- $ref: '#/components/schemas/payments_ptyMinimumPayinAmount'
- required:
- nominal_currency
- nominal_amount
- nominal_holding_swap_rate
- holding_currency
- payment_fee
- holding_amount
- payin_holding_swap_rate
- payin_currency
- deposit_fee
- expected_payin_amount
- minimum_payin_amount
- properties:
nominal_holding_swap_rate:
type: string
description: |
Estimated exchange rate from the payment currency to the holding
currency calculated if these do not match.
Format: decimal
example: '2.37'
payin_holding_swap_rate:
type: string
description: |
Estimated exchange rate from the payin currency to the holding
currency calculated if these do not match.
Format: decimal
example: '1'
deposit_fee:
type: string
description: |
Fixed fee charged for deposits.
ℹ️ An absolute value: `0.01` stands for 0.01 USDT.
Format: decimal
example: '0.01'
payment_fee:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
The total payment fee.
Format: decimal
example: '0.97'
expected_payin_amount:
allOf:
- $ref: '#/components/schemas/payments_schAmount'
description: |
Expected amount of payin in payin currency.
Format: decimal
example: '0.0062534748'
payments_resSendCallback:
title: Send callback response
required:
- request
- response
properties:
request:
type: object
required:
- url
- body
- signature
properties:
url:
type: string
format: uri
description: |
Target URL.
example: https://example.com/api/v1/payment/webhook
body:
type: string
description: |
Callback body.
example: >-
{"callback_type":"PAYMENT","payment_id":"80036de2-7aef-4aaf-9205-992647ff730a","project_id":"7388421c-06af-11ee-be56-0242ac120002","type":"INVOICE","state":"CANCELED","nominal_currency":"USDT","nominal_amount":"14.08","fees_payer":"MERCHANT","title":"DBA","description":"Loremipsumdolorsitametconsecteturadipiscingelit...","order_id":"34d3149b-8eb0-4898-971a-63464ae73f1e","customer_id":"24fc0740-c6c6-48d8-9735-6b5f42a350d4","customer_email":"johndoe@example.com","other_data":{"sales_manager_id":221163,"customer_phone":"+999999999"},"selected_payment_method":{"holding_currency":"USDT","holding_amount":"14.08","minimum_payin_amount":"14.08","selected_at":"2023-03-22T15:23:56.876Z","nominal_holding_swap":{},"payment_fee":"0.27","holding_transfer_txn_id":"cec43f26-99a7-48dd-a42e-c332833a3c47","payin_holding_swap":{},"payin_currency":"USDT","payin_network":"ETH","expected_payin_amount":"14.08","remaining_payin_amount":"0.01","payin_address":"0xb794f5ea0ba39494ce839613fffba74279579268","payin_address_tag":"lOqMs91JaKqlwM18Mkqolx","payins":[]},"created_at":"2023-03-22T15:23:56.876Z","updated_at":"2023-03-22T15:23:56.876Z","completed_at":"2023-03-22T15:23:56.876Z","deadline_at":"2023-03-22T15:23:56.876Z"}
signature:
allOf:
- $ref: '#/components/schemas/payments_schSignature'
example: >-
VzMyYzZDT0h3UVR2RFNwNENNMWh5ZE11S3VhWU42ajVEcDl6RG1GaG1pRDlnV25USHI0ZUovVDE4eHZwZGxLdXJmcnhKYSt5RElMelQ0RmRIZUYzVjZYcnNxdzZ3YzhKNi9lZXFyZzc1WnhJek0yN1ZjckFQVXNrazJ3WTFYUFJrK3BqWnpGcTVMRU5ZbHdESFpIOFRPaGtLUTVtbDBQUFFCaDUvVitYTG5BPToxNzEyMjI5NTM5
response:
type: object
required:
- code
- body
properties:
code:
type: integer
description: |
Status code.
example: 200
body:
type: string
description: |
Request result.
example: '{"ok":true}'
payments_ptyType-Errors:
title: Type
type: object
properties:
type:
$ref: '#/components/schemas/payments_schType-Errors'
payments_schType-Errors:
title: Type
type: string
enum:
- BAD_REQUEST
- API_ERROR
description: |
Error type.
payments_ptyCode-Errors:
title: Code
type: object
properties:
code:
$ref: '#/components/schemas/payments_schCode-Errors'
payments_schCode-Errors:
title: Code
type: string
enum:
- INVALID_REQUEST_PARAMETERS
- INVALID_REQUEST_BODY
- INVALID_REQUEST
- TOO_MANY_REQUESTS
- ACCOUNT_IS_DISABLED
- OPERATION_TEMPORARILY_BLOCKED
- NOMINAL_AMOUNT_INVALID
- PAYMENT_METHOD_NOT_SELECTED
- NO_FREE_ADDRESSES
- ADDRESS_ALREADY_EXISTS
- INSUFFICIENT_BALANCE
- MERCHANT_IS_DISABLED
description: |
Error reason.
payments_ptyMessage-Errors:
title: Message
type: object
properties:
message:
$ref: '#/components/schemas/payments_schMessage-Errors'
payments_schMessage-Errors:
type: string
description: |
Error message.
payments_ptyParam-Errors:
title: Parameter
type: object
properties:
param:
$ref: '#/components/schemas/payments_schParam-Errors'
payments_schParam-Errors:
title: Parameter
type: string
description: |
Name of the parameter caused the error.
payments_default:
title: Error
type: object
required:
- errors
properties:
errors:
type: array
items:
allOf:
- $ref: '#/components/schemas/payments_ptyType-Errors'
- $ref: '#/components/schemas/payments_ptyMessage-Errors'
- required:
- type
- message
payments_default-Code:
title: Error
type: object
required:
- errors
properties:
errors:
type: array
items:
allOf:
- $ref: '#/components/schemas/payments_ptyType-Errors'
- $ref: '#/components/schemas/payments_ptyMessage-Errors'
- $ref: '#/components/schemas/payments_ptyCode-Errors'
- required:
- type
- message
payments_default-Code-Param:
title: Error
type: object
required:
- errors
properties:
errors:
type: array
items:
allOf:
- $ref: '#/components/schemas/payments_ptyType-Errors'
- $ref: '#/components/schemas/payments_ptyMessage-Errors'
- $ref: '#/components/schemas/payments_ptyCode-Errors'
- $ref: '#/components/schemas/payments_ptyParam-Errors'
- required:
- type
- message
payments_errBadRequest:
title: Bad request
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Bad request.
example:
errors:
- type: BAD_REQUEST
message: bad request
payments_errUnauthorized:
title: Unauthorized
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Requested address do not march the project or merchant.
example:
errors:
- type: BAD_REQUEST
message: unauthorized
payments_errForbidden:
title: Forbidden
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Requested operation is not allowed.
example:
errors:
- type: BAD_REQUEST
message: forbidden
payments_errNotFound:
title: Not found
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Requested resource not found.
example:
errors:
- type: BAD_REQUEST
message: not found
payments_errAlreadyExists:
title: Already exists
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Bad request.
example:
errors:
- type: BAD_REQUEST
message: already exists
payments_errResourceBusy:
title: Resource busy
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Cannot alter requested resource.
example:
errors:
- type: BAD_REQUEST
message: resource is busy
payments_errTooManyRequests:
title: Too many requests
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Too many requests.
example:
errors:
- type: BAD_REQUEST
code: TOO_MANY_REQUESTS
message: too many requests
payments_errUnavailableNow:
title: Unavailable now
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Service unavailable.
example:
errors:
- type: API_ERROR
message: service unavailable now
payments_errUnknown:
title: Unknown
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Unknown error.
example:
errors:
- type: API_ERROR
message: unknown error
payments_errInternal:
title: Internal
allOf:
- $ref: '#/components/schemas/payments_default'
description: |
Internal server error.
example:
errors:
- type: API_ERROR
message: internal server error
payments_errInvalidRequestParameters:
title: Invalid request parameters
allOf:
- $ref: '#/components/schemas/payments_default-Code-Param'
description: ''
example:
errors:
- type: BAD_REQUEST
code: INVALID_REQUEST_PARAMETERS
message:
param:
payments_errInvalidRequestBody:
title: Invalid request body
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Invalid request body.
example:
errors:
- type: BAD_REQUEST
code: INVALID_REQUEST_BODY
message:
payments_errInvalidRequest:
title: Invalid request
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Invalid request.
example:
errors:
- type: BAD_REQUEST
code: INVALID_REQUEST
message:
payments_errPaymentMethodNotSelected:
title: Payment method not selected
allOf:
- $ref: '#/components/schemas/payments_default-Code-Param'
description: |
Missing payment method.
example:
errors:
- type: BAD_REQUEST
code: PAYMENT_METHOD_NOT_SELECTED
message: payment_method is required for recommended_amount.payin
param: payment_method
payments_errNominalAmountInvalid:
title: Nominal amount invalid
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Invalid nominal amount.
example:
errors:
- type: API_ERROR
code: NOMINAL_AMOUNT_INVALID
message:
payments_errNoFreeAddresses:
title: No free addresses
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
No free deposit addresses in the pool of addresses.
example:
errors:
- type: API_ERROR
code: NO_FREE_ADDRESSES
message: no free addresses in the pool
payments_errAddressAlreadyExists:
title: Address already exists
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Deposit address generated for provided parameters already exists.
example:
errors:
- type: API_ERROR
code: ADDRESS_ALREADY_EXISTS
message: customer static deposit address already exists
payments_errAccountIsDisabled:
title: Account is disabled
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Holding account is disabled.
example:
errors:
- type: API_ERROR
code: ACCOUNT_IS_DISABLED
message: the account is disabled
payments_errOperationBlocked:
title: Operation blocked
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Requested operation is temporary disabled.
example:
errors:
- type: API_ERROR
code: OPERATION_TEMPORARILY_BLOCKED
message: requested operation is temporarily blocked
payments_errMerchantIsDisabled:
title: Merchant is disabled
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Merchant is disabled.
example:
errors:
- type: API_ERROR
code: MERCHANT_IS_DISABLED
message: cannot perform operation; this account is disabled
payments_errInsufficientBalance:
title: Insufficient balance
allOf:
- $ref: '#/components/schemas/payments_default-Code'
description: |
Holding account balance is insufficient for the withdrawal.
example:
errors:
- type: API_ERROR
code: INSUFFICIENT_BALANCE
message: balance is insufficient for the requested operation
payments_errCurrencyNotFound:
title: Currency not found
allOf:
- $ref: '#/components/schemas/payments_default-Code-Param'
description: |
Currency not found.
example:
errors:
- code: INVALID_REQUEST_PARAMETERS
message: 'not found: currency'
type: API_ERROR
param: currency
payments_errNetworkNotFound:
title: Network not found
allOf:
- $ref: '#/components/schemas/payments_default-Code-Param'
description: |
Network not found.
example:
errors:
- code: INVALID_REQUEST_PARAMETERS
message: network is not found
type: API_ERROR
param: network
payments_errNetworkRequired:
title: Network required
allOf:
- $ref: '#/components/schemas/payments_default-Code-Param'
description: |
Network parameter not provided.
example:
errors:
- code: INVALID_REQUEST_PARAMETERS
message: network is required
type: API_ERROR
param: network
callbacks_schCode:
title: Code
type: string
pattern: ^[A-Z0-9]{2,16}$
minLength: 2
maxLength: 16
callbacks_schAddress:
title: Address
type: string
description: |
Deposit address.
example: '0xb794f5ea0ba39494ce839613fffba74279579268'
callbacks_schCode-Currency:
title: Currency code
allOf:
- $ref: '#/components/schemas/callbacks_schCode'
description: |
Currency code.
example: USDT
callbacks_schCode-Network:
title: Network code
allOf:
- $ref: '#/components/schemas/callbacks_schCode'
description: |
Network code.
example: ETH
callbacks_schTimestamp:
title: Timestamp
type: string
format: date-time
example: '2023-03-22T15:23:56.876Z'
callbacks_schPaymentId:
title: Payment ID
type: string
format: uuid
description: |
Payment ID.
example: 2838302c-a433-4a52-912c-91877ca62178
callbacks_ptyCurrency:
title: Currency
type: object
properties:
currency:
$ref: '#/components/schemas/callbacks_schCode-Currency'
callbacks_ptyNetwork:
title: Network
type: object
properties:
network:
$ref: '#/components/schemas/callbacks_schCode-Network'
callbacks_ptyPaymentId:
title: Payment ID
type: object
properties:
payment_id:
$ref: '#/components/schemas/callbacks_schPaymentId'
callbacks_ptyProjectId:
title: Project ID
type: object
properties:
project_id:
type: string
format: uuid
description: |
Project ID.
example: a157bba8-1aed-46f8-a91b-d89d8476aab0
callbacks_schState-Payments:
title: Payment states
type: string
enum:
- CREATED
- CANCELED
- WAITING
- FAILED
- COMPLETED
description: |
Payment state.
Values:
* `CREATED`—the customer initiated a payment and picks a payment method;
* `CANCELED`—the merchant deadline specified in `pending_deadline_at` is
exceeded;
* `FAILED`—the payment expired our deadline or failed during processing;
* `WAITING`—a transaction corresponding to the payment is detected in
the blockchain and gains confirmations;
* `COMPLETED`—the payment successfully completed.
callbacks_ptyState-Payments:
title: State
type: object
properties:
state:
$ref: '#/components/schemas/callbacks_schState-Payments'
callbacks_ptyType:
title: Type
type: object
properties:
type:
$ref: '#/components/schemas/callbacks_schType'
callbacks_schType:
title: Type
type: string
enum:
- INVOICE
- DEPOSIT
description: |
Payment type.
Values:
* `INVOICE`—a payment of the predefined amount that succeeds only after
the total amount of all detected payins reaches this amount;
* `DEPOSIT`—a deposit of an arbitrary amount that succeeds after the
first detected payin.
callbacks_ptyNominalCurrency:
title: Nominal currency
type: object
properties:
nominal_currency:
type: string
description: |
The desired currency of payment.
ℹ️ This currency also denominates the amount specified in
`nominal_amount`.
example: USDT
callbacks_schAmount:
title: Amount
type: string
maxLength: 128
description: |
Amount.
Format: decimal
example: '14.08'
callbacks_ptyAmount:
title: Amount
type: object
properties:
amount:
$ref: '#/components/schemas/callbacks_schAmount'
callbacks_ptyNominalAmount:
title: Nominal amount
type: object
properties:
nominal_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
The desired amount of a payment.
⚠️ A payment will not complete until this amount is sent by the
customer.
Format: decimal
callbacks_ptyFeesPayer:
title: Fees payer
type: object
properties:
fees_payer:
type: string
enum:
- MERCHANT
- CUSTOMER
description: |
The party that pays fees.
Values:
* `MERCHANT`—the amount of payment is not affected by fees;
* `CUSTOMER`—the amount of a payment is reduced by fees.
callbacks_schTitle:
title: Title
type: string
maxLength: 255
description: |
Payment custom name shown to the customer.
example: DBA
callbacks_ptyTitle:
title: Title
type: object
properties:
title:
$ref: '#/components/schemas/callbacks_schTitle'
callbacks_schDescription:
title: Description
type: string
maxLength: 4096
description: |
Payment custom description.
example: Lorem ipsum dolor sit amet consectetur adipiscing elit...
callbacks_ptyDescription:
title: Description
type: object
properties:
description:
$ref: '#/components/schemas/callbacks_schDescription'
callbacks_ptyOrderId:
title: Order ID
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 36
description: |
Arbitrary operation ID generated of the merchant side.
example: 34d3149b-8eb0-4898-971a-63464ae73f1e
callbacks_schCustomerId:
title: Customer ID
type: string
minLength: 1
maxLength: 36
description: |
Arbitrary customer ID.
example: 24fc0740-c6c6-48d8-9735-6b5f42a350d4
callbacks_ptyCustomerId:
title: Customer ID
type: object
properties:
customer_id:
$ref: '#/components/schemas/callbacks_schCustomerId'
callbacks_ptyCustomerEmail:
title: Customer email
type: object
properties:
customer_email:
type: string
format: email
maxLength: 255
description: |
Customer email.
example: johndoe@example.com
callbacks_schData:
type: object
additionalProperties: true
description: |
Arbitrary metadata associated with the payment.
example:
sales_manager_id: 221163
customer_phone: '+999999999'
callbacks_ptyOtherData:
title: Other data
type: object
properties:
other_data:
$ref: '#/components/schemas/callbacks_schData'
callbacks_ptyHoldingCurrency:
title: Holding currency
type: object
properties:
holding_currency:
allOf:
- $ref: '#/components/schemas/callbacks_schCode-Currency'
description: |
Holding currency.
callbacks_ptyHoldingAmount:
title: Holding amount
type: object
properties:
holding_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Amount credited to the holding account as a result of the payment
minus fees.
Format: decimal
example: '14.08'
callbacks_ptyMinimumPayinAmount:
title: Minimum payin amount
type: object
properties:
minimum_payin_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Minimum payin amount.
Format: decimal
callbacks_schTxnId:
title: Transaction ID
type: string
format: uuid
description: |
Transaction UUID.
example: e1dbb8b8-cb76-4dc1-8be9-68d751d6cd1a
callbacks_schRate:
title: Swap rate
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Swap rate.
Format: decimal
example: '30250.48'
callbacks_schHoldingSwap:
title: Holding swap
type: object
required:
- rate
- time
properties:
rate:
$ref: '#/components/schemas/callbacks_schRate'
time:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time of the swap from default holding currency to holding
currency.
txn_id:
allOf:
- $ref: '#/components/schemas/callbacks_schTxnId'
description: |
Swap operation UUID.
callbacks_resSelectedPaymentMethod:
title: Selected payment method
allOf:
- $ref: '#/components/schemas/callbacks_ptyHoldingCurrency'
- $ref: '#/components/schemas/callbacks_ptyHoldingAmount'
- $ref: '#/components/schemas/callbacks_ptyMinimumPayinAmount'
- required:
- selected_at
- holding_currency
- payin_currency
- payin_address
- minimum_payin_amount
- properties:
selected_at:
$ref: '#/components/schemas/callbacks_schTimestamp'
nominal_holding_swap:
allOf:
- $ref: '#/components/schemas/callbacks_schHoldingSwap'
- required:
- txn_id
description: |
Details of a swap created after the payment initialization which
is not guaranteed to be executed after successful payins.
payment_fee:
type: string
description: |
Fee charged for the payment.
ℹ️ A percent: `0.01` stands for 0.01%.
Format: decimal
example: '0.27'
holding_transfer_txn_id:
type: string
format: uuid
description: |
UUID of the final transfer to the holding account.
example: fe442f6b-4846-4ec6-8199-7859afc9facb
payin_holding_swap:
allOf:
- $ref: '#/components/schemas/callbacks_schHoldingSwap'
description: |
Transaction produced as a result of the actually committed swap
at the latest stage of the payment.
payin_currency:
allOf:
- $ref: '#/components/schemas/callbacks_schCode-Currency'
description: |
Payin currency code.
payin_network:
$ref: '#/components/schemas/callbacks_schCode-Network'
expected_payin_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Expected payment amount.
Format: decimal
remaining_payin_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Payins amount remaining before we accept the payment.
Format: decimal
example: '0.01'
payin_address:
$ref: '#/components/schemas/callbacks_schAddress'
payin_address_tag:
type: string
description: |
Additional ID of the payment apart from a deposit address.
example: lOqMs91JaKqlwM18Mkqolx
payins:
type: array
items:
$ref: '#/components/schemas/callbacks_schPayins'
description: |
Payins detected for a payment.
callbacks_schHash:
title: Hash
type: string
description: |
Network transaction hash.
example: 0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20
callbacks_schPayins:
title: Payins
allOf:
- $ref: '#/components/schemas/callbacks_ptyCurrency'
- $ref: '#/components/schemas/callbacks_ptyNetwork'
- $ref: '#/components/schemas/callbacks_ptyAmount'
- required:
- amount
- fee
- currency
- network
- txn_hash
- declared_at
- properties:
fee:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Deposit fee.
Format: decimal
example: '0.01'
txn_hash:
$ref: '#/components/schemas/callbacks_schHash'
declared_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time of submitting the payin transaction to the
blockchain.
example: '2023-03-22T15:23:56.876Z'
confirmed_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time of gathering sufficient number of confirmations.
example: '2023-03-22T15:23:56.876Z'
callbacks_ptySelectedPaymentMethod:
title: Selected payment method
type: object
properties:
selected_payment_method:
$ref: '#/components/schemas/callbacks_resSelectedPaymentMethod'
callbacks_ptyCreatedAt-Payments:
title: Created at
type: object
properties:
created_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time the payment initiated.
callbacks_ptyUpdatedAt-Payments:
title: Updated at
type: object
properties:
updated_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time the payment state last update.
callbacks_ptyCompletedAt:
title: Completed at
type: object
properties:
completed_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Date and time of the transition to the `COMPLETED` state.
callbacks_ptyDeadlineAt:
title: Deadline at
type: object
properties:
deadline_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Our deadline for a payment in the `WAITING` state.
⚠️ If a payment violates the deadline, it will be transferred
to the `FAILED` state.
callbacks_schCustomerIpAddress:
title: Customer IP address
type: string
description: |
IP address (IPv4 or IPv6) of the request sender.
⚠️ Currently our validator accepts empty values for this field, but
this is only temporary. In the next release, this field will become
mandatory. To avoid unexpected integration failures when validation
is enforced, please populate this field from the beginning of your
integration implementation.
ℹ️ Used for API requests only.
example: 0.0.0.0
callbacks_ptyCustomerIpAddress:
title: Customer IP address
type: object
properties:
customer_ip_address:
$ref: '#/components/schemas/callbacks_schCustomerIpAddress'
callbacks_schCustomerReferrerDomain:
title: Customer referrer domain
type: string
description: |
The URL of the domain where the buyer is located at the moment of the
request for creating a one-time payment, static address, or initiation
of withdrawal.
⚠️ Currently our validator accepts empty values for this field, but this
is only temporary. In the next release, this field will become
mandatory. To avoid unexpected integration failures when validation is
enforced, please populate this field from the beginning of your
integration implementation.
ℹ️ Used for API requests only.
callbacks_ptyCustomerReferrerDomain:
title: Customer referrer domain
type: object
properties:
customer_referer_domain:
$ref: '#/components/schemas/callbacks_schCustomerReferrerDomain'
callbacks_reqPayment:
title: Payment (success)
allOf:
- $ref: '#/components/schemas/callbacks_ptyCallbackType'
- $ref: '#/components/schemas/callbacks_ptyPaymentId'
- $ref: '#/components/schemas/callbacks_ptyType'
- $ref: '#/components/schemas/callbacks_ptyState-Payments'
- $ref: '#/components/schemas/callbacks_ptyNominalCurrency'
- $ref: '#/components/schemas/callbacks_ptyNominalAmount'
- $ref: '#/components/schemas/callbacks_ptySelectedPaymentMethod'
- $ref: '#/components/schemas/callbacks_ptyFeesPayer'
- $ref: '#/components/schemas/callbacks_ptyTitle'
- $ref: '#/components/schemas/callbacks_ptyDescription'
- $ref: '#/components/schemas/callbacks_ptyProjectId'
- $ref: '#/components/schemas/callbacks_ptyOrderId'
- $ref: '#/components/schemas/callbacks_ptyCustomerId'
- $ref: '#/components/schemas/callbacks_ptyCustomerEmail'
- $ref: '#/components/schemas/callbacks_ptyOtherData'
- $ref: '#/components/schemas/callbacks_ptyCustomerIpAddress'
- $ref: '#/components/schemas/callbacks_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/callbacks_ptyCreatedAt-Payments'
- $ref: '#/components/schemas/callbacks_ptyUpdatedAt-Payments'
- $ref: '#/components/schemas/callbacks_ptyCompletedAt'
- $ref: '#/components/schemas/callbacks_ptyDeadlineAt'
- required:
- callback_type
- payment_id
- project_id
- type
- state
- nominal_currency
- fees_payer
- payment_url
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- example:
callback_type: PAYMENT
payment_id: d7d15ac2-e189-4a48-83d1-d605d6f6d2bf
project_id: 3a771452-4cb8-4035-af07-5e8dc9b8f96a
type: INVOICE
state: COMPLETED
nominal_currency: USD
nominal_amount: '5'
fees_payer: CUSTOMER
selected_payment_method:
selected_at: '2025-05-21T12:37:17Z'
nominal_holding_swap:
rate: '1'
time: '2025-05-21T12:37:16Z'
holding_currency: USDT
holding_amount: '5.015'
payment_fee: '0.015'
received_amount: '5'
holding_transfer_txn_id: 498b5b85-0ea0-4d99-8a72-0d62a50d3ee9
payin_holding_swap:
rate: '1'
time: '2025-05-21T12:37:16Z'
payin_currency: USDT
payin_network: TRX
expected_payin_amount: '5.815'
received_payin_amount: '9.090101'
received_holding_amount: '8.290101'
received_nominal_amount: '8.27'
remaining_payin_amount: '0'
minimum_payin_amount: '0.88'
payin_address: TYx0zXTN7ubkbs7NyXrN6WLs9AUsY298zg
payins:
- amount: '9.090101'
fee: '0.8'
currency: USDT
network: TRX
txn_hash: >-
9194999cb90ce3dd77caa6afc316d7e7069640298bda69bcc9209bf5156f93a9
declared_at: '2025-05-21T12:39:39Z'
confirmed_at: '2025-05-21T12:39:51Z'
created_at: '2025-05-21T12:37:06Z'
updated_at: '2025-05-21T12:39:59Z'
deadline_at: '2025-05-23T12:37:17Z'
completed_at: '2025-05-21T12:39:59Z'
callbacks_errPayment:
title: Payment (error)
allOf:
- $ref: '#/components/schemas/callbacks_ptyCallbackType'
- $ref: '#/components/schemas/callbacks_ptyPaymentId'
- $ref: '#/components/schemas/callbacks_ptyType'
- $ref: '#/components/schemas/callbacks_ptyState-Payments'
- $ref: '#/components/schemas/callbacks_ptyNominalCurrency'
- $ref: '#/components/schemas/callbacks_ptyNominalAmount'
- $ref: '#/components/schemas/callbacks_ptySelectedPaymentMethod'
- $ref: '#/components/schemas/callbacks_ptyFeesPayer'
- $ref: '#/components/schemas/callbacks_ptyTitle'
- $ref: '#/components/schemas/callbacks_ptyDescription'
- $ref: '#/components/schemas/callbacks_ptyProjectId'
- $ref: '#/components/schemas/callbacks_ptyOrderId'
- $ref: '#/components/schemas/callbacks_ptyCustomerId'
- $ref: '#/components/schemas/callbacks_ptyCustomerEmail'
- $ref: '#/components/schemas/callbacks_ptyOtherData'
- $ref: '#/components/schemas/callbacks_ptyCustomerIpAddress'
- $ref: '#/components/schemas/callbacks_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/callbacks_ptyCreatedAt-Payments'
- $ref: '#/components/schemas/callbacks_ptyUpdatedAt-Payments'
- $ref: '#/components/schemas/callbacks_ptyCompletedAt'
- $ref: '#/components/schemas/callbacks_ptyDeadlineAt'
- $ref: '#/components/schemas/callbacks_ptyError'
- required:
- callback_type
- payment_id
- project_id
- type
- state
- nominal_currency
- fees_payer
- payment_url
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- error
- example:
callback_type: PAYMENT
payment_id: 8d4e7c5b-318c-47c5-bf39-5195f6ee24e0
project_id: 77ae12fb-8cac-46d0-b812-e26970a016e2
type: DEPOSIT
state: FAILED
nominal_currency: TRX
nominal_amount: '0.099993'
fees_payer: MERCHANT
selected_payment_method:
selected_at: '2025-07-23T10:57:50Z'
nominal_holding_swap:
rate: '0.1308488790559265'
time: '2025-07-23T10:59:32Z'
holding_currency: USDT
payment_fee: '0.000072'
holding_amount: '0.011972'
payin_holding_swap:
rate: '0.1308415300546448'
time: '2025-07-23T10:59:32Z'
payin_currency: TRX
payin_network: TRX
expected_payin_amount: '0.1'
remaining_payin_amount: '0'
minimum_payin_amount: '14.185704'
payin_address: 9HGnrn59CQrRFw7HDPnHyVZjdQ2DbpSEKW
payins:
- amount: '0.1'
fee: '0.0085'
currency: TRX
network: TRX
txn_hash: >-
cae7926190900ceca1da15dfed4bba132d6ca46e5563709c09df57d7f7d6b8e9
declared_at: '2025-07-23T10:59:32Z'
error:
message: >-
The order has been failed because the payin amount is below the
minimum amount
created_at: '2025-07-23T10:57:42Z'
updated_at: '2025-07-23T10:59:33Z'
deadline_at: '2025-07-23T14:57:49Z'
completed_at: '2025-07-23T10:59:33Z'
callbacks_ptyId-Withdrawals:
title: Withdrawal ID
type: object
properties:
id:
$ref: '#/components/schemas/callbacks_schTxnId'
callbacks_schCode-Currency-To:
title: Currency to
allOf:
- $ref: '#/components/schemas/callbacks_schCode-Currency'
description: |
Target currency.
example: BTC
callbacks_ptyReceiveCurrency:
title: Receive currency
type: object
properties:
receive_currency:
allOf:
- $ref: '#/components/schemas/callbacks_schCode-Currency-To'
description: |
The currency credited to the merchant as the result of a withdrawal.
callbacks_ptyReceiveNetwork:
title: Receive network
type: object
properties:
receive_network:
$ref: '#/components/schemas/callbacks_schCode-Network'
callbacks_ptyCreditCurrency:
title: Credit currency
type: object
properties:
credit_currency:
allOf:
- $ref: '#/components/schemas/callbacks_schCode-Currency'
description: |
The holding currency.
callbacks_schAmountTo:
title: Amount to
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Estimated amount in target currency.
Format: decimal
example: '0.00007'
callbacks_ptyReceiveAmount:
title: Receive amount
type: object
properties:
receive_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmountTo'
description: |
The amount of crypto the merchant must receive as the result of a
withdrawals (fees not included).
Format: decimal
callbacks_ptyCreditAmount:
title: Credit amount
type: object
properties:
credit_amount:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
The amount of crypto the merchant withdraws from the holding account
(fees included).
Format: decimal
callbacks_ptyFee:
title: Fee
type: object
properties:
fee:
allOf:
- $ref: '#/components/schemas/callbacks_schAmount'
description: |
Withdrawal fee amount.
Format: decimal
example: '0.14'
callbacks_schState-Withdrawals:
title: State
type: string
enum:
- PENDING
- COMPLETED
- CANCELED
- FAILED
description: |
Withdrawal state.
Values:
* `PENDING`—a transaction has been created and either waiting to be sent
to the blockchain or has been sent to the blockchain and gains
confirmations;
* `CANCELED`—the transaction has been rolled back;
* `FAILED`—transaction has failed before being created or on latest
stages;
* `COMPLETED`—transaction has been successfully completed.
callbacks_ptyState-Withdrawals:
title: State
type: object
properties:
state:
$ref: '#/components/schemas/callbacks_schState-Withdrawals'
callbacks_ptyTxnId:
title: Payout UUID
type: object
properties:
txn_id:
allOf:
- $ref: '#/components/schemas/callbacks_schTxnId'
description: |
UUID of the payout corresponding to this withdrawal.
example: a0cdbe86-f568-4b7d-a696-8c31effe10b1
callbacks_ptyAddress:
title: Address
type: string
properties:
address:
$ref: '#/components/schemas/callbacks_schAddress'
callbacks_schAddressTag:
title: Address tag
type: string
description: |
Address tag value.
example: 33672098-c31e-4790-b4ed-27fd48638a3e
callbacks_ptyAddressTag:
title: Address tag
type: object
properties:
address_tag:
$ref: '#/components/schemas/callbacks_schAddressTag'
callbacks_schCallbackType:
title: Callback type
type: string
enum:
- PAYMENT
- WITHDRAWAL
description: |
Callback type.
callbacks_ptyCallbackType:
title: Callback type
type: object
properties:
callback_type:
$ref: '#/components/schemas/callbacks_schCallbackType'
callbacks_ptyError:
title: Error
type: object
properties:
error:
$ref: '#/components/schemas/callbacks_schError'
callbacks_schError:
title: Error
type: object
properties:
message:
type: string
description: |
Error caused payment failure.
example: >-
The order has been failed because the payin amount is below the
minimum amount
callbacks_schCanceledBy:
title: Canceled by
type: object
required:
- id
- name
- email
properties:
id:
type: string
format: uuid
description: |
Cabinet user UUID.
name:
type: string
description: |
Cabinet user name
email:
type: string
format: email
description: |
Cabinet user email.
callbacks_reqWithdrawal:
title: Withdrawal (success)
allOf:
- $ref: '#/components/schemas/callbacks_ptyCallbackType'
- $ref: '#/components/schemas/callbacks_ptyId-Withdrawals'
- $ref: '#/components/schemas/callbacks_ptyState-Withdrawals'
- $ref: '#/components/schemas/callbacks_ptyReceiveCurrency'
- $ref: '#/components/schemas/callbacks_ptyReceiveNetwork'
- $ref: '#/components/schemas/callbacks_ptyCreditCurrency'
- $ref: '#/components/schemas/callbacks_ptyReceiveAmount'
- $ref: '#/components/schemas/callbacks_ptyCreditAmount'
- $ref: '#/components/schemas/callbacks_ptyTxnId'
- $ref: '#/components/schemas/callbacks_ptyFee'
- $ref: '#/components/schemas/callbacks_ptyAddress'
- $ref: '#/components/schemas/callbacks_ptyAddressTag'
- $ref: '#/components/schemas/callbacks_ptyOrderId'
- $ref: '#/components/schemas/callbacks_ptyCustomerIpAddress'
- $ref: '#/components/schemas/callbacks_ptyCustomerReferrerDomain'
- required:
- callback_type
- id
- receive_currency
- receive_amount
- credit_currency
- credit_amount
- fee
- state
- address
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- properties:
created_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Withdrawal created.
canceled_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction rolled back.
canceled_by:
allOf:
- $ref: '#/components/schemas/callbacks_schCanceledBy'
description: |
Identity of the cabinet user who canceled the withdrawal.
sent_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction sent to the blockchain.
committed_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction committed in the blockchain.
updated_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Withdrawal status updated.
- example:
callback_type: WITHDRAWAL
id: df390018-a2fc-433a-b969-abdb5224415b
state: COMPLETED
credit_currency: TRX
credit_amount: '1.100001'
swap_rate: '0'
nominal_receive_amount: '0'
receive_currency: TRX
receive_network: TRX
receive_amount: '0.000001'
network_fee: '1.1'
fee: '1.1'
address: ''
txn_id: 12e6acaf-3aba-442b-b72e-739fa47fa2fe
committed_at: '2025-05-22T07:57:43Z'
hash: 0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20
sent_at: '2025-05-22T07:58:04Z'
created_at: '2025-05-22T07:57:09Z'
updated_at: '2025-05-23T09:27:14Z'
callbacks_errWithdrawal:
title: Withdrawal (error)
allOf:
- $ref: '#/components/schemas/callbacks_ptyCallbackType'
- $ref: '#/components/schemas/callbacks_ptyId-Withdrawals'
- $ref: '#/components/schemas/callbacks_ptyState-Withdrawals'
- $ref: '#/components/schemas/callbacks_ptyReceiveCurrency'
- $ref: '#/components/schemas/callbacks_ptyReceiveNetwork'
- $ref: '#/components/schemas/callbacks_ptyCreditCurrency'
- $ref: '#/components/schemas/callbacks_ptyReceiveAmount'
- $ref: '#/components/schemas/callbacks_ptyCreditAmount'
- $ref: '#/components/schemas/callbacks_ptyTxnId'
- $ref: '#/components/schemas/callbacks_ptyFee'
- $ref: '#/components/schemas/callbacks_ptyAddress'
- $ref: '#/components/schemas/callbacks_ptyAddressTag'
- $ref: '#/components/schemas/callbacks_ptyOrderId'
- $ref: '#/components/schemas/callbacks_ptyCustomerIpAddress'
- $ref: '#/components/schemas/callbacks_ptyCustomerReferrerDomain'
- $ref: '#/components/schemas/callbacks_ptyError'
- required:
- callback_type
- id
- receive_currency
- receive_amount
- credit_currency
- credit_amount
- fee
- state
- address
- customer_ip_address
- customer_referer_domain
- created_at
- updated_at
- error
- properties:
note:
type: string
description: |
Text comment.
created_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Withdrawal created.
canceled_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction rolled back.
canceled_by:
allOf:
- $ref: '#/components/schemas/callbacks_schCanceledBy'
description: |
Identity of the cabinet user who canceled the withdrawal.
sent_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction sent to the blockchain.
committed_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Transaction committed in the blockchain.
updated_at:
allOf:
- $ref: '#/components/schemas/callbacks_schTimestamp'
description: |
Withdrawal status updated.
- example:
callback_type: WITHDRAWAL
id: d693f8db-fbcb-46ca-a3e2-ff55b1d0cec8
note: test
order_id: '12345'
state: FAILED
credit_currency: USDC
credit_amount: '0'
swap_rate: '0'
nominal_receive_currency: EUR_VIRTUAL
nominal_receive_amount: '6'
receive_currency: USDC
receive_network: ETH
receive_amount: '0'
network_fee: '0'
fee: '0'
address: '123222'
error:
message: Withdrawal has been declined by your project team member
created_at: '2025-05-22T13:58:39Z'
updated_at: '2025-05-23T09:25:35Z'
callbacks_reqCallback:
allOf:
- type: object
oneOf:
- $ref: '#/components/schemas/callbacks_reqPayment'
- $ref: '#/components/schemas/callbacks_errPayment'
- $ref: '#/components/schemas/callbacks_reqWithdrawal'
- $ref: '#/components/schemas/callbacks_errWithdrawal'
discriminator:
propertyName: callback_type
mapping:
PAYMENT: '#/components/schemas/callbacks_reqPayment'
WITHDRAWAL: '#/components/schemas/callbacks_reqWithdrawal'
responses:
payments_res204:
description: No Content
payments_err400:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errBadRequest'
payments_err401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errUnauthorized'
payments_err403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errForbidden'
payments_err404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errNotFound'
payments_err409:
description: Conflict
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errAlreadyExists'
- $ref: '#/components/schemas/payments_errResourceBusy'
payments_err429:
description: Too Many Requests
headers:
Retry-After:
schema:
type: integer
description: |
Time in milliseconds to wait before making a new request.
example: 3600
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errTooManyRequests'
payments_err500:
description: Internal Server Error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/payments_errInternal'
- $ref: '#/components/schemas/payments_errUnknown'
payments_err503:
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/payments_errUnavailableNow'
securitySchemes:
payments_APIKeyAuth:
type: apiKey
in: header
name: X-Api-Key
description: |
Public part of an API key.