openapi: 3.0.0 info: title: Merchant Backend V2 version: '1.0' description: Documentation for merchant backend processing endpoints servers: - url: https://app.cryptoprocessing.com/api tags: - name: Status - name: Balance - name: Currencies - name: Deposit addresses - name: Withdrawal - name: Exchange - name: Invoices - name: Transactions security: - xProcessingKey: [] paths: /v2/ping: get: summary: Check status description: Test if your API connection is working. responses: '200': description: OK content: text/html: examples: Success: value: OK operationId: get-ping tags: - Status security: - {} /v2/accounts/list: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Get a list of balances description: Get a list of your balances for every currency, both crypto and fiat. tags: - Balance operationId: post-accounts-list responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: currency: type: string description: Asset or currency code. type: type: string description: Asset type. enum: - crypto - fiat balance: type: string description: Account balance as a decimal string, may be negative. examples: Basic example: value: data: - currency: BTC type: crypto balance: "0.04" - currency: EUR type: fiat balance: "10000" '400': $ref: '#/components/responses/MalformedJson' '403': $ref: '#/components/responses/HeaderAuthorization' requestBody: required: true description: | The `Content-Type: application/json` header must be specified even though the request body has no fields. content: application/json: schema: type: object description: | This endpoint does not accept any request parameters, but you must still send an empty JSON object (`{}`) in the request body. additionalProperties: false examples: Empty body: value: {} /v2/currencies/list: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Get a list of currencies description: Get a list of available currencies, minimum deposit amounts, and deposit and withdrawal fees. tags: - Currencies responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer description: Currency ID. type: type: string description: Currency type (crypto or fiat). enum: - crypto - fiat currency: type: string description: Currency code. minimum_amount: type: string description: The minimum deposit amount for this currency. minimum_withdrawal_amount: type: string description: The minimum withdrawal amount for this currency. deposit_confirmations: type: integer description: | The number of confirmations required before a deposit is credited. For some cryptocurrencies, smaller amount deposits may require less confirmations than returned by the API before the funds are credited. See [Confirmations and limits](/confirmations-and-limits) for the number of confirmations required in such cases. deposit_fee_percent: type: string description: The fee that is charged for deposits in this currency, in percentage of the deposit amount. withdrawal_fee_percent: type: string description: The fee that is charged for withdrawals in this currency, in percentage of the withdrawal amount. precision: type: integer description: The number of decimal places. examples: Basic example: value: data: - id: 1 type: crypto currency: BTC minimum_amount: '0.00010000' minimum_withdrawal_amount: '0.00020000' deposit_confirmations: 1 deposit_fee_percent: '0.000700' withdrawal_fee_percent: '0.010000' precision: 8 - id: 5 type: crypto currency: ETH minimum_amount: '0.00200000' minimum_withdrawal_amount: '0.00200000' deposit_confirmations: 10 deposit_fee_percent: '0.010000' withdrawal_fee_percent: '0.000000' precision: 8 - id: 87 type: crypto currency: USDC minimum_amount: '5.00000000' minimum_withdrawal_amount: '5.00000000' deposit_confirmations: 10 deposit_fee_percent: '0.010000' withdrawal_fee_percent: '0.000000' precision: 8 '400': $ref: '#/components/responses/MalformedJson' '403': $ref: '#/components/responses/HeaderAuthorization' operationId: post-currencies-list requestBody: required: true description: | The `Content-Type: application/json` header must be specified even though the request body has no fields. content: application/json: schema: type: object description: | This endpoint does not accept any request parameters, but you must still send an empty JSON object (`{}`) in the request body. additionalProperties: false examples: Basic example: value: {} /v2/currencies/pairs: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' tags: - Currencies summary: Get exchange rates deprecated: true description: | Use `POST /v2/currencies/rates` instead. responses: '200': description: | OK. Returns the available exchange pairs, including currency metadata and the conversion rate. content: application/json: schema: type: object properties: data: type: array description: List of matching currency pairs. items: type: object properties: currency_from: type: object properties: currency: type: string description: Source currency code. example: BTC type: type: string description: Source currency type. enum: - crypto - fiat example: crypto min_amount: type: string description: Minimum exchange amount for the source currency. example: "0.00010000" min_amount_deposit_with_exchange: type: string description: Minimum deposit amount when using exchange flow. example: "0.00020000" currency_to: type: object properties: currency: type: string description: Target currency code. example: ETH type: type: string description: Target currency type. enum: - crypto - fiat example: crypto rate_from: type: string description: Always `1`, representing one unit of `currency_from`. rate_to: type: string description: Amount of `currency_to` equivalent to one unit of `currency_from`. examples: USDC to EUR: value: data: - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14616853" rate_to: "1" Convert from USDC: value: data: - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: ETH type: crypto rate_from: "1746.86560006" rate_to: "1" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: LTC type: crypto rate_from: "44.72987358" rate_to: "1" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14601670" rate_to: "1" Convert to EUR: value: data: - currency_from: currency: BTC type: crypto min_amount: "0.00010000" min_amount_deposit_with_exchange: "0.00010000" currency_to: currency: EUR type: fiat rate_from: "1" rate_to: "56106.14483781" - currency_from: currency: ETH type: crypto min_amount: "0.00300000" min_amount_deposit_with_exchange: "0.00200000" currency_to: currency: EUR type: fiat rate_from: "1" rate_to: "1527.70805675" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14543711" rate_to: "1" '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Invalid currency_from: value: errors: currency_from: The selected currency from is invalid. Invalid currency_to: value: errors: currency_to: The selected currency to is invalid. Invalid currency_from and currency_to: value: errors: currency_from: The selected currency from is invalid. currency_to: The selected currency to is invalid. Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' operationId: post-currencies-pairs requestBody: content: application/json: schema: type: object properties: currency_from: type: string description: Currency to exchange from. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). currency_to: type: string description: Currency to exchange to. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). examples: USDC to EUR: value: currency_from: USDC currency_to: EUR Convert from USDC: value: currency_from: USDC Convert to EUR: value: currency_to: EUR /v2/currencies/rates: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' tags: - Currencies summary: Get currency exchange rates description: Get available currency pairs and exchange rates. responses: '200': description: | OK. Returns the available exchange pairs. content: application/json: schema: type: object properties: data: type: array description: List of matching currency pairs. items: type: object properties: currency_from: type: object properties: currency: type: string description: Source currency code. example: BTC type: type: string description: Source currency type. enum: - crypto - fiat example: crypto min_amount: type: string description: Minimum exchange amount for the source currency. example: "0.00010000" min_amount_deposit_with_exchange: type: string description: Minimum deposit amount when using exchange flow. Present when `currency_from.type` is `crypto`. example: "0.00020000" currency_to: type: object properties: currency: type: string description: Target currency code. example: ETH type: type: string description: Target currency type. enum: - crypto - fiat example: crypto rate_from: type: string description: Always `1`, representing one unit of `currency_from`. rate_to: type: string description: Amount of `currency_to` equivalent to one unit of `currency_from`. examples: USDC to EUR: value: data: - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14616853" rate_to: "1" Convert from USDC: value: data: - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: ETH type: crypto rate_from: "1746.86560006" rate_to: "1" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: LTC type: crypto rate_from: "44.72987358" rate_to: "1" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14601670" rate_to: "1" Convert to EUR: value: data: - currency_from: currency: BTC type: crypto min_amount: "0.00010000" min_amount_deposit_with_exchange: "0.00010000" currency_to: currency: EUR type: fiat rate_from: "1" rate_to: "56106.14483781" - currency_from: currency: ETH type: crypto min_amount: "0.00300000" min_amount_deposit_with_exchange: "0.00200000" currency_to: currency: EUR type: fiat rate_from: "1" rate_to: "1527.70805675" - currency_from: currency: USDC type: crypto min_amount: "5.00000000" min_amount_deposit_with_exchange: "5.00000000" currency_to: currency: EUR type: fiat rate_from: "1.14543711" rate_to: "1" '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Invalid currency_from: value: errors: currency_from: The selected currency from is invalid. Invalid currency_to: value: errors: currency_to: The selected currency to is invalid. Invalid currency_from and currency_to: value: errors: currency_from: The selected currency from is invalid. currency_to: The selected currency to is invalid. Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' '422': $ref: '#/components/responses/InternalError' operationId: post-currencies-rates requestBody: content: application/json: schema: type: object properties: currency_from: description: Currency to exchange from. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). type: string currency_to: description: Currency to exchange to. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). type: string examples: USDC to EUR: value: currency_from: USDC currency_to: EUR Convert from USDC: value: currency_from: USDC Convert to EUR: value: currency_to: EUR /v2/addresses/take: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Generate a crypto address description: Generate a deposit address for a user. tags: - Deposit addresses responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object properties: id: type: integer format: int32 description: Address ID. currency: type: string description: Currency code. convert_to: type: string description: The currency all deposits to this address will be converted to. It is only returned if you included `convert_to` in the request. address: type: string description: The generated address. tag: type: string description: Destination tag/memo for currencies that require it. `Null` for currencies that do not require tags. foreign_id: type: string description: ID of the customer who will be depositing to this address. end_user_reference: type: string description: Permanent ID of the customer in your system. examples: USDC address: value: data: id: 3859599 currency: USDC address: "0x35f6005cfA94a1c030B8c4dfcc29D4eB8a6865bF" tag: null foreign_id: user_12345 end_user_reference: user_12345 USDC address with EUR conversion: value: data: id: 3859601 currency: USDC convert_to: EUR address: "0x360669C460894e27fc875cf674268D81f9e6512c" tag: null foreign_id: user_12345 end_user_reference: user_12345 '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Missing currency: summary: currency field is required value: errors: currency: "The currency field is required." Missing foreign_id: summary: foreign_id field is required value: errors: foreign_id: "The foreign id field is required." Currency not enabled: summary: Currency not enabled for client value: errors: currency: "The selected currency is not enabled for your account." Currency not found: summary: Currency doesn't exist value: errors: currency: "Invalid currency" Currency not allowed without conversion: summary: This currency requires convert_to to be set value: errors: currency: "Currency is not allowed without conversion" Invalid convert_to: summary: convert_to currency doesn't exist value: errors: convert_to: "Invalid currency" convert_to not allowed without conversion: summary: convert_to currency not supported for conversion value: errors: convert_to: "Currency is not allowed without conversion" Invalid end_user_reference: summary: end_user_reference must not contain an email address value: errors: end_user_reference: "The end user reference must not contain an email address." Invalid sender_type: summary: sender_type must be "natural" or "legal" value: errors: sender_type: "The selected sender type is invalid." KYC data incomplete: summary: Incomplete KYC sender_data value: errors: sender_data.first_name: "The sender data.first name field is required." sender_data.last_name: "The sender data.last name field is required." Multiple validation errors: summary: Multiple fields failed validation value: errors: currency: "The currency field is required." foreign_id: "The foreign id field is required." Address cannot be issued: summary: This end_user_reference cannot receive a new address value: errors: sender_data: "Address cannot be issued for that end_user_reference" Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' '422': description: | Unprocessable entity. An infrastructure or blockchain-related error occurred while issuing the address. content: application/json: schema: type: object properties: errors: type: array items: type: string error_code: type: string examples: Blockchain error: summary: Infrastructure failure while issuing the address value: errors: - "Something went wrong, please try again shortly" error_code: blockchain_error operationId: post-addresses-take requestBody: content: application/json: schema: type: object properties: currency: type: string description: The currency to receive. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). convert_to: type: string description: Automatically convert all deposits to this currency. If omitted, no automatic conversion is applied. foreign_id: type: string description: The unique ID of the customer who will be depositing to this address. It will be returned with every callback to make it easy for you to identify the customer within your system. The same `foreign_id` can be reused across multiple addresses that belong to the same customer. This parameter must not include any personal data. end_user_reference: $ref: "#/components/schemas/end_user_reference.deposits" sender_type: $ref: "#/components/schemas/sender_type.deposits" sender_data: $ref: "#/components/schemas/sender_data" required: - currency - foreign_id - sender_data - sender_type - end_user_reference examples: USDC address: value: currency: USDC foreign_id: user_12345 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU USDC address with EUR conversion: value: currency: USDC convert_to: EUR foreign_id: user_12345 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU /v2/withdrawal/crypto: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Withdraw crypto description: Withdraw in crypto to any address. tags: - Withdrawal responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: "Transaction ID." foreign_id: type: string description: "Unique ID of the withdrawal request." end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" type: type: string description: "Transaction type (e.g., `withdrawal`, `withdrawal_exchange`)." status: type: string description: "Transaction status." amount: type: string description: "Withdrawal amount in `sender_currency`." sender_amount: type: string description: "Same as `amount`. Withdrawal amount in the `sender_currency`. Present for withdrawals without conversion." sender_currency: type: string description: "Source currency ISO code." receiver_currency: type: string description: "Destination currency ISO code. Same as `sender_currency` for withdrawals without conversion." receiver_amount: type: string description: "Amount sent in `receiver_currency`. Present if the amount to be sent to the wallet is specified (`amount` for withdrawals without conversion, `amount_to` for withdrawals with conversion)." examples: Withdraw USDC: value: data: id: 132541615 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal status: processing amount: "100.00000000" sender_amount: "100.00000000" sender_currency: USDC receiver_currency: USDC receiver_amount: "100.00000000" Withdraw USDC with conversion from EUR: value: data: id: 132541619 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal_exchange status: processing amount: "100.00000000" sender_amount: "100.00000000" sender_currency: EUR receiver_currency: USDC Withdraw USDC with conversion and target amount: value: data: id: 132541648 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal_exchange status: processing sender_currency: EUR receiver_currency: USDC receiver_amount: "100.00000000" '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Missing currency: summary: currency field is required value: errors: currency: "The currency field is required." Invalid currency: summary: Currency doesn't exist value: errors: currency: "Invalid currency" Invalid convert_to: summary: convert_to currency doesn't exist value: errors: convert_to: "Invalid currency" Amount not a number: summary: amount is not numeric value: errors: amount: "The amount must be a number." Amount too many decimals: summary: amount has too many decimal places value: errors: amount: "The amount must not have more than X decimal places." Amount_to not a number: summary: amount_to is not numeric value: errors: amount_to: "The amount to must be a number." Amount_to too many decimals: summary: amount_to has too many decimal places value: errors: amount_to: "The amount to must not have more than X decimal places." Missing amount: summary: amount is required when amount_to is not present value: errors: amount: "The amount field is required when amount to is not present." Amount not positive: summary: amount must be greater than 0 value: errors: amount: "The amount field must be greater than 0." Missing amount_to: summary: amount_to is required when amount is not present value: errors: amount_to: "The amount to field is required when amount is not present." Amount_to not positive: summary: amount_to must be greater than 0 value: errors: amount_to: "The amount to field must be greater than 0." Missing convert_to: summary: convert_to is required when amount_to is present value: errors: convert_to: "The convert to field is required when amount to is present." Missing foreign_id: summary: foreign_id field is required value: errors: foreign_id: "The foreign id field is required." Duplicate foreign_id: summary: foreign_id already used value: errors: foreign_id: "The foreign id has already been taken." Invalid end_user_reference: summary: end_user_reference must not contain an email address value: errors: end_user_reference: "The end user reference must not contain an email address." Invalid sender_type: summary: sender_type must be "natural" or "legal" value: errors: sender_type: "The selected sender type is invalid." Invalid receiver_type: summary: receiver_type must be "natural", "legal", or "self" value: errors: receiver_type: "The selected receiver type is invalid." Invalid address format: summary: Crypto address format invalid value: errors: address: "Invalid USDC address" Amount below minimum: summary: Amount too small value: errors: amount: "The amount must be 5.00000000 USDC." Amount exceeds balance: summary: Insufficient balance value: errors: amount: The requested amount exceeds the available balance. Invalid tag for currency: summary: Tag validation failed value: errors: tag: "Destination tag/memo for currencies that require it." Exchange rate unavailable: summary: Unable to get exchange rate (sender-amount variant) value: errors: amount: "Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later." Exchange rate unavailable (amount_to): summary: Unable to get exchange rate (target-amount variant) value: errors: amount_to: "Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/WithdrawalHeaderAuthorization' '422': $ref: '#/components/responses/InternalError' operationId: post-withdrawal-crypto requestBody: content: application/json: schema: type: object properties: currency: type: string description: Currency to withdraw. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). convert_to: type: string description: Target currency to convert funds into before sending. If omitted, funds are sent in the source `currency` without conversion. amount: type: number description: Amount to withdraw in the source `currency`. You can only specify either `amount_to` or `amount`. amount_to: type: number description: Amount to send in the `convert_to` currency. Use this field when you want to convert funds and send a specific amount in the target currency set in `convert_to`. You can only specify either `amount_to` or `amount`. address: type: string description: Cryptocurrency address where you want to send funds. tag: type: string description: Tag/memo for currencies and destination wallets that support or require it. On withdrawal forms, display this field to the user, but allow it to be empty because some wallets do not require a tag/memo. Warn the user that if the destination wallet requires a tag/memo and it is not provided, the funds may be lost. foreign_id: description: Unique ID of the withdrawal request. end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" sender_type: $ref: "#/components/schemas/sender_type.withdrawals" sender_data: $ref: "#/components/schemas/sender_data.withdrawals" receiver_type: $ref: "#/components/schemas/receiver_type" receiver_data: $ref: "#/components/schemas/receiver_data" required: - currency - amount - address - foreign_id - sender_data - sender_type - receiver_data - receiver_type - end_user_reference examples: Withdraw USDC: value: currency: USDC amount: "100" address: "0x35f6005cfA94a1c030B8c4dfcc29D4eB8a6865bF" foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU receiver_type: natural receiver_data: first_name: Friedrich last_name: Müller date_of_birth: "1995-08-17" Withdraw USDC with conversion from EUR: value: currency: EUR convert_to: USDC amount: "100" address: "0x35f6005cfA94a1c030B8c4dfcc29D4eB8a6865bF" foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU receiver_type: natural receiver_data: first_name: Friedrich last_name: Müller date_of_birth: "1995-08-17" Withdraw USDC with conversion and target amount: value: currency: EUR convert_to: USDC amount_to: "100" address: "0x35f6005cfA94a1c030B8c4dfcc29D4eB8a6865bF" foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU receiver_type: natural receiver_data: first_name: Friedrich last_name: Müller date_of_birth: "1995-08-17" /v2/crypto/withdrawal_instant: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Withdraw BTC description: Make an [instant withdrawal](/withdrawals#instant-withdrawals) from a cryptocurrency balance. tags: - Withdrawal responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: "Transaction ID." foreign_id: type: string description: "Unique ID of the withdrawal request." end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" type: type: string description: "Transaction type (always `withdrawal_instant`)." status: type: string description: "Transaction status." sender_currency: type: string description: "Source currency ISO code." sender_amount: type: string description: "Withdrawal amount." examples: Withdraw BTC: value: data: id: 134702815 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal_instant status: processing sender_currency: BTC sender_amount: "0.00020000" '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Instant_withdrawals_disabled: summary: Instant withdrawals are disabled value: errors: amount: Instant withdrawals are disabled for this merchant. Instant_withdrawals_not_supported_for_sender_currency: summary: Instant withdrawals are not supported for this currency value: errors: sender_currency: Instant withdrawals are not supported for the specified sender_currency. Duplicate foreign_id: summary: Foreign ID already used value: errors: foreign_id: "The foreign id has already been taken." Missing required field: summary: Sender currency field is required value: errors: currency: "The sender_currency field is required." Invalid address format: summary: Crypto address format invalid value: errors: address: "Invalid USDC address" Amount below minimum: summary: Amount too small value: errors: amount: "The amount must be 5.00000000 USDC." Amount exceeds balance: summary: Insufficient balance value: errors: amount: The requested amount exceeds the available balance. Multiple validation errors: summary: Multiple fields failed validation value: errors: sender_currency: "The sender_currency field is required." address: "The address field is required." sender_amount: "The sender_amount must be greater than 0." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/WithdrawalHeaderAuthorization' operationId: post-crypto-withdrawal-instant requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: Currency to withdraw. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). sender_amount: type: number description: Amount to withdraw in `sender_currency`. address: type: string description: Cryptocurrency address where you want to send funds. foreign_id: description: Unique ID of the withdrawal request. end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" sender_type: $ref: "#/components/schemas/sender_type.withdrawals" sender_data: $ref: "#/components/schemas/sender_data.withdrawals" receiver_type: $ref: "#/components/schemas/receiver_type" receiver_data: $ref: "#/components/schemas/receiver_data" required: - sender_currency - sender_amount - address - foreign_id - sender_data - sender_type - receiver_type - receiver_data - end_user_reference examples: Withdraw BTC: value: sender_currency: BTC sender_amount: "0.00020000" address: tb1qfdxh6gkfr0qgyatnlkd8khcnxph9tw06n6qwjc foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU receiver_type: natural receiver_data: first_name: Friedrich last_name: Müller date_of_birth: "1995-08-17" /v2/crypto/withdrawal_instant_exchange: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Withdraw BTC with conversion from EUR description: Make an [instant withdrawal](/withdrawals#instant-withdrawals) from a cryptocurrency or fiat balance with conversion to cryptocurrency. tags: - Withdrawal responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: "Transaction ID." foreign_id: type: string description: "Unique ID of the withdrawal request." end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" type: type: string description: "Transaction type (always `withdrawal_instant_exchange`)." status: type: string description: "Transaction status." sender_currency: type: string description: "Source currency ISO code." sender_amount: type: string description: "Withdrawal amount in `sender_currency`." received_currency: type: string description: "Destination currency ISO code." received_amount: type: string description: "Amount sent in `received_currency`." examples: Withdraw BTC with conversion from EUR: value: data: id: 134702815 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal_instant_exchange status: processing sender_currency: EUR sender_amount: "100.00000000" received_currency: BTC received_amount: "0.00153827" '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Instant_withdrawals_disabled: summary: Instant withdrawals are disabled value: errors: amount: Instant withdrawals are disabled for this merchant. Instant_withdrawals_not_supported_for_sender_currency: summary: Instant withdrawals are not supported for this currency value: errors: sender_currency: Instant withdrawals are not supported for the specified sender_currency. Duplicate foreign_id: summary: Foreign ID already used value: errors: foreign_id: "The foreign id has already been taken." Missing required field: summary: Sender currency field is required value: errors: currency: "The sender_currency field is required." Invalid address format: summary: Crypto address format invalid value: errors: address: "Invalid USDC address" Amount below minimum: summary: Amount too small value: errors: amount: "The amount must be 5.00000000 USDC." Amount exceeds balance: summary: Insufficient balance value: errors: amount: The requested amount exceeds the available balance. Exchange rate unavailable: summary: Unable to get exchange rate value: errors: amount: "Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later." Multiple validation errors: summary: Multiple fields failed validation value: errors: sender_currency: "The sender_currency field is required." address: "The address field is required." sender_amount: "The sender_amount must be greater than 0." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/WithdrawalHeaderAuthorization' operationId: post-crypto-withdrawal-instant-exchange requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: Currency to withdraw. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). received_currency: type: string description: Target currency to convert funds into before sending. sender_amount: type: number description: Amount to withdraw in `sender_currency`. address: type: string description: Cryptocurrency address where you want to send funds. foreign_id: description: Unique ID of the withdrawal request. end_user_reference: $ref: "#/components/schemas/end_user_reference.withdrawals" sender_type: $ref: "#/components/schemas/sender_type.withdrawals" sender_data: $ref: "#/components/schemas/sender_data.withdrawals" receiver_type: $ref: "#/components/schemas/receiver_type" receiver_data: $ref: "#/components/schemas/receiver_data" required: - sender_currency - received_currency - sender_amount - address - foreign_id - sender_data - sender_type - receiver_type - receiver_data - end_user_reference examples: Withdraw BTC with conversion from EUR: value: sender_currency: EUR received_currency: BTC sender_amount: "100" address: tb1qfdxh6gkfr0qgyatnlkd8khcnxph9tw06n6qwjc foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU receiver_type: natural receiver_data: first_name: Friedrich last_name: Müller date_of_birth: "1995-08-17" /v2/exchange/calculate: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Get an exchange quote description: Get a fixed exchange quote for a specific amount, which can then be used with [/v2/exchange/fixed](/api-reference/endpoints/exchange-fixed). tags: - Exchange responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: sender_currency: type: string description: The currency being exchanged from. sender_amount: type: string description: If `sender_amount` was provided in the request, this is the requested send amount. If `receiver_amount` was provided, this is the calculated amount to send. receiver_currency: type: string description: The currency being exchanged to. receiver_amount: type: string description: If `receiver_amount` was provided in the request, this is the requested receive amount. If `sender_amount` was provided, this is the calculated amount to receive. fee_currency: type: string description: The currency in which the exchange fee is charged. fee_amount: type: string description: The exchange fee amount. If the fee is charged in the sender currency, the total debited amount is `sender_amount + fee_amount`. price: type: string description: The quoted exchange rate, expressed as units of `receiver_currency` for 1 unit of `sender_currency`. ts_fixed: type: integer description: Unix timestamp, in seconds, when the quote rate was fixed. format: int64 ts_release: type: integer format: int64 description: Unix timestamp, in seconds, when the quote expires. fix_period: type: integer format: int32 description: How long the fixed quote remains valid, in seconds. After this period, request a new quote. examples: sender_amount: value: data: sender_currency: USDC sender_amount: "100.00000000" receiver_currency: EUR receiver_amount: "87.33886770" fee_currency: EUR fee_amount: "0.87338868" price: "0.87338867" ts_fixed: 1782219422 ts_release: 1782219482 fix_period: 60 receiver_amount: value: data: sender_currency: USDC sender_amount: "114.49347482" receiver_currency: EUR receiver_amount: "100.00000000" fee_currency: EUR fee_amount: "1.00000000" price: "0.87341221" ts_fixed: 1782219490 ts_release: 1782219550 fix_period: 60 '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Missing sender currency: summary: Sender currency field is required value: errors: sender_currency: "The sender currency field is required." Missing fields: summary: Required fields missing value: errors: receiver_currency: "The receiver currency field is required." receiver_amount: "The receiver amount field is required when the sender amount field is not presented." Same currency pair: summary: Cannot exchange same currency value: errors: receiver_currency: "The receiver currency and sender currency must be different." Invalid sender currency: summary: Sender currency not supported value: errors: sender_currency: "The selected sender currency is invalid." Invalid receiver currency: summary: Receiver currency not supported value: errors: receiver_currency: "The selected receiver currency is invalid." Invalid amount: summary: Amount below minimum or invalid format value: errors: sender_amount: "Invalid amount format" Sender amount not positive: summary: Sender amount must be greater than 0 value: errors: sender_amount: "The sender amount must be greater than 0." Receiver amount not positive: summary: Receiver amount must be greater than 0 value: errors: receiver_amount: "The receiver amount must be greater than 0." Amount below minimum: summary: Sender amount below the minimum tradeable amount for this currency value: errors: sender_amount: "The sender_amount must be at least 2.00000000 ABC" Amount exceeds maximum: summary: Sender amount above the maximum tradeable amount for this currency value: errors: sender_amount: "The sender_amount may not be greater than 7.00000000 ABC" Currency pair not available: summary: Exchange is unavailable for the requested currency pair value: errors: sender_amount: "Exchange is unavailable for given currencies" Exchange rate unavailable: summary: Unable to get an exchange rate right now. Keyed under receiver_amount instead if only that field was provided. value: errors: sender_amount: "Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' '422': $ref: '#/components/responses/InternalError' operationId: post-exchange-calculate requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: Currency to exchange from. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). receiver_currency: type: string description: Currency to exchange to. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). sender_amount: description: Amount to send. You must include either this parameter or `receiver_amount`. type: number receiver_amount: description: Amount to receive. You must include either this parameter or `sender_amount`. type: number required: - sender_currency - receiver_currency examples: sender_amount: value: sender_currency: USDC receiver_currency: EUR sender_amount: 100 receiver_amount: value: sender_currency: USDC receiver_currency: EUR receiver_amount: 100 description: '' /v2/exchange/fixed: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Exchange at a fixed exchange rate description: Execute an exchange using a valid fixed quote from [/v2/exchange/calculate](/api-reference/endpoints/exchange-calculate). tags: - Exchange responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object required: - id - foreign_id - type - sender_amount - sender_currency - receiver_amount - receiver_currency - fee_amount - fee_currency - price - status properties: id: type: integer description: Transaction ID. foreign_id: type: string description: This exchange's unique identifier in your system. type: type: string description: Transaction type. sender_amount: type: string description: The amount being exchanged. sender_currency: type: string description: The currency being exchanged from. receiver_amount: type: string description: The amount to be received. receiver_currency: type: string description: The currency being exchanged to. fee_amount: type: string description: The exchange fee amount. If the fee is charged in the sender currency, the total debited amount is `sender_amount + fee_amount`. fee_currency: type: string description: The currency in which the exchange fee is charged. price: type: string description: The quoted exchange rate from `/v2/exchange/calculate`, expressed as units of `receiver_currency` for 1 unit of `sender_currency`. status: type: string description: Exchange status. examples: sender_amount: value: data: sender_currency: USDC sender_amount: "100.00000000" receiver_currency: EUR receiver_amount: "87.33886770" fee_currency: EUR fee_amount: "0.87338868" price: "0.87338867" id: 132541744 foreign_id: exchange_123 type: exchange status: processing receiver_amount: value: data: sender_currency: USDC sender_amount: "114._49347482" receiver_currency: EUR receiver_amount: "100.00000000" fee_currency: EUR fee_amount: "1.00000000" price: "0.87341221" id: 132541748 foreign_id: exchange_123 type: exchange status: processing '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Rate expired: summary: Fixed rate has expired value: errors: message: "Fix time is up. Exchange price is changed." Insufficient balance: summary: Not enough balance for exchange value: errors: sender_amount: "Insufficient balance. Available: 50.00000000 USDC" Invalid sender currency: summary: Sender currency not supported value: errors: sender_currency: "Currency not supported" Invalid receiver currency: summary: Receiver currency not supported value: errors: receiver_currency: "Currency not supported" Invalid amount: summary: Amount below minimum or invalid value: errors: sender_amount: "The amount must be at least 50.00000000 USDC" Missing foreign_id: summary: Foreign ID missing value: errors: foreign_id: "The foreign_id field is required" Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: "#/components/responses/HeaderAuthorization" operationId: post-exchange-fixed requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: Currency to exchange from. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). receiver_currency: type: string description: Currency to exchange to. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). sender_amount: type: number description: Amount to send. You must include either this parameter or `receiver_amount`. This value must match the quote returned by `/v2/exchange/calculate`. receiver_amount: type: number description: Amount to receive. You must include either this parameter or `sender_amount`. This value must match the quote returned by `/v2/exchange/calculate`. foreign_id: type: string description: Unique ID of the exchange transaction. price: type: number description: The quoted exchange rate from `/v2/exchange/calculate`, expressed as units of `receiver_currency` for 1 unit of `sender_currency`. This value must match the quote. required: - sender_currency - receiver_currency - foreign_id - price examples: sender_amount: value: sender_currency: USDC receiver_currency: EUR sender_amount: 100 foreign_id: exchange_123 price: "0.87338867" receiver_amount: value: sender_currency: USDC receiver_currency: EUR receiver_amount: 100 foreign_id: exchange_123 price: "0.87341221" /v2/exchange/now: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Exchange at market rate description: Execute an exchange immediately at the currently available market rate, without requesting a fixed quote. tags: - Exchange responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object required: - sender_currency - sender_amount - receiver_currency - receiver_amount - fee_currency - fee_amount - price - id - foreign_id - type - status properties: sender_currency: type: string description: The currency being exchanged from. sender_amount: type: string description: If `sender_amount` was provided in the request, this is the requested send amount. If `receiver_amount` was provided, this is the calculated amount to send. receiver_currency: type: string description: The currency being exchanged to. receiver_amount: type: string description: If `receiver_amount` was provided in the request, this is the requested receive amount. If `sender_amount` was provided, this is the calculated amount to receive. fee_currency: type: string description: The currency in which the exchange fee is charged. fee_amount: type: string description: The exchange fee amount. If the fee is charged in the sender currency, the total debited amount is `sender_amount + fee_amount`. price: type: string description: The exchange rate, expressed as units of `receiver_currency` for 1 unit of `sender_currency`. id: type: integer description: Transaction ID. foreign_id: type: string description: This exchange's unique identifier in your system. type: type: string description: Transaction type. status: type: string description: Exchange status. examples: sender_amount: value: data: sender_currency: USDC sender_amount: "100.00000000" receiver_currency: EUR receiver_amount: "87.33886770" fee_currency: EUR fee_amount: "0.87338868" price: "0.87338867" id: 132541744 foreign_id: exchange_123 type: exchange status: processing receiver_amount: value: data: sender_currency: USDC sender_amount: "114.49347482" receiver_currency: EUR receiver_amount: "100.00000000" fee_currency: EUR fee_amount: "1.00000000" price: "0.87341221" id: 132541748 foreign_id: exchange_123 type: exchange status: processing '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Rate not available: summary: Exchange rate currently unavailable value: errors: message: "Exchange rate not available at this time" Insufficient balance: summary: Not enough balance for exchange value: errors: sender_amount: The requested amount exceeds the available balance. Invalid sender currency: summary: Sender currency not supported value: errors: sender_currency: "Currency not supported" Invalid receiver currency: summary: Receiver currency not supported value: errors: receiver_currency: "Currency not supported" Invalid amount: summary: Amount below minimum or invalid value: errors: sender_amount: "The amount must be 5.00000000 USDC" Missing foreign_id: summary: Foreign ID missing value: errors: foreign_id: "The foreign_id field is required" Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: "#/components/responses/HeaderAuthorization" operationId: post-exchange-now requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: Currency to exchange from. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). receiver_currency: description: Currency to exchange to. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). type: string sender_amount: type: number description: Amount to send. You must include either this parameter or `receiver_amount`. receiver_amount: type: number description: Amount to receive. You must include either this parameter or `sender_amount`. foreign_id: type: string description: Unique exchange identifier in your system. required: - sender_currency - receiver_currency - foreign_id examples: sender_amount: value: sender_currency: USDC receiver_currency: EUR sender_amount: 100 foreign_id: exchange_123 receiver_amount: value: sender_currency: USDC receiver_currency: EUR receiver_amount: 100 foreign_id: exchange_123 /v2/invoices/create: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Create an invoice tags: - Invoices responses: '201': description: Created content: application/json: schema: type: object properties: data: type: object required: - id - url - foreign_id - end_user_reference - address - title - status - currency - amount - sender_currency - sender_amount - fixed_at - release_at - seconds_left properties: id: type: integer format: int32 description: Invoice ID. example: 123732 url: type: string format: uri description: Invoice URL. foreign_id: type: string description: This invoice's unique ID in your system. end_user_reference: type: string description: The unique ID of the customer this invoice is for. You can use it to group invoices by customer. address: type: string description: The address that will receive the invoice payment. May be null if address is not yet assigned. example: 2N2xtaZCNygY3iq6XKPJsdoPMDX85LUc8SM tag: type: string nullable: true description: "Destination tag/memo. Present only for currencies that support tags (e.g., XRP)." title: type: string minLength: 1 description: Invoice title. status: type: string description: For newly created invoices, this will always be either `created` or `pending`. enum: - created - pending currency: type: string description: Invoice currency. amount: type: string description: Invoice amount. example: '0.01230000' sender_currency: type: string default: null description: The currency the customer will pay in. Defaults to null for invoices without a pre-selected currency. sender_amount: type: string example: '0.01230000' default: null description: The amount the customer needs to pay in their sender_currency. Defaults to null for invoices without a pre-selected currency. fixed_at: type: integer format: int64 default: null description: The Unix timestamp for when the invoice was created, in seconds. Defaults to null if no fixed payment quote was created. release_at: type: integer default: null description: The Unix timestamp for when the invoice will expire, in seconds. Defaults to null for invoices without a timer. format: int64 seconds_left: type: integer format: int32 default: null description: The number of seconds left until the invoice expires. Defaults to null for invoices without a timer. example: 899 examples: Invoice without a timer: value: data: id: 826900 url: https://invoices.sandbox.cryptoprocessing.com/invoice/Jyf1cQ foreign_id: invoice_123 end_user_reference: user_12345 address: null title: Invoice Title status: created currency: EUR amount: '100.00000000' sender_currency: null sender_amount: null fixed_at: null release_at: null seconds_left: null Invoice with a timer: value: data: id: 826904 url: https://invoices.sandbox.cryptoprocessing.com/invoice/o6t4I8 foreign_id: invoice_123 end_user_reference: user_12345 address: null title: Invoice Title status: pending currency: EUR amount: '100.00000000' sender_currency: null sender_amount: null fixed_at: null release_at: 1775177485 seconds_left: 59 Invoice with a timer and a pre-selected currency: value: data: id: 826906 url: https://invoices.sandbox.cryptoprocessing.com/invoice/ZKeDtw foreign_id: invoice_123 end_user_reference: user_12345 address: tb1q0raamq6ppjpcfy5mzselzqfgcqaff59kt03lzl title: Invoice Title status: pending currency: EUR amount: '100.00000000' sender_currency: BTC sender_amount: '0.00129400' fixed_at: 1775177497 release_at: 1775177557 seconds_left: 59 '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Duplicate foreign_id: summary: Foreign ID already used value: errors: foreign_id: "The foreign id has already been taken." Invalid currency: summary: Currency not supported value: errors: currency: "The selected currency is invalid." Invalid amount: summary: Amount validation failed value: errors: amount: "The amount must be a number." Amount below minimum: summary: Amount below minimum limit value: errors: amount: "The amount must be 5.00000000 USDC." Invalid email: summary: Invalid email format value: errors: email_user: "The email user must be a valid email address." Missing required fields: summary: Required fields missing value: errors: title: "The title field is required." foreign_id: "The foreign id field is required." currency: "The currency field is required." amount: "The amount field is required." Invalid type: summary: Invalid invoice type value: errors: type: "The selected type is invalid." Feature not enabled: summary: Invoice feature is disabled value: message: "Required features [invoices_enabled] not enabled." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: "#/components/responses/HeaderAuthorization" operationId: post-invoices-create requestBody: content: application/json: schema: type: object properties: type: type: string description: "For partial pay invoices, set this parameter to good_until_expired. For standard invoices, use fill_or_kill or leave this parameter empty." enum: - fill_or_kill - good_until_expired end_user_reference: $ref: "#/components/schemas/end_user_reference.deposits" timer: type: boolean description: If this parameter is set to true, the invoice will expire in 15 minutes after it is created. title: type: string maxLength: 50 description: Invoice title that the customer will see. minLength: 1 description: type: string description: Invoice description that the customer will see. maxLength: 1000 foreign_id: type: string description: This invoice's unique ID in your system. currency: type: string description: Currency you want to receive deposits in. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). sender_currency: type: string description: "Currency the customer will pay in. If provided together with `timer: true`, the invoice is created with a fixed payment currency." amount: type: number description: "Invoice amount that you want to receive from the customer." url_success: type: string format: uri description: "The URL the customer will be redirected to in case of a successful invoice payment." url_failed: type: string description: "The URL the customer will be redirected to in case of an unsuccessful invoice payment." format: uri email_user: type: string description: If the amount the customer pays does not match the amount you set for the invoice, CryptoProcessing will send an email to this address instructing the customer on how they can receive a refund. If they paid less, they will receive a full refund. If they paid more, the customer will get instructions on how to be refunded the difference. format: email sender_type: $ref: "#/components/schemas/sender_type.deposits" sender_data: $ref: "#/components/schemas/sender_data" required: - timer - title - foreign_id - end_user_reference - currency - sender_type - sender_data - amount - url_success - url_failed - email_user examples: Invoice without a timer: value: timer: false title: Invoice Title currency: EUR amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: customer@example.com sender_type: natural sender_data: first_name: Friedrich last_name: Müller date_of_birth: '1995-08-17' Invoice with a timer: value: timer: true title: Invoice Title currency: EUR amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: customer@example.com sender_type: natural sender_data: first_name: Friedrich last_name: Müller date_of_birth: '1995-08-17' Invoice with a timer and a pre-selected currency: value: timer: true title: Invoice Title currency: EUR sender_currency: BTC amount: 100 foreign_id: invoice_123 end_user_reference: user_12345 url_success: https://example.com/success url_failed: https://example.com/failed email_user: customer@example.com sender_type: natural sender_data: first_name: Friedrich last_name: Müller date_of_birth: '1995-08-17' /v2/invoices/{foreign_id}/cancel: post: summary: Cancel an invoice operationId: cancel-an-invoice tags: - Invoices parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' - name: foreign_id in: path required: true description: The unique identifier of the invoice you need to cancel. schema: type: string example: invoice_123 responses: '200': description: OK content: application/json: examples: Basic example: value: [] '400': description: "Bad Request" content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Invoice not found: summary: Invoice with given foreign_id not found value: errors: foreign_id: "Invoice not found." Invalid state: summary: Invoice cannot be cancelled in current state value: error: "Invoice cannot be failed in its current state." code: "invalid_invoice_state" Feature not enabled: summary: Invoice feature is disabled value: message: "Required features [invoices_enabled] not enabled." Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' requestBody: required: true description: | The `Content-Type: application/json` header must be specified even though the request body has no fields. content: application/json: schema: type: object description: | This endpoint does not accept any request parameters, but you must still send an empty JSON object (`{}`) in the request body. additionalProperties: false examples: Basic example: value: {} /v2/transactions/info: get: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Fetch transaction metadata description: Get transaction details by `id`, `foreign_id`, or `txid`. Include only one of these parameters in your request. tags: - Transactions responses: '200': description: OK content: application/json: schema: type: object properties: id: type: integer format: int32 minimum: 1 example: 717535 foreign_id: type: string description: This transaction's unique identifier in your system. end_user_reference: type: string description: "End user reference. Present only when KYC data was provided." type: type: string description: Transaction type. crypto_address: type: object description: "Address details. Present only when entry has an associated address." required: - id - currency - address - tag properties: id: type: integer minimum: 1 format: int32 example: 176 currency: type: string description: "Currency ISO code." example: BTC convert_to: type: string description: "Conversion target currency. Present only when address has conversion logic." example: EUR address: type: string example: tb1qqepjlefdvrtyu6teqndww7v86hkz269z0ewj5q minLength: 1 tag: type: string nullable: true foreign_id: type: string currency_sent: type: object description: "Sent currency details. Present for confirmed, verifying, or processing transactions." required: - currency - amount properties: currency: type: string description: "Currency ISO code." amount: type: string description: "Amount sent." currency_received: type: object description: "Received currency details. Present for confirmed, verifying, or processing transactions." required: - currency - amount properties: currency: type: string description: "Currency ISO code." amount: type: string description: "Amount received." amount_minus_fee: type: string description: "Amount received minus fees. Present only for deposit transactions." transactions: type: array description: | Transaction entries. Each entry has a `transaction_type` that determines which fields are present: - `blockchain`: On-chain transactions (has address, tag, txid, riskscore, confirmations) - `internal`: Internal transfers (has address, tag, txid, confirmations) - `exchange`: Currency exchanges (has currency_to, amount_to) items: type: object required: - id - currency - transaction_type - type - amount properties: id: type: integer currency: type: string description: "Currency ISO code." currency_to: type: string description: "Destination currency. Present only for `exchange` entries." transaction_type: type: string enum: - blockchain - internal - exchange type: type: string description: "Entry type (e.g., deposit, withdrawal)." address: type: string description: "Cryptocurrency address. Present for `blockchain` and `internal` entries." tag: type: string nullable: true description: "Destination tag. Present for `blockchain` and `internal` entries." amount: type: string description: "Transaction amount." amount_to: type: string description: "Amount in destination currency. Present only for `exchange` entries." txid: type: string nullable: true riskscore: type: string nullable: true description: "Risk score (0-100). Present only for `blockchain` entries when risk scoring is enabled." confirmations: type: string description: "Number of blockchain confirmations. Present for `blockchain` and `internal` entries." fees: type: array uniqueItems: true items: type: object properties: type: type: string description: "Fee type identifier (e.g., `mining`, `fee_crypto_withdrawal`, etc.)." currency: type: string description: "Fee currency ISO code." amount: type: string description: "Fee amount. Returns '0' when system pays network fees." required: - type - currency - amount error: type: string nullable: true description: "Error message. Null or empty string for successful transactions." status: type: string description: | Transaction status. Note: internal statuses are mapped before returning: - `processing` and `verifying` are returned as `not_confirmed` - `error` is returned as `cancelled` - `rejected` is returned as `cancelled` enum: - cancelled - confirmed - declined - not_confirmed - pending additional_details: type: object nullable: true description: "Additional transaction details. Present only when available." required: - id - type - transactions - fees - status examples: Deposit: value: id: 1 end_user_reference: user_12345 type: deposit crypto_address: id: 1 currency: BTC address: 39mFf3X46YzUtfdwVQpYXPCMydc74ccbAZ foreign_id: user_12345 tag: null currency_sent: currency: BTC amount: "6.53157512" currency_received: currency: BTC amount: "6.53157512" amount_minus_fee: "6.5119800" transactions: - id: 1 currency: BTC transaction_type: blockchain type: deposit address: 39mFf3X46YzUtfdwVQpYXPCMydc74ccbAZ tag: null amount: "6.53157512" txid: 3950ad8149421a850d01dff88f024810e363ac18c9e8dd9bc0b9116e7937ad93 riskscore: "0.5" confirmations: "3" fees: - type: deposit currency: BTC amount: "0.01959472" error: "" status: confirmed Withdrawal: value: id: 1 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal crypto_address: id: 1 currency: BTC address: 115Mn1jCjBh1CNqug7yAB21Hq2rw8PfmTA tag: null currency_sent: currency: BTC amount: "0.02000000" currency_received: currency: BTC amount: "0.02000000" transactions: - id: 1 currency: BTC transaction_type: blockchain type: withdrawal address: 115Mn1jCjBh1CNqug7yAB21Hq2rw8PfmTA tag: null amount: "0.02" txid: bb040d895ef7141ea0b06b04227d8f5dd4ee12d5b890e6e5633f6439393a666b confirmations: "3" fees: - type: mining currency: BTC amount: "0.00007402" - type: withdrawal currency: BTC amount: "0.00002000" error: "" status: confirmed Exchange: value: id: 132541656 type: exchange currency_sent: currency: USDC amount: "100.00000000" currency_received: currency: EUR amount: "87.21435784" transactions: - id: 3788929 currency: USDC currency_to: EUR transaction_type: exchange type: exchange amount: "100.00000000" amount_to: "87.21435784" fees: - type: fee_crypto_sell_for_fiat currency: "EUR" amount: "0.87214358" error: "" status: confirmed '400': description: "Bad Request" content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Missing all params: value: errors: id: The id field is required when none of foreign id / txid are present. foreign_id: The foreign id field is required when none of id / txid are present. txid: The txid field is required when none of id / foreign id are present. Invalid id: value: errors: id: The id must be an integer. txid: The txid field is required when none of id / foreign id are present. Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/HeaderAuthorization' '404': description: Transaction not found content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: string examples: Not found: value: errors: - "No transaction found." requestBody: required: true content: application/json: schema: oneOf: - title: By internal ID type: object additionalProperties: false properties: id: type: integer description: Internal transaction ID. example: 717535 required: - id - title: By foreign ID type: object additionalProperties: false properties: foreign_id: type: string description: The transaction's unique identifier in your system. You can only find withdrawal transactions by their foreign_id. For deposits, search by id. example: withdrawal_123 required: - foreign_id - title: By txid type: object additionalProperties: false description: Transaction hash. properties: txid: type: string example: 3950ad8149421a850d01dff88f024810e363ac18c9e8dd9bc0b9116e7937ad93 required: - txid examples: foreign_id: value: foreign_id: withdrawal_123 txid: value: txid: 3950ad8149421a850d01dff88f024810e363ac18c9e8dd9bc0b9116e7937ad93 id: value: id: 134702831 /payments/v1/requests: post: parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' summary: Create a payment request description: Create a payment request for the client for a specified amount and a configurable expiration time. tags: - Payment requests requestBody: content: application/json: schema: type: object properties: amount: type: string description: Payment request amount that you want to receive from the customer. example: "100.50" currency: type: object description: The currency you want to receive. required: - iso properties: iso: type: string description: Currency ISO code. For the list of all available currencies, see [Currency codes](/api-reference/currency-codes#currency-codes-for-payment-requests). example: EUR network_name: type: string nullable: true description: Currency network name. Required for cryptocurrencies. Do not include for fiat currencies. For the list of all available networks, see [Currency codes](/api-reference/currency-codes#currency-codes-for-payment-requests). user_fee_percent: type: integer enum: [0, 100] default: 0 description: | Percentage of processing fees [paid by the customer](/payment-requests/fees#passing-the-processing-fee-to-your-customer). Currently, only two values are supported: - `0` (the default) — the processing fee is paid by the merchant. - `100` — the processing fee is paid by the customer. life_time_duration: type: integer nullable: true description: Payment request lifetime (duration in seconds). Include **either** this parameter or life_time_date_time. **At least one** of these fields is required. example: 3600 life_time_date_time: type: integer nullable: true description: Payment request lifetime (exact expiry timestamp). Include **either** this parameter or life_time_duration. **At least one** of these fields is required. example: 1773768946 payment_currency: type: object required: - iso description: | The cryptocurrency your customer will pay in. Unlike `currency`, this must be a cryptocurrency — fiat currencies are not supported. You can set both the currency and network or just the currency. If [rate_mode](#body-rate-mode) is `fixed`, you must set both the currency and network. properties: iso: type: string description: Cryptocurrency ISO code. For the list of all available currencies, see [Currency codes](/api-reference/currency-codes#currency-codes-for-payment-requests). network_name: type: string nullable: true description: Currency network name. Optional — omit to accept this cryptocurrency on any of its supported networks. For the list of all available networks, see [Currency codes](/api-reference/currency-codes#currency-codes-for-payment-requests). rate_mode: type: string enum: [standard, fixed] default: standard description: | This parameter controls the [rate lock](/payment-requests#currency-selection) behavior. - `standard` - the customer will be able to choose the payment currency. The exchange rate will be locked after the customer confirms the selection on the first screen. - `fixed` - the exchange rate is locked immediately after the payment request is created. The first screen is skipped, and the customer is taken directly to the screen with the payment instructions. In this mode, you must specify both the currency and network in [payment_currency](#body-payment-currency), as well as provide [sender_type](#body-sender-type), [sender_data](#body-sender-data) and [end_user_email](#body-end-user-email) for the customer identification. end_user_email: type: string description: If the amount the customer pays does not match the amount that you set for the payment request, CryptoProcessing will send an email to this address instructing the customer on how they can receive a refund. If they paid less, they will receive a full refund. If they paid more, the customer will get instructions on how to be refunded the difference. example: "customer@example.com" end_user_reference: type: string description: The unique ID of the customer this payment request is for. You can use it to group payment requests by customer. sender_type: $ref: '#/components/schemas/sender_type.deposits' sender_data: $ref: '#/components/schemas/sender_data' description: type: string description: Payment request description that the customer will see. example: "Order #123" foreign_id: type: string description: Unique foreign ID in your system. Must not contain personal data, such as the user's name or email address. example: order_123 url_store: type: string description: URL of the store page. The customer can click a button on the payment form to return to this URL (for example, if they change their mind or want to pick a different payment method). We recommend setting this to the URL of the checkout page. example: https://example.com/store url_success: type: string description: URL of the success page. The customer will be able to return to this address once the payment is completed. example: https://example.com/success url_failed: type: string description: URL of the failed payment page. The customer will be able to return to this address if the payment fails. example: https://example.com/fail required: - amount - currency - life_time_duration - life_time_date_time examples: Receive EUR: value: amount: '100' currency: iso: EUR life_time_duration: 360000 end_user_email: customer@example.com description: Order 0511 foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU Receive USDC: value: amount: '0.0015' currency: iso: USDC network_name: ethereum life_time_duration: 360000 end_user_email: customer@example.com description: Order 0511 foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU Receive EUR, forced USDC payment (fixed_mode): value: amount: '100' currency: iso: EUR rate_mode: fixed life_time_duration: 360000 payment_currency: iso: USDC network_name: ethereum end_user_email: customer@example.com description: Order 0511 foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example GmbH country_of_registration: DEU responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object required: - id - amount - currency - user_fee_percent - status - rate_mode - life_time - payment_link properties: id: type: string description: Payment request ID. example: "0196f6a1-cab2-76fb-84c7-7e9ee9ddf6b4" amount: type: string description: Payment request amount. example: "100.50" currency: properties: iso: type: string description: Payment request currency. example: EUR network_name: type: string nullable: true description: Network of the selected cryptocurrency. Not included for fiat currencies. required: - iso user_fee_percent: type: integer enum: [ 0, 100 ] description: Percentage of processing fees [paid by the customer](/payment-requests/fees#passing-the-processing-fee-to-your-customer). status: type: string description: | The status of the newly created payment request. Depends on [rate_mode](#body-rate-mode). - If the rate mode is `standard`, the status will be `created`. - If the rate mode is `fixed`, the status will be `processing`. example: created rate_mode: type: string enum: [standard, fixed] default: standard description: | The [rate lock](/payment-requests#currency-selection) behavior. - `standard` - the customer will be able to choose the payment currency. The exchange rate will be locked after the customer confirms the selection on the first screen. - `fixed` - the exchange rate is locked immediately after the payment request is created. The first screen is skipped, and the customer is taken directly to the screen with the payment instructions. valid_until: type: number description: | Unix timestamp until which the exchange rate remains locked. Included only if [rate_mode](#body-rate-mode) is `fixed`. example: 1731427200 life_time: type: number description: | Unix timestamp for when the payment request will expire, in seconds. If [rate_mode](#body-rate-mode) is `fixed`, this will have the same value as [valid_until](#body-valid-until). example: 1731427200 payment_currency: type: object required: - iso description: The cryptocurrency your customer will pay in. This is always a cryptocurrency, regardless of what `currency` is set to. properties: iso: type: string description: Cryptocurrency ISO code. For the list of all available currencies, see [API currency codes](/api-reference/currency-codes#currency-codes-for-payment-requests). network_name: type: string description: Currency network name. end_user_email: type: string description: Customer email provided in the request. example: customer@example.com description: type: string description: Payment request description. example: "Order #123 payment" payment_link: type: string description: Payment request URL. foreign_id: type: string description: Unique payment request ID in your system. example: "uuid string" url_store: type: string description: URL of the store page. url_success: type: string description: URL of the success page. url_failed: type: string description: URL of the failed payment page. end_user_reference: type: string description: The unique ID of the customer this payment request is for. You can use it to group payment requests by customer. payment_details: type: object description: Additional information about the expected payment. Included only if [rate_mode](#body-rate-mode) is `fixed`. additionalProperties: false required: - address - expected_amount - expected_currency properties: address: type: object additionalProperties: false required: - value properties: value: type: string description: The crypto address to which the customer will need to send the funds. tag: type: string description: Destination tag/memo for currencies that require it. expected_amount: type: string description: The amount of cryptocurrency that the customer is expected to send. expected_currency: type: object description: The cryptocurrency that the customer is expected to send. additionalProperties: false required: - iso - network_name properties: iso: type: string description: The currency the customer will send. example: USDC network_name: type: string nullable: true description: Network of the selected cryptocurrency. exchange_rate: type: object additionalProperties: false description: | The information about the exchange that will be performed after receiving funds from the customer. This object is included only if [payment_currency](/api-reference/endpoints/payments#body-payment-currency) differs from [currency](/api-reference/endpoints/payments#body-currency). properties: from: additionalProperties: false required: - iso - network_name properties: iso: type: string description: The currency the customer will send. example: USDC network_name: type: string description: Network of the selected cryptocurrency. example: ethereum to: additionalProperties: false required: - iso properties: iso: type: string description: The currency you will receive on your balance. example: EUR network_name: type: string description: Network of the selected cryptocurrency. Not included for fiat currencies. fees: type: array uniqueItems: true description: | The operation fee for the payment. Included only if [user_fee_percent](#body-user-fee-percent) is 100 (the customer pays the fee). items: type: object properties: currency: additionalProperties: false required: - iso properties: iso: type: string description: Fee currency ISO code. example: USDC network_name: type: string description: Network of the fee currency. example: ethereum amount: type: string description: Fee amount. required: - currency - amount examples: Receive EUR: value: data: id: 019d511c-9fd2-7e71-b534-74e8abd855f1 amount: '100' currency: iso: EUR user_fee_percent: 0 status: created rate_mode: standard life_time: 1775542323 end_user_email: customer@example.com description: Order 0511 payment_link: https://payments.cryptoprocessing.com/payment/lLXLZ6Q8lCwFFRbyW0C1ET foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 Receive USDC: value: data: id: 019d511c-1546-7c34-a916-a2610a198448 amount: '0.0015' currency: iso: USDC network_name: ethereum user_fee_percent: 0 status: created rate_mode: standard life_time: 1775542288 end_user_email: customer@example.com description: Order 0511 payment_link: https://payments.cryptoprocessing.com/payment/8N8_cWBnfAbT12mR5JmPVf foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 Receive EUR, forced USDC payment (fixed_mode): value: data: id: 0196f6a1-cab2-76fb-84c7-7e7ee9ddf7b9 amount: '100' currency: iso: EUR user_fee_percent: 0 status: processing rate_mode: fixed life_time: 1731423600 valid_until: 1731423600 payment_currency: iso: USDC network_name: ethereum end_user_email: customer@example.com description: Order 0511 payment_link: https://payments.cryptoprocessing.com/payment/8N8_cWBnfAbT12mR5JmPVf foreign_id: payment_request_123 url_store: https://example.com/store end_user_reference: user_12345 payment_details: address: value: '0x3b6C3c0B5d8f8c2b4E0a9d4f5b1f21C9c8A1b2C3' expected_amount: '115.28' expected_currency: iso: USDC network_name: ethereum exchange_rate: from: iso: USDC network_name: ethereum to: iso: EUR rate: '0.87' '400': description: Bad Request. content: application/json: schema: type: object title: ErrorResponse required: - error - code properties: error: type: string description: Human-readable error message. code: type: integer description: HTTP status code. examples: ForeignIdAlreadyExists: summary: Duplicate foreign_id value: error: Payment request with this foreign_id already exists. code: 400 user_fee_percent: summary: Invalid user_fee_percent value: error: user_fee_percent must be 0 or 100. code: 400 Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. description: Invalid or missing headers. Refer to [Errors](/api-reference/errors#403-forbidden) for troubleshooting steps. examples: Bad signature header: value: error: Bad signature header code: bad_header_signature No signature header: value: error: No signature header code: required_header_signature Bad key header: value: error: Bad key header code: bad_header_key No key header: value: error: No key header code: required_header_key Merchant_disabled: value: error: Merchant is disabled. code: 403 '404': description: Invalid currency content: application/json: schema: type: object title: ErrorResponse required: - error - code properties: error: type: string description: Human-readable error message. code: type: integer description: HTTP status code. examples: CurrencyIsoIncorrect: summary: Invalid currency.iso value: error: The currency.iso is incorrect. code: 404 PaymentCurrencyIsoIncorrect: summary: Invalid payment_currency.iso value: error: payment_currency.iso is incorrect. code: 404 '422': description: Failed validation content: application/json: schema: type: object title: ErrorResponse required: - error - code properties: code: type: integer description: HTTP status code. error: type: string description: Human-readable error message. examples: CurrencyIsoMandatory: summary: Missing currency.iso value: error: The iso is a mandatory field. code: 422 CurrencyIsoDisabled: summary: Disabled currency.iso value: error: The currency.iso is disabled. code: 422 CurrencyNetworkNameMandatory: summary: Missing currency.network_name for crypto value: error: The currency.network_name field is mandatory for crypto currencies. code: 422 CurrencyNetworkNotSupported: summary: Unsupported currency and network combination value: error: The combination of currency and network is not supported. code: 422 AmountMandatory: summary: Missing amount value: error: The amount field is mandatory. code: 422 AmountMinimum: summary: Amount below minimum value: error: The minimum amount is EUR. code: 422 AmountMaximum: summary: Amount above maximum value: error: The maximum amount is EUR. code: 422 AmountTooManyDecimals: summary: Too many decimal places value: error: The amount for cannot have more than decimal places. code: 422 PeriodRequired: summary: Missing life time fields value: error: It is obligatory - to fill in life_time_date_time or life_time_duration. code: 422 PeriodOnlyOneAllowed: summary: Both life time fields provided value: error: Only one of fields life_time_date_time and life_time_duration should be field. code: 422 LifeSpanTooShort: summary: Lifespan below minimum value: error: The lifespan must be longer than or equal to {minutes/days}. code: 422 LifeSpanTooLong: summary: Lifespan above maximum value: error: The lifespan must be shorter than or equal {minutes/days}. code: 422 EndUserEmailIncorrect: summary: Invalid email value: error: The email address is incorrect. code: 422 PaymentCurrencyEmpty: summary: Empty payment_currency value: error: payment_currency must not be empty if provided. code: 422 PaymentCurrencyIsoMustBeCrypto: summary: payment_currency.iso must be cryptocurrency value: error: payment_currency.iso must be a cryptocurrency. code: 422 PaymentCurrencyIsoEmpty: summary: Empty payment_currency.iso value: error: payment_currency.iso must not be empty if provided. code: 422 PaymentCurrencyIsoDisabled: summary: Disabled payment_currency.iso value: error: payment_currency.iso is disabled. code: 422 ExchangeRateUnavailable: summary: Exchange rate unavailable value: error: Exchange rate is not available between and . code: 422 PaymentCurrencyNetworkEmpty: summary: Empty payment_currency.network_name value: error: payment_currency.network_name must not be empty if provided. code: 422 PaymentCurrencyNetworkWithoutIso: summary: payment_currency.network_name without iso value: error: payment_currency.network_name cannot be specified without payment_currency.iso. code: 422 PaymentCurrencyNetworkNotSupported: summary: Unsupported payment currency and network combination value: error: The combination of currency and network is not supported. code: 422 DescriptionTooLong: summary: Description too long value: error: The description must be 255 characters or less. code: 422 DescriptionEmpty: summary: Empty description value: error: The description must not be empty if provided. code: 422 ForeignIdTooLong: summary: foreign_id too long value: error: Foreign ID must be 255 characters or less. code: 422 ForeignIdEmpty: summary: Empty foreign_id value: error: The foreign_id must not be empty if provided. code: 422 UrlStoreInvalid: summary: Invalid url_store value: error: The url_store is invalid. code: 422 UrlStoreTooLong: summary: url_store too long value: error: The url_store must be 255 characters or less. code: 422 UrlSuccessInvalid: summary: Invalid url_success value: error: The url_success is invalid. code: 422 UrlSuccessTooLong: summary: url_success too long value: error: The url_success must be 255 characters or less. code: 422 UrlFailedInvalid: summary: Invalid url_failed value: error: The url_failed is invalid. code: 422 UrlFailedTooLong: summary: url_failed too long value: error: The url_failed must be 255 characters or less. code: 422 EndUserReferenceMandatory: summary: Missing end_user_reference value: error: The end_user_reference must not be empty if provided. code: 422 EndUserReferenceTooLong: summary: end_user_reference too long value: error: The end_user_reference must be 255 characters or less. code: 422 RateModeInvalid: summary: Invalid rate_mode value: error: The rate_mode must be either standard or fixed. code: 422 SenderTypeMandatory: summary: Missing sender_type value: error: The sender_type field must be provided when sender_data is present. code: 422 SenderTypeInvalid: summary: Invalid sender_type value: error: The sender_type must be either ‘natural’ or ‘legal’. code: 422 SenderDataMandatory: summary: Missing sender_data value: error: The sender_data object must be provided when sender_type is present. code: 422 SenderDataInvalid: summary: Invalid sender_data value: error: The sender_data must be a valid object. code: 422 SenderFirstNameMandatory: summary: Missing first_name for natural sender value: error: The first_name must be provided for sender_type = natural. code: 422 SenderFirstNameTooLong: summary: first_name too long value: error: The first_name must be 255 characters or less. code: 422 SenderLastNameMandatory: summary: Missing last_name for natural sender value: error: The last_name must be provided for sender_type = natural. code: 422 SenderLastNameTooLong: summary: last_name too long value: error: The last_name must be 255 characters or less. code: 422 SenderDateOfBirthInvalid: summary: Invalid date_of_birth format value: error: The date_of_birth must be in YYYY-MM-DD format. code: 422 SenderLegalNameMandatory: summary: Missing legal_name for legal sender value: error: The legal_name must be provided for sender_type = legal. code: 422 SenderLegalNameTooLong: summary: legal_name too long value: error: The legal_name must be 255 characters or less. code: 422 SenderCountryOfRegistrationMandatory: summary: Missing country_of_registration for legal sender value: error: The country_of_registration must be provided for sender_type = legal. code: 422 SenderCountryOfRegistrationLength: summary: country_of_registration wrong length value: error: The country_of_registration must contain exactly 3 characters. code: 422 SenderCountryOfRegistrationInvalid: summary: Invalid ISO Alpha-3 country code value: error: The country_of_registration must be a valid ISO Alpha-3 code. code: 422 components: parameters: XProcessingSignatureHeader: name: X-Processing-Signature in: header required: true description: "Hex-encoded HMAC-SHA512 signature of the request body, [generated using your secret key](/api-reference/authentication)." schema: type: string schemas: ValidationOrMalformedJson: oneOf: - type: object title: ValidationError description: One or more request parameters failed validation. properties: errors: type: object additionalProperties: type: string - type: object title: MalformedJson description: The request body is not valid JSON or the Content-Type header is not set to `application/json`. properties: error: type: string code: type: string end_user_reference.deposits: type: string description: | Permanent ID of the customer in your system. Used to group, track, and analyze transactions made by a specific customer. Must not contain personal data, such as the user's name or email address. end_user_reference.withdrawals: type: string description: | Persistent internal ID of the merchant's customer who initiates the withdrawal. Use the same value for the same customer across all requests. This value must refer to the same customer described in `sender_data`. Do not include personal data, such as the customer's name or email address. Put personal details in `sender_data`. sender_type.deposits: type: string enum: - natural - legal description: | Type of the merchant's customer who sends the funds. Use `natural` if the sender is an individual person and `legal` if the sender is a legal entity. The selected type determines which fields must be included in `sender_data`. sender_type.withdrawals: type: string enum: - natural - legal description: | Type of the merchant's customer who initiates the withdrawal. The sender must be the same customer identified by `end_user_reference`. Use `natural` if the sender is an individual person and `legal` if the sender is a legal entity. The selected type determines which fields must be included in `sender_data`. sender_data: type: object description: | Must contain the details of the merchant's customer who sends the funds. - If `sender_type` is `natural`, include `first_name`, `last_name`, and `date_of_birth`. Do not include `legal_name` or `country_of_registration`. - If `sender_type` is `legal`, include `legal_name` and `country_of_registration`. Do not include `first_name`, `last_name`, or `date_of_birth`. required: - first_name - last_name - date_of_birth - legal_name - country_of_registration properties: first_name: type: string maxLength: 255 description: The sender's first name. This is required for a natural person. For a legal entity, do not include this parameter. last_name: type: string maxLength: 255 description: The sender's last name. This is required for a natural person. For a legal entity, do not include this parameter. date_of_birth: type: string description: The sender's date of birth, YYYY-MM-DD. This is required for a natural person. For a legal entity, do not include this parameter. legal_name: type: string maxLength: 255 description: The company's name. This is required for a legal entity. For a natural person, do not include this parameter. country_of_registration: type: string description: The company's country of registration (ISO alpha-3 format, three characters). This is required for a legal entity. For a natural person, do not include this parameter. sender_data.withdrawals: type: object description: | Must contain the details of the merchant's customer who initiates the withdrawal. - If `sender_type` is `natural`, include `first_name`, `last_name`, and `date_of_birth`. Do not include `legal_name` or `country_of_registration`. - If `sender_type` is `legal`, include `legal_name` and `country_of_registration`. Do not include `first_name`, `last_name`, or `date_of_birth`. required: - first_name - last_name - date_of_birth - legal_name - country_of_registration properties: first_name: type: string maxLength: 255 description: The sender's first name. This is required for a natural person. For a legal entity, do not include this parameter. last_name: type: string maxLength: 255 description: The sender's last name. This is required for a natural person. For a legal entity, do not include this parameter. date_of_birth: type: string description: The sender's date of birth, YYYY-MM-DD. This is required for a natural person. For a legal entity, do not include this parameter. legal_name: type: string maxLength: 255 description: The company's name. This is required for a legal entity. For a natural person, do not include this parameter. country_of_registration: type: string description: The company's country of registration (ISO alpha-3 format, three characters). This is required for a legal entity. For a natural person, do not include this parameter. receiver_type: type: string enum: - natural - legal - self description: | Type of the withdrawal recipient. Use `natural` if the recipient is an individual person, `legal` if the recipient is a legal entity, or `self` if the recipient is the same person or legal entity as the sender. The selected type determines whether `receiver_data` is required and which fields it must contain. receiver_data: type: object description: | Details of the withdrawal recipient. - If `receiver_type` is `natural`, include `first_name`, `last_name`, and `date_of_birth`. Do not include `legal_name` or `country_of_registration`. - If `receiver_type` is `legal`, include `legal_name` and `country_of_registration`. Do not include `first_name`, `last_name`, or `date_of_birth`. - If `receiver_type` is `self`, do not include `receiver_data`. required: - first_name - last_name - date_of_birth - legal_name - country_of_registration properties: first_name: type: string description: The recipient's first name. This is required for a natural person. For a legal entity, do not include this parameter. last_name: type: string description: The recipient's last name. This is required for a natural person. For a legal entity, do not include this parameter. date_of_birth: type: string description: The recipient's date of birth, YYYY-MM-DD. This is required for a natural person. For a legal entity, do not include this parameter. legal_name: type: string maxLength: 255 description: The company's name. This is required for a legal entity. For a natural person, do not include this parameter. country_of_registration: type: string description: The company's country of registration (ISO alpha-3 format, three characters). This is required for a legal entity. For a natural person, do not include this parameter. responses: HeaderAuthorization: description: | Forbidden content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. description: Invalid or missing headers. Refer to [Errors](/api-reference/errors#403-forbidden) for troubleshooting steps. examples: Bad signature header: value: error: Bad signature header code: bad_header_signature No signature header: value: error: No signature header code: required_header_signature Bad key header: value: error: Bad key header code: bad_header_key No key header: value: error: No key header code: required_header_key WithdrawalHeaderAuthorization: description: | Forbidden content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. description: Invalid or missing headers, or withdrawals are disabled for the merchant. Refer to [Errors](/api-reference/errors#403-forbidden) for troubleshooting steps. examples: Bad signature header: value: error: Bad signature header code: bad_header_signature No signature header: value: error: No signature header code: required_header_signature Bad key header: value: error: Bad key header code: bad_header_key No key header: value: error: No key header code: required_header_key Withdrawals disabled: summary: Withdrawals are disabled for this merchant value: error: Withdrawal functionality is currently unavailable code: withdrawal_functionality_unavailable FeatureNotEnabled: description: | API integration feature is not enabled for the authenticated client. Contact support to enable API access for your account. content: application/json: schema: type: object properties: message: type: string description: Human-readable error message. examples: Not authorized: value: message: "Not authorized" MalformedJson: description: | Bad Request The request body is not valid JSON, or the Content-Type header is not set to `application/json`. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. examples: Malformed JSON: summary: Invalid JSON body value: error: Bad content format code: bad_content_format InternalServerError: description: Internal server error content: application/json: schema: type: object properties: errors: type: array items: type: string error_code: type: integer examples: Server error: value: errors: - "Internal error" error_code: 422 InternalError: description: | Unprocessable entity. An internal error occurred during processing. The request was understood but could not be completed. The `errors` field is an array of error messages. The `error_code` is always the string `"internal_error"`. content: application/json: schema: type: object required: - errors - error_code properties: errors: type: array description: Array of error messages items: type: string error_code: type: string description: Error code identifier examples: Internal error: summary: Generic internal error value: errors: - "Internal error" error_code: "internal_error" Something went wrong: summary: Processing error value: errors: - "Something went wrong. Please try later." error_code: "internal_error" Unhandled exception: summary: Generic unhandled exception value: errors: - "Something went wrong." error_code: "internal_error" securitySchemes: xProcessingKey: type: apiKey description: "Your [API key](/merchant-administration/generate-and-activate-api-keys)." in: header name: X-Processing-Key