v2.2.3

OpenAPI 3.1.0

Business API

Overview

Welcome to the Business API documentation!

Here are the main terms we use:

Merchant - partner which integrated with Business API to accept Cryptocurrency payments from Customers
Customer - end user who uses crypto to pay for goods or services offered by a Merchant
Deposit - the act of Customer sending crypto from an external wallet to their Deposit Address, with the goal to increase the customer's account balance at Merchant
Deposit Address - dedicated blockchain address assigned to Customer for incoming deposits using specific Cryptocurrency and Fiat Currency
Consolidation Address - address that aggregates Merchant funds and is the source of outgoing operations
Withdrawal - customer-initiated transfer from the Consolidation Address to an external address
Callback - HTTP server-to-server notification sent to Merchant after key transaction events like new deposits, status changes or address rotations, for real-time processing

Preconditions

Credentials

Request your API Key and Secret Key from Business Support

API Key - public merchant identifier, sent in the api-key header with each request
Secret Key - key used to calculate request signatures, sent in the x-signature header with each request, must be kept secret

IP whitelisting

Provide the outbound IP addresses of all servers that will call the API so Business API can allow them through its firewall Add the Business API callback IP range to your own firewall allow-list to ensure callbacks reach your servers

Authentication

Endpoints are protected by an HMAC-SHA256 signature scheme that authenticates every request.

Authentication flow recap

Determine HTTP method, path, query and request body
Build canonical request string: HTTP_METHOD + PATH_AND_QUERY + REQUEST_BODY
Generate HMAC-SHA256 digest using the canonical string and Secret Key
Hex-encode the digest (lower-case) to create request signature
Send the request with mandatory headers:
- api-key - API Key
- x-signature - request parameters, signed with Secret Key
Server locates Secret Key by API Key and validates the signature:
- on mismatch or missing data it replies with 400 Bad Request or 401 Unauthorized
- on success your request will be handled

Canonical request representation

Normalized string that represents important parts of the HTTP request. Resulting string must match exactly between client and server to ensure consistent signature generation and verification.

CANONICAL_REQUEST = HTTP_METHOD + PATH_AND_QUERY + REQUEST_BODY

HTTP_METHOD - verb exactly as it appears in the HTTP request, for example GET, POST
PATH_AND_QUERY - full path including query string, for example /api/v2/withdrawal?id=10
REQUEST_BODY - raw body payload for POST / PUT, empty string for GET / DELETE

Request Signature

Signature is a lowercase hex-encoded HMAC-SHA256 digest of the canonical request. It proves that the request was created by someone who has the Merchant's Secret Key and that the request content has not been changed.

REQUEST_SIGNATURE = hex(
  hmac-sha256(SECRET_KEY, CANONICAL_REQUEST)
)

hmac-sha256(...) - computes HMAC using the SHA256 algorithm and a provided signing key
hex(...) - encodes the HMAC signature as a lowercase hexadecimal string
CANONICAL_REQUEST - canonical request representation
SECRET_KEY - secret key issued to Merchant, must be kept secret

Server Request

Signature is sent to the server using the x-signature header. The server uses the api-key header to find Secret Key and verify the signature against the canonical representation of the received request. Both headers are required and must match the expected values. Requests with missing or invalid authentication headers will be rejected with 400 Bad Request or 401 Unauthorized HTTP status code.

Required headers

The following HTTP header keys must be used for Merchant authentication when making API calls:
api-key - API_KEY identifies the merchant
x-signature - REQUEST_SIGNATURE proves request integrity and authenticity

These headers are used together to ensure the request was created by an authorized merchant. The canonical request is signed using the merchant's secret key, and the server verifies that the signature matches the request data.

Authenticaton Error Codes

HTTP Status	Code	Meaning
400	`API_KEY_NOT_SPECIFIED`	`api-key` header missing
400	`SIGNATURE_NOT_SPECIFIED`	`x-signature` header missing
401	`IP_ADDRESS_IS_NOT_WHITELISTED`	Origin IP not allowed
401	`INVALID_AUTHORIZATION_DATA`	Authentication not passed

Retries and idempotency

foreignId is the idempotency key for create operations. It MUST be stable across retries of the same logical withdrawal — never regenerate foreignId when retrying.

On timeout or network error

A timeout or transport-level error does not mean the withdrawal failed. The server may have created the withdrawal even when the response did not reach the client. Recovery flow:

Do not retry immediately and do not mark the withdrawal as failed.
Wait at least 10 seconds.
Call GET /api/v2/withdrawals/{foreignId} with the same foreignId.
- If found — the original create succeeded, use the returned status.
- If 404 Not Found — retry the create with the same foreignId.

A withdrawal is final only when the API returns COMPLETED, FAILED, or CANCELED. Network errors, 5xx responses, and timeouts are inconclusive.

When to use a new `foreignId`

Use a new foreignId only for a distinct withdrawal. Splitting one payout into multiple withdrawals is fine — each split is its own withdrawal with its own foreignId.

Reusing the create call with a new foreignId for what is conceptually the same withdrawal (a retry after a timeout, an operator clicking create again) bypasses duplicate protection and produces two withdrawals on the same external address.

If create returns 400 DUPLICATE_FOREIGN_ID, the withdrawal already exists on the server — fetch it via GET /api/v2/withdrawals/{foreignId} rather than retrying with a different foreignId.

Callbacks

Once an event occurs, Business API sends an HTTP POST to the callbackUrl you provided when creating the deposit or withdrawal

Forward-compatibility - new fields or currency codes can appear at any time
ignore unknown keys and unexpected enum values
HTTP 2xx - reply with any status in the 200-299 range, body may be empty
Retry schedule - if your endpoint responds with anything outside the 2xx range we will retry the callback ten times using the following back-off delays (in seconds): 60, 120, 180, 240, 300, 360, 420, 480, 540, 600
Signature verification - every webhook carries a lowercase-hex x-signature header:
HMAC-SHA-256(secretKey, METHOD + PATH_AND_QUERY + REQUEST_BODY)

Callback types

deposit - crypto funds received at a deposit address
withdrawal - crypto sent to an external wallet
addressRotation - deposit address replaced with a new one

For full descriptions see the Callback Reference

Statuses

Deposit statuses

PENDING - Incoming transaction detected, waiting for the required blockchain confirmations and AML validation
SUCCESSFUL - Confirmations and AML checks complete, deposit credited to the customer balance
FAILED - Deposit could not be processed, no funds were credited
AML_FAILED - Deposit rejected by automated compliance screening
REFUNDING - Refund transaction has been initiated and broadcast, awaiting confirmations
REFUNDED - Refund transaction fully confirmed on-chain
REFUND_FAILED - Refund attempt failed, manual intervention is required

SUCCESSFUL, FAILED, and REFUNDED are final statuses.

PENDING can transition to any final state above.
REFUND_FAILED can transition back to REFUNDING.
REFUNDING always moves to either REFUNDED or REFUND_FAILED.

Withdrawal statuses

SUBMITTED - Withdrawal request accepted and queued for processing
CANCELED - Withdrawal canceled by the customer or merchant before any on-chain transaction was broadcast, no funds were debited
PENDING - Transaction broadcast to the blockchain, waiting for the required confirmations
COMPLETED - Required confirmations received, withdrawal settled to the external address
FAILED - Withdrawal could not be completed, the original funds were returned to the merchant balance
AML_FAILED - Withdrawal blocked by compliance screening

COMPLETED, FAILED, and CANCELED are final statuses.

SUBMITTED can transition to CANCELED, PENDING, or AML_FAILED.
PENDING can transition to COMPLETED, FAILED, or AML_FAILED.

Integration Guidelines

String-encoded numbers - every monetary value is returned as a string with a dot . decimal separator, to avoid rounding errors in JSON. Use a fixed-precision/decimal library when parsing.
UTC timestamps - all date/time fields are ISO-8601 strings in UTC, Do not apply local offsets when validating signatures or comparing timestamps.
Forward-compatible enums & objects - new enum items and new JSON properties can appear at any time. Treat unknown enum values as “other”, and ignore unrecognised keys rather than failing hard
Nullable / optional fields - any property that can be null may also be omitted. Your code should handle both null and “missing”.
Idempotency keys - foreignId is the merchant-supplied idempotency key for create operations. Keep it stable across retries of the same logical withdrawal and never regenerate it on retry. id is the server-assigned unique identifier. See the Retries and idempotency section above for the full retry flow

Server

https://api.paynomicpay.com

Client Libraries

Shell Curl

Deposit V2 (Collapsed)

Deposit endpoints: create deposit addresses, get existing deposit address

Deposit V2 Operations

post/api/v2/deposit-addresses
get/api/v2/deposit-addresses/{userId}

Create Deposit Addresses

Creates Deposit Addresses for the Customer identified by userId.

Idempotent call - if an address for the exact tuple (userId, cryptoCurrency, fiatCurrency) already exists the API returns the existing addresses
Forced rotation - set force: true to replace the current address. addressRotation callback will be emited
All Deposit Addresses are linked to the given customer and fiatCurrency

Body·

required

application/json

callbackUrl
Type: string
required

URL to which callback notifications will be sent about detected Deposits status changes to created Deposit Address
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
userId
Type:
required

Customer identifier in Merchant system
fiatCurrency
Type:

Fiat currency in which the deposit will be quoted. If omitted, USD is assumed
force
Type: boolean | null

If true addresses will be recreated and callback with type addressRotation issued

Responses

application/json
application/json
application/json
application/json

post/api/v2/deposit-addresses

curl https://api.paynomicpay.com/api/v2/deposit-addresses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "fiatCurrency": "USD",
  "cryptoCurrency": "BTC",
  "callbackUrl": "https://api.mymerchant.fyi/callbacks/withdrawals",
  "force": false
}'

Show Schema

{
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "addresses": [
    {
      "address": "0x01ff1726A783E4bF964123A88abB85Cc87078490",
      "cryptoCurrency": "BTC",
      "fiatCurrency": "USD"
    }
  ]
}

Customer deposit addresses already exist

Get Deposit Address

Returns deposit addresses that belongs to the specified userId
A user can hold addresses in multiple fiat currencies, each object in addresses represents one fiatCurrency

Path Parameters

userId
Type:
required

Customer identifier in the Merchant's system

Customer identifier in Merchant system

Query Parameters

fiatCurrencies
Type:

Comma-separated list of fiat currency codes to keep in the response, for example USD,EUR
Type:

Fiat-currency code.

Currently supported values: USD, EUR, RUB, UAH, TRY, BRL, KZT, MXN, SEK, HUF, BGN, PLN, JPY, KRW, AUD, NOK, RON, BYN, CAD, UZS, AZN, INR.

Forward-compatibility: new fiat-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
cryptoCurrencies
Type:

Comma-separated list of crypto currency codes to keep in the response, for example BTC,USDT-TRC20
Type:

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/api/v2/deposit-addresses/{userId}

curl 'https://api.paynomicpay.com/api/v2/deposit-addresses/5b1dee5a-9005-46d9-b520-014ce58ce6df?fiatCurrencies=USD%2CEUR&cryptoCurrencies=BTC%2CUSDT-TRC20' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

{
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "addresses": [
    {
      "address": "0x01ff1726A783E4bF964123A88abB85Cc87078490",
      "cryptoCurrency": "BTC",
      "fiatCurrency": "USD"
    }
  ]
}

Returns deposit address found by userId

Withdrawal V2 (Collapsed)

Withdrawal endpoints for both crypto and fiat Withdrawals: create, cancel and track withdrawal status

Withdrawal V2 Operations

post/api/v2/withdrawals/crypto
post/api/v2/withdrawals/fiat
get/api/v2/withdrawals/{foreignId}
delete/api/v2/withdrawals/{foreignId}

Create crypto Withdrawal

Initiates withdrawal where the requested cryptocurrency amount is debited from the merchant balance and sent to the recipient address provided in the payload.
The amount transferred equals the request amount for the chosen blockchain, network fee is covered by platform.

Callback notifications
Every status change for Withdrawal is pushed to the merchant's callbackUrl Each callback contains the current status and withdrawal details

Retry policy
On timeout or network error, do not retry immediately. Wait at least 10 seconds, then call GET /api/v2/withdrawals/{foreignId} with the same foreignId to determine whether the withdrawal was created. See the Retries and idempotency section for the full flow.

foreignId is a stable idempotency key — reuse the same value when retrying the same logical withdrawal. A new foreignId represents a new withdrawal.

Body·

required

application/json

address
Type:
required

External Address
callbackUrl
Type: string
required

URL for sending callbacks
cryptoAmount
Type: string
required

Withdrawal amount in the requested cryptocurrency
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
foreignId
Type: string
required

Stable identifier from the merchant's system. Acts as the idempotency key for this withdrawal — MUST remain identical across all retries of the same logical withdrawal. Generate a new value only when creating a different withdrawal (for example, a separate split of a larger payout). Reusing a foreignId that already exists on the server returns 400 DUPLICATE_FOREIGN_ID.
tag
Type: string

Message or reference
userId
Type:

Customer identifier in Merchant system

Responses

application/json
application/json
application/json
application/json
application/json

post/api/v2/withdrawals/crypto

curl https://api.paynomicpay.com/api/v2/withdrawals/crypto \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoAmount": "0.000007",
  "cryptoCurrency": "BTC",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": "",
  "callbackUrl": "https://api.mymerchant.fyi/callbacks/withdrawals"
}'

Show Schema

{
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "cryptoAmount": "0.000007",
  "fiatCurrency": "USD",
  "fiatAmount": "15.20",
  "usdAmount": "3.20",
  "rate": "string",
  "status": "PENDING",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": null,
  "txid": null,
  "createdAt": "2026-09-28T08:08:26.214Z",
  "updatedAt": "2026-09-28T08:08:26.214Z"
}

Cryptocurrency Withdrawal successfully created

Create fiat Withdrawal

Initiates withdrawal where the requested fiat amount is converted into the chosen Cryptocurrency using internal exchange rate at the moment the request is processed. After conversion, the resulting crypto amount is sent to the recipient address specified in the payload. The final crypto amount is returned in the response.

Callback notifications
Every status change for Withdrawal is pushed to the merchant's callbackUrl Each callback contains the current status and withdrawal details

foreignId is a stable idempotency key — reuse the same value when retrying the same logical withdrawal. A new foreignId represents a new withdrawal.

Body·

required

application/json

address
Type:
required

External Address
callbackUrl
Type: string
required

URL for sending callbacks
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
fiatAmount
Type: string
required

Withdrawal amount in the requested fiat currency
fiatCurrency
Type:
required

Fiat-currency code.

Currently supported values: USD, EUR, RUB, UAH, TRY, BRL, KZT, MXN, SEK, HUF, BGN, PLN, JPY, KRW, AUD, NOK, RON, BYN, CAD, UZS, AZN, INR.

Forward-compatibility: new fiat-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
foreignId
Type: string
required

Stable identifier from the Merchant's system. Acts as the idempotency key for this withdrawal — MUST remain identical across all retries of the same logical withdrawal. Generate a new value only when creating a different withdrawal (for example, a separate split of a larger payout). Reusing a foreignId that already exists on the server returns 400 DUPLICATE_FOREIGN_ID.
tag
Type: string

Message or reference
userId
Type:

Customer identifier in Merchant system

Responses

application/json
application/json
application/json
application/json
application/json

post/api/v2/withdrawals/fiat

curl https://api.paynomicpay.com/api/v2/withdrawals/fiat \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "fiatCurrency": "USD",
  "fiatAmount": "15.20",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": "",
  "callbackUrl": "https://api.mymerchant.fyi/callbacks/withdrawals"
}'

Show Schema

{
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "cryptoAmount": "0.000007",
  "fiatCurrency": "USD",
  "fiatAmount": "15.20",
  "usdAmount": "3.20",
  "rate": "string",
  "status": "PENDING",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": null,
  "txid": null,
  "createdAt": "2026-09-28T08:08:26.214Z",
  "updatedAt": "2026-09-28T08:08:26.214Z"
}

Fiat Withdrawal successfully created

Get withdrawal by foreignId

Retrieves Withdrawal by its foreignId (the identifier provided when creating the withdrawal)

Path Parameters

foreignId
Type: string
required

withdrawal identifier at Merchant's system

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/api/v2/withdrawals/{foreignId}

curl 'https://api.paynomicpay.com/api/v2/withdrawals/{foreignId}' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "cryptoAmount": "0.000007",
  "fiatCurrency": "USD",
  "fiatAmount": "15.20",
  "usdAmount": "3.20",
  "rate": "string",
  "status": "PENDING",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": null,
  "txid": null,
  "createdAt": "2026-09-28T08:08:26.214Z",
  "updatedAt": "2026-09-28T08:08:26.214Z"
}

withdrawal successfully retrieved

Cancel withdrawal by foreignId

Cancels a Withdrawal identified by its foreignId.

Only withdrawals in SUBMITTED status can be canceled - the request is acknowledged before any on-chain transaction is broadcast and no funds are debited.

If the withdrawal has already advanced beyond SUBMITTED (for example to PENDING, when the transaction has already been broadcast on-chain) it can no longer be canceled and the API responds with 409 Conflict.

Callback notifications
A withdrawal callback is emitted when the cancellation is applied, carrying the final status of the withdrawal.

Path Parameters

foreignId
Type: string
required

withdrawal identifier at Merchant's system

Responses

application/json
application/json
application/json
application/json
application/json
application/json
application/json

delete/api/v2/withdrawals/{foreignId}

curl 'https://api.paynomicpay.com/api/v2/withdrawals/{foreignId}' \
  --request DELETE \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "cryptoAmount": "0.000007",
  "fiatCurrency": "USD",
  "fiatAmount": "15.20",
  "usdAmount": "3.20",
  "rate": "string",
  "status": "PENDING",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "tag": null,
  "txid": null,
  "createdAt": "2026-09-28T08:08:26.214Z",
  "updatedAt": "2026-09-28T08:08:26.214Z"
}

Withdrawal successfully canceled

Callbacks V2 (Collapsed)

Reference examples only - these paths let you inspect the exact JSON payloads system will POST to the callbackUrl you supply during address creation

When your server receives a webhook, respond with HTTP 200 OK - any other code triggers retries
Validate the x-signature HMAC header to ensure integrity.
Forward-compatibility - new fields and new currency enum values can appear at any time. Use tolerant deserialization so unknown keys or enum items do not break your integration

Callbacks V2 Operations

post/callback/deposit
post/callback/withdrawal
post/callback/address-rotation

Deposit

Fired when a customer deposit is detected and status changed

Body·

required

application/json

address
Type:
required

Deposit Address
callbackType
enum
const:
deposit
required

Always deposit
cryptoAmount
Type: string
required

Credited amount in Cryptocurrency
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
fiatAmount
Type: string
required

Credited amount in fiat
fiatCurrency
Type:
required

Fiat-currency code.

Currently supported values: USD, EUR, RUB, UAH, TRY, BRL, KZT, MXN, SEK, HUF, BGN, PLN, JPY, KRW, AUD, NOK, RON, BYN, CAD, UZS, AZN, INR.

Forward-compatibility: new fiat-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
id
Type: string
required

Unique deposit id, can be used as idempotency key
rate
Type: string
required

Rate used for conversion between cryptoAmount and fiatAmount
settlement
Type:
required
Settlement breakdown of the operation. The merchant balance always changes by exactly amount.
- Deposit: amount = amount credited to the merchant balance (received amount minus fee), fee = platform fee.
- Withdrawal: cryptoAmount is the requested amount that the recipient receives; fee = platform fee charged on top; amount = cryptoAmount + fee = total amount debited from the merchant balance.
Properties: 4
status
Type: enum
required

Lifecycle status of a deposit
values
- PENDING
  
  Incoming transaction detected, waiting for the required blockchain confirmations and AML validation
- SUCCESSFUL
  
  Confirmations and AML checks complete, deposit credited to the customer balance
- FAILED
  
  Deposit could not be processed, no funds were credited
- AML_FAILED
  
  Deposit rejected by automated compliance screening
- REFUNDING
  
  Refund transaction has been initiated
- REFUNDED
  
  Refund transaction fully confirmed on-chain
- REFUND_FAILED
  
  Refund attempt failed, manual intervention is required
senderAddress
Type: string | null

External address that funds were sent from
txid
Type: string | null

Blockchain transaction hash (nullable, for internal transfers)

Responses

200

Any 2xx means “received”

post/callback/deposit

curl https://api.paynomicpay.com/callback/deposit \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "callbackType": "deposit",
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "status": "PENDING",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "fiatAmount": "15.20",
  "fiatCurrency": "USD",
  "cryptoAmount": "0.000007",
  "cryptoCurrency": "BTC",
  "rate": "",
  "address": "0x01ff1726A783E4bF964123A88abB85Cc87078490",
  "txid": null,
  "senderAddress": null,
  "usdAmount": "3.20",
  "settlement": {
    "amount": "0.000007",
    "fee": "0.000001",
    "currency": "BTC",
    "rate": ""
  }
}'

No Body

Any 2xx means “received”

Withdrawal

Fired when customer-initiated withdrawal is created and status changed

Body·

required

application/json

address
Type:
required

External Address
callbackType
enum
const:
withdrawal
required
cryptoAmount
Type: string
required

Crypto amount
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
fiatAmount
Type: string
required

Fiat amount
fiatCurrency
Type:
required

Fiat-currency code.

Currently supported values: USD, EUR, RUB, UAH, TRY, BRL, KZT, MXN, SEK, HUF, BGN, PLN, JPY, KRW, AUD, NOK, RON, BYN, CAD, UZS, AZN, INR.

Forward-compatibility: new fiat-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
foreignId
Type: string
required

Withdrawal identifier from the merchant's system
id
Type: string
required

Unique withdrawal id, can be used as idempotency key
rate
Type: string
required

Rate used for conversion between cryptoAmount and fiatAmount
settlement
Type:
required
Settlement breakdown of the operation. The merchant balance always changes by exactly amount.
- Deposit: amount = amount credited to the merchant balance (received amount minus fee), fee = platform fee.
- Withdrawal: cryptoAmount is the requested amount that the recipient receives; fee = platform fee charged on top; amount = cryptoAmount + fee = total amount debited from the merchant balance.
Properties: 4
status
Type: enum
required

Lifecycle status of a withdrawal
values
- PENDING
  
  Transaction broadcast to the blockchain, waiting for the required confirmations
- SUBMITTED
  
  Withdrawal request accepted and queued for processing
- COMPLETED
  
  Required confirmations received, withdrawal settled to the external address
- AML_FAILED
  
  Withdrawal blocked by compliance screening
- FAILED
  
  Withdrawal could not be completed, the original funds were returned to the merchant balance
- CANCELED
  
  Withdrawal was canceled by the customer or merchant before any transaction was broadcast to Network, no funds were debited
userId
Type:
required

Customer identifier in Merchant system

Responses

200

Any 2xx means “received”

post/callback/withdrawal

curl https://api.paynomicpay.com/callback/withdrawal \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "callbackType": "withdrawal",
  "id": "2b8d7dbe-b1f0-409b-a82f-670a7361abca",
  "status": "PENDING",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "foreignId": "6rS9rUPwwUOHaU3D0s3x3w",
  "fiatAmount": "15.20",
  "fiatCurrency": "USD",
  "cryptoAmount": "0.000007",
  "cryptoCurrency": "BTC",
  "usdAmount": "3.20",
  "rate": "",
  "address": "0xfe00e8d9587c1b4069bedc5775447a3378f87b6f",
  "txid": null,
  "settlement": {
    "amount": "0.000007",
    "fee": "0.000001",
    "currency": "BTC",
    "rate": ""
  }
}'

No Body

Any 2xx means “received”

Address Rotation

Fired when a Customer's Deposit Address is replaced

Body·

required

application/json

address
Type:
required

Deposit Address
callbackType
enum
const:
addressRotation
required
convertToFiat
Type:
required

Fiat-currency code.

Currently supported values: USD, EUR, RUB, UAH, TRY, BRL, KZT, MXN, SEK, HUF, BGN, PLN, JPY, KRW, AUD, NOK, RON, BYN, CAD, UZS, AZN, INR.

Forward-compatibility: new fiat-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
cryptoCurrency
Type:
required

Crypto-currency code.

Currently supported values: ADA, ALGO, ARB-ARB-ERC20, AVAX, BTC, BCH, BTCB-BEP20, BNB, BNB-POL-ERC20, DAI-BEP20, DAI-ERC20, DOGE, DOGE-BEP20, ETH, ETH-ARB, ETH-BASE, ETH-BEP20, ETH-OP, LTC, LINK-BEP20, LINK-ERC20, POL, POL-BEP20, POL-ERC20, SHIB-BEP20, SHIB-ERC20, SOL, SOL-BEP20, TON, TRX, UNI-BEP20, UNI-ERC20, USDC-ARB-ERC20, USDC-AVAX-ERC20, USDC-BASE-ERC20, USDC-BEP20, USDC-ERC20, USDC-OP-ERC20, USDC-POL-ERC20, USDC-SOL, USDT-ARB-ERC20, USDT-AVAX-ERC20, USDT-BASE-ERC20, USDT-BEP20, USDT-ERC20, USDT-OP-ERC20, USDT-POL-ERC20, USDT-SOL, USDT-TEP74, USDT-TRC20, WBNB-POL-ERC20, WBTC-ARB-ERC20, WBTC-BASE-ERC20, WBTC-ERC20, WBTC-OP-ERC20, WBTC-POL-ERC20, WETH-ARB-ERC20, WETH-BASE-ERC20, WETH-BEP20, WETH-ERC20, WETH-POL-ERC20, WSOL-POL-ERC20, WXRP-ERC20, XRP, XRP-BEP20.

Forward-compatibility: new crypto-currency codes can be added at any time without prior notice. Clients MUST treat this field as a plain string and tolerate previously unseen values rather than failing on them.
userId
Type:
required

Customer identifier in Merchant system

Responses

200

Any 2xx means “received”

post/callback/address-rotation

curl https://api.paynomicpay.com/callback/address-rotation \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN' \
  --data '{
  "callbackType": "addressRotation",
  "userId": "5b1dee5a-9005-46d9-b520-014ce58ce6df",
  "cryptoCurrency": "BTC",
  "convertToFiat": "USD",
  "address": "0x01ff1726A783E4bF964123A88abB85Cc87078490"
}'

No Body

Any 2xx means “received”

Business API

Overview

Preconditions

Credentials

IP whitelisting

Authentication

Authentication flow recap

Canonical request representation

Request Signature

Server Request

Required headers

Authenticaton Error Codes

Retries and idempotency

On timeout or network error

When to use a new foreignId

Callbacks

Callback types

Statuses

Deposit statuses

Withdrawal statuses

Integration Guidelines

AuthenticationRequired

Deposit V2 (Collapsed)

Create Deposit Addresses

Body·CreateDepositAddressesPayload

Responses

Get Deposit Address

Path Parameters

Query Parameters

Responses

Withdrawal V2 (Collapsed)

Create crypto Withdrawal

Body·CreateCryptoWithdrawalPayload

Responses

Create fiat Withdrawal

Body·CreateFiatWithdrawalPayload

Responses

Get withdrawal by foreignId

Path Parameters

Responses

Cancel withdrawal by foreignId

Path Parameters

Responses

Balance V2 (Collapsed)

Rate V2 (Collapsed)

Currency V2 (Collapsed)

Callbacks V2 (Collapsed)

Deposit

Body·DepositCallback

Responses

Withdrawal

Body·WithdrawalCallback

Responses

Address Rotation

Body·AddressRotationCallback

Responses

Models

When to use a new `foreignId`

Body·

Body·

Body·

Body·

Body·

Body·