v2.4.0

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
Pay In - payment made by a Merchant's partner or another external source to a Pay In Address, usually to top up the Merchant balance (not linked to a Customer purchase)
Pay In Address - blockchain address of the Merchant, per Cryptocurrency, for receiving Pay Ins
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
403	`INSUFFICIENT_SCOPE`	API Key has no scope required by the endpoint, see Access scopes

Access scopes

Each API Key carries a list of scopes. Every endpoint requires exactly one scope; a request made with an API Key that lacks it is rejected with 403 INSUFFICIENT_SCOPE. Scopes are assigned by Business Support.

Scope	Grants
`balance:read`	`GET /api/v2/balance`
`rates:read`	`GET /api/v2/rates/*`, `GET /api/v2/currencies`
`deposit_addresses:create`	`POST /api/v2/deposit-addresses`
`deposit_addresses:read`	`GET /api/v2/deposit-addresses/{userId}`
`pay_in_addresses:read`	`GET /api/v2/pay-in-addresses`, `GET /api/v2/pay-in-addresses/{cryptoCurrency}`
`withdrawals:create`	`POST /api/v2/withdrawals/crypto`, `POST /api/v2/withdrawals/fiat`
`withdrawals:read`	`GET /api/v2/withdrawals/{foreignId}`
`withdrawals:cancel`	`DELETE /api/v2/withdrawals/{foreignId}`
`transactions:read`	`GET /api/v2/transactions`, `GET /api/v2/transactions/{transactionId}`
`callback:sign`	not an endpoint: marks the API Key whose Secret Key signs outgoing callbacks

Rate limits

Some endpoints (currently GET /api/v2/transactions and GET /api/v2/transactions/{transactionId}) are rate limited per Merchant within a 60-second window. Rate-limited responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers. When the limit is exceeded the API responds with 429 RATE_LIMIT_EXCEEDED and a Retry-After header (seconds).

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
REFUND_PENDING - Refund of an AML-rejected deposit has been initiated, 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 SUCCESSFUL, FAILED, or AML_FAILED.
AML_FAILED can transition to REFUND_PENDING when a refund is initiated.
REFUND_PENDING always moves to either REFUNDED or REFUND_FAILED.
REFUND_FAILED can transition back to REFUND_PENDING when the refund is retried.

Withdrawal statuses

Returned by the Withdrawal endpoints:

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
REFUNDED - A completed withdrawal was refunded by the operator and the funds were returned to the merchant balance. Emitted only for merchants with withdrawal refunds enabled

FAILED, CANCELED, and REFUNDED are final statuses. COMPLETED is final unless the withdrawal is later refunded.

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

Withdrawal callback statuses

The withdrawal callback uses its own status set (WithdrawalCallbackStatus), which differs from the one above:

SUCCESSFUL is sent instead of COMPLETED
SUBMITTED is never sent
PENDING is sent only when a processing delay is configured for the merchant

Transaction statuses

GET /api/v2/transactions returns ledger-level transactions with their own status set (TransactionStatus), shared by all operation types: SENDING, PENDING, AML_CHECKING, COMPLETED, FAILED, AML_FAILED, CANCELED, REFUND_PENDING, REFUNDED, REFUND_FAILED. These are not the same values as the Deposit and Withdrawal statuses above.

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

Required scope: deposit_addresses:create

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
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

Required scope: deposit_addresses:read

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

Pay-in Addresses V2 (Collapsed)

Pay In Address endpoints: list the Merchant Pay In Addresses, get the Pay In Address for a cryptocurrency

Pay-in Addresses V2 Operations

get/api/v2/pay-in-addresses
get/api/v2/pay-in-addresses/{cryptoCurrency}

List Pay In Addresses

Returns all Pay In Addresses of the Merchant, one per Cryptocurrency.

Required scope: pay_in_addresses:read

Responses

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

get/api/v2/pay-in-addresses

curl https://api.paynomicpay.com/api/v2/pay-in-addresses \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "TXYZabc123...",
    "cryptoCurrency": "BTC",
    "network": "TRON"
  }
]

Pay In Addresses successfully retrieved

Get Pay In Address

Returns the Merchant's Pay In Address for the specified Cryptocurrency.

Required scope: pay_in_addresses:read

Path Parameters

cryptoCurrency
Type:
required

Cryptocurrency

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/pay-in-addresses/{cryptoCurrency}

curl https://api.paynomicpay.com/api/v2/pay-in-addresses/BTC \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "TXYZabc123...",
  "cryptoCurrency": "BTC",
  "network": "TRON"
}

Pay In Address successfully retrieved

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.

Business errors

400 DUPLICATE_FOREIGN_ID - a withdrawal with this foreignId already exists, fetch it via GET /api/v2/withdrawals/{foreignId}
400 INSUFFICIENT_FUNDS - not enough funds on the merchant balance, or the withdrawal limit is exceeded
400 INVALID_ADDRESS - the address is invalid for the specified cryptocurrency

Required scope: withdrawals:create

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-30T10:32:05.531Z",
  "updatedAt": "2026-09-30T10:32:05.531Z"
}

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.

Business errors

400 DUPLICATE_FOREIGN_ID - a withdrawal with this foreignId already exists, fetch it via GET /api/v2/withdrawals/{foreignId}
400 INSUFFICIENT_FUNDS - not enough funds on the merchant balance, or the withdrawal limit is exceeded
400 INVALID_ADDRESS - the address is invalid for the specified cryptocurrency

Required scope: withdrawals:create

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-30T10:32:05.531Z",
  "updatedAt": "2026-09-30T10:32:05.531Z"
}

Fiat Withdrawal successfully created

Get withdrawal by foreignId

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

Required scope: withdrawals:read

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-30T10:32:05.531Z",
  "updatedAt": "2026-09-30T10:32:05.531Z"
}

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.

Required scope: withdrawals:cancel

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-30T10:32:05.531Z",
  "updatedAt": "2026-09-30T10:32:05.531Z"
}

Withdrawal successfully canceled

Transactions V2 (Collapsed)

Merchant transactions of all operation types: list for a period with filters and pagination, get by id

Transactions V2 Operations

get/api/v2/transactions
get/api/v2/transactions/{transactionId}

List transactions

Returns Merchant transactions of all operation types (deposits, pay ins, withdrawals, pay outs, refunds) created within a period, paginated.

Period - filtered by transaction creation date, both bounds inclusive. createdDateTo defaults to now, createdDateFrom defaults to createdDateTo minus 92 days. The period must not exceed 92 days.

Pagination - limit (default 20) is clamped to [1, 100]: out-of-range values are adjusted, not rejected. offset is a row offset.

Rate limit - requests are rate limited per Merchant, see Rate limits.

Required scope: transactions:read

Query Parameters

createdDateFrom
Type: stringFormat: date-time

Lower bound of the period (inclusive), ISO-8601
createdDateTo
Type: stringFormat: date-time

Upper bound of the period (inclusive), ISO-8601
statuses
Type: enum

Comma-separated list of transaction statuses
Type: enum

Ledger-level transaction status, shared by all operation types. Not the same set as DepositStatus / WithdrawalStatus

values
SENDING

Outgoing transaction queued for sending

PENDING

Transaction detected or broadcast, waiting for the required confirmations

AML_CHECKING

AML screening in progress

COMPLETED

Transaction completed

FAILED

Transaction failed

AML_FAILED

Transaction rejected by compliance screening

CANCELED

Transaction canceled before broadcast

REFUND_PENDING

Refund initiated, awaiting confirmations

REFUNDED

Transaction refunded

REFUND_FAILED

Refund attempt failed
types
Type: enum

Comma-separated list of operation types
Type: enum

Operation type

values
deposit

Customer Deposit to a Deposit Address

payin

Pay In to a Pay In Address

withdrawal

Withdrawal created via the API

payout

Pay Out created in the Backoffice

refund

Refund of a deposit to the original sender
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.
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.
txid
Type: string

Blockchain transaction hash
foreignId
Type: string

Operation identifier in the Merchant system
userId
Type: string

Customer identifier in the Merchant system
fromAddress
Type: string

Source address: matched against the customer address for incoming operations and against the platform address for outgoing ones
toAddress
Type: string

Destination address: matched against the platform address for incoming operations and against the customer address for outgoing ones
limit
Type: integer

Page size, clamped to [1, 100]
offset
Type: integer
min:
0

Row offset: 0 returns the first record, 20 returns records from the 21st on
sortBy
enum
const:
createdDate

Sort field
sortOrder
Type: "ASC" or "DESC"enum

Sort order

Responses

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

get/api/v2/transactions

curl 'https://api.paynomicpay.com/api/v2/transactions?createdDateFrom=2026-06-01T00%3A00%3A00.000Z&createdDateTo=2026-06-30T23%3A59%3A59.999Z&statuses=COMPLETED%2CPENDING&types=deposit%2Cwithdrawal&cryptoCurrencies=BTC%2CUSDT-TRC20&fiatCurrencies=USD%2CEUR&limit=20&offset=0&sortBy=createdDate&sortOrder=DESC' \
  --header 'api-key: YOUR_SECRET_TOKEN' \
  --header 'x-signature: YOUR_SECRET_TOKEN'

Show Schema

{
  "data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-000000000000",
      "status": "SENDING",
      "type": "deposit",
      "userId": "user-42",
      "foreignId": "order-777",
      "fiatAmount": "92.00",
      "fiatCurrency": "USD",
      "cryptoAmount": "100.000000",
      "cryptoCurrency": "BTC",
      "txid": null,
      "vout": 0,
      "tag": null,
      "fromAddress": null,
      "toAddress": null,
      "rate": "0.92",
      "usdAmount": null,
      "settlement": {
        "amount": "0.000007",
        "fee": "0.000001",
        "currency": "BTC",
        "rate": "string"
      },
      "createdDate": "2026-06-18T12:00:00.000Z",
      "updatedDate": "2026-06-18T12:05:00.000Z",
      "risk": {
        "level": "HIGH",
        "categories": [
          {
            "category": "sanctions",
            "level": "HIGH"
          }
        ]
      }
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}

Transactions successfully retrieved

Get transaction

Returns a single Merchant transaction by its identifier (id from the list).

Rate limit - shares the limit with GET /api/v2/transactions, see Rate limits.

Required scope: transactions:read

Path Parameters

transactionId
Type: string
required

Transaction identifier

Responses

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

get/api/v2/transactions/{transactionId}

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

Show Schema

{
  "id": "c1d2e3f4-0000-0000-0000-000000000000",
  "status": "SENDING",
  "type": "deposit",
  "userId": "user-42",
  "foreignId": "order-777",
  "fiatAmount": "92.00",
  "fiatCurrency": "USD",
  "cryptoAmount": "100.000000",
  "cryptoCurrency": "BTC",
  "txid": null,
  "vout": 0,
  "tag": null,
  "fromAddress": null,
  "toAddress": null,
  "rate": "0.92",
  "usdAmount": null,
  "settlement": {
    "amount": "0.000007",
    "fee": "0.000001",
    "currency": "BTC",
    "rate": "string"
  },
  "createdDate": "2026-06-18T12:00:00.000Z",
  "updatedDate": "2026-06-18T12:05:00.000Z",
  "risk": {
    "level": "HIGH",
    "categories": [
      {
        "category": "sanctions",
        "level": "HIGH"
      }
    ]
  }
}

Transaction successfully retrieved

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
- REFUND_PENDING
  
  Refund of an AML-rejected deposit has been initiated, awaiting confirmations
- REFUNDED
  
  Refund transaction fully confirmed on-chain
- REFUND_FAILED
  
  Refund attempt failed, manual intervention is required
context
Type: object

Additional context attached to the deposit, if any. Free-form object, its structure is not fixed; omitted when there is no context

Properties: 1
risk
Type:

AML risk of the operation. Present only when AML risk disclosure is enabled for the merchant; omitted otherwise

Properties: 2

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": ""
  },
  "risk": {
    "level": "HIGH",
    "categories": [
      {
        "category": "sanctions",
        "level": "HIGH"
      }
    ]
  },
  "context": {
    "additionalProperty": "anything"
  }
}'

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

Status of a withdrawal as sent in the withdrawal callback. Differs from WithdrawalStatus: SUCCESSFUL is sent instead of COMPLETED, SUBMITTED is never sent
values
- PENDING
  
  Transaction broadcast to the blockchain, waiting for the required confirmations. Sent only when a processing delay is configured for the merchant
- SUCCESSFUL
  
  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 before any transaction was broadcast to Network, no funds were debited
- REFUNDED
  
  Completed withdrawal refunded by the operator, funds returned to the merchant balance
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": ""
  },
  "risk": {
    "level": "HIGH",
    "categories": [
      {
        "category": "sanctions",
        "level": "HIGH"
      }
    ]
  }
}'

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

Access scopes

Rate limits

Retries and idempotency

On timeout or network error

When to use a new foreignId

Callbacks

Callback types

Statuses

Deposit statuses

Withdrawal statuses

Withdrawal callback statuses

Transaction statuses

Integration Guidelines

Deposit V2 (Collapsed)

Create Deposit Addresses

Body·CreateDepositAddressesPayload

Responses

Get Deposit Address

Path Parameters

Query Parameters

Responses

Pay-in Addresses V2 (Collapsed)

List Pay In Addresses

Responses

Get Pay In Address

Path 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

Transactions V2 (Collapsed)

List transactions

Query Parameters

Responses

Get transaction

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·