Reference

0xPay API SDK with methods and utilities

Table of contents

Properties

• IPN_KIND

• IPN_STATUS

Constructors

• constructor

Basic Crypto Operations Methods

• createReceiveAddress

• withdrawCrypto

• getCryptoWithdrawalFee

• getAvailableCryptoAssets

Basic Fiat Operations Methods

• withdrawFiat

• withdrawFiatBatch

• getFiatWithdrawalFee

• getAvailableFiatAssets

Crypto Invoices Methods

• createCryptoInvoice

Exchange Methods

• getAvailableExchangeDirections
• estimateExchange
• exchange

Fiat Invoices Methods

• createFiatInvoice

Merchant Info Methods

• getBalances

Utilities Methods

• validateWebhookRequest
• isIpnReplenish
• isIpnInvoice
• isIpnWithdraw
• isIpnExchange
• isIpnWithdrawBatch
• isIpnWithdrawExchangeCrypto
• isIpnWithdrawExchangeFiat

Withdraw With Exchange Methods

• estimateExchangeWithdrawalCrypto
• estimateExchangeWithdrawalFiat
• withdrawExchangeCrypto
• withdrawExchangeFiat

Properties

IPN_KIND

▪ Static Readonly IPN_KIND: typeof IpnKind = IpnKind

Shortcut for IpnKind enum

---

IPN_STATUS

▪ Static Readonly IPN_STATUS: typeof IpnStatus = IpnStatus

Shortcut for IpnStatus enum

Constructors

constructor

• new XPay(merchantId, privateKey, options?)

Parameters

Name	Type	Description
merchantId	string	Merchant ID
privateKey	string	Merchant private key
options	Object	Sdk options
options.signatureTTL?	number	Time to live for webhook notifiations signature. Must be greater than 1 if provided
options.url?	string	Url of public api

Basic Crypto Operations Methods

createReceiveAddress

▸ createReceiveAddress(body): Promise<string>

Create a deposit wallet address

As said previously, you can generate new deposit addresses with receiving addresses feature. For BEP20 & ERC20 networks: on creation, one wallet address will be generated and assigned for both networks, and monitored for incoming transactions.

Remarks

Deposit Updates: After a receiving address is created on a dedicated blockchain, 0xPay will notify you about incoming transactions for all the assets supported on this blockchain.

Throws

XPayApiError if validation failed or exceed limit(not verified merchant)

Parameters

Name	Type	Description
body	Object	Request body
body.blockchain	Blockchain	Blockchain in which address will be created
body.meta?	string	Metadata to catch it back later with a notification

Returns

Promise<string>

Receive address

---

withdrawCrypto

▸ withdrawCrypto(body): Promise<string>

Send cryptocurrency transaction

Creates an outgoing cryptocurrency transaction.

Remarks

0xpay API will produce notifications according to status updates on your withdrawal.

Throws

XPayApiError if validation failed, not enough balance or not enough fee

Parameters

Name	Type	Description
body	Object	Request body
body.localId?	string	If was specified - error will be thrown if not unique
body.amount	string	Amount in decimal format
body.to	string	Destination wallet address
body.ticker	string	Currency ticker to withdraw
body.blockchain	Blockchain	Blockchain in which withdraw transaction will be created
body.meta?	string	Metadata to catch it back later with a notification
body.fee?	string	Precalculated fee. If not the specified – fee will be set automatically

Returns

Promise<string>

Withdraw id

---

getCryptoWithdrawalFee

▸ getCryptoWithdrawalFee(amount, ticker, blockchain, address?): Promise<string>

Get crypto withdraw fee

This method is used to get a fee for sending a desired amount of assets (ticker) on a chosen blockchain.

Throws

XPayApiError if validation failed

Parameters

Name	Type	Description
amount	string	Withdraw amount in decimal format
ticker	string	Currency ticker to withdraw
blockchain	Blockchain	Blockchain in which withdraw transaction will be created
address?	string	Destination wallet address(if you fill it in, we'll check if the transaction might be an internal transfer)

Returns

Promise<string>

Withdraw fee

---

getAvailableCryptoAssets

▸ getAvailableCryptoAssets(): Promise<CryptoAsset[]>

List all supported crypto assets

This method is used to fetch all available crypto assets of your merchant.

Returns

Promise<CryptoAsset[]>

Array of all crypto assets with their ticker, name, price, and blockchain network

---

Basic Fiat Operations Methods

withdrawFiat

▸ withdrawFiat(body): Promise<string>

Send single fiat withdraw

Creates an outgoing fiat transaction (for example, UAH payment to a banking card).

Remarks

Amount limits: Min: 1000 UAH; Max: 14500 UAH. After creation, 0xpay API will produce notifications according to status updates on your withdrawal.

Throws

XPayApiError if validation failed or not enough balance

Parameters

Name	Type	Description
body	Object	Request body
body.localId?	string	If was specified - error will be thrown if not unique
body.amount	string	Amount in decimal format
body.to	string	Destination card number
body.ticker	string	Currency ticker to withdraw(UAH)
body.meta?	string	Metadata to catch it back later with a notification
body.fee?	string	Precalculated fee. If not the specified – fee will be set automatically

Returns

Promise<string>

Withdraw id

---

withdrawFiatBatch

▸ withdrawFiatBatch(body): Promise<string>

Send fiat withdraws as batch

Splits large fiat transactions into several smaller payments and sends them to destination.

Remarks

Minimal limit: UAH 1000. After creation, 0xpay API will produce notifications according to status updates on your withdrawal.

Example: You want to send UAH 100,000 to a banking card. Normally, that'd require creating 7 different requests of ~UAH 14,500. With batched payments, your transaction amount will be automatically split into smaller portions: (13800 + 13611 + 14120 + 13900 + 13831 + 13822 + 8447 + 8469 = 100 000), then sent as a batch of payments.

Throws

XPayApiError if validation failed, not enough balance or not enough fee

Parameters

Name	Type	Description
body	Object	Request body
body.localId?	string	If was specified - error will be thrown if not unique
body.amount	string	Amount in decimal format
body.to	string	Destination card number
body.ticker	string	Currency ticker to withdraw(UAH)
body.meta?	string	Metadata to catch it back later with a notification
body.fee?	string	Precalculated fee. If not the specified – fee will be set automatically

Returns

Promise<string>

Withdraw batch id

---

getFiatWithdrawalFee

▸ getFiatWithdrawalFee(amount, ticker): Promise<string>

Get fiat withdraw fee

This method is used to get a fee for sending a desired amount of assets (ticker) on a chosen blockchain.

Throws

XPayApiError if validation failed

Parameters

Name	Type	Description
amount	string	Amount in decimal format
ticker	string	Currency ticker to withdraw(UAH)

Returns

Promise<string>

Withdraw fee

---

getAvailableFiatAssets

▸ getAvailableFiatAssets(): Promise<FiatAsset[]>

List all supported fiat assets

This method is used to fetch all available fiat assets of your merchant.

Returns

Promise<FiatAsset[]>

Array of all crypto fiat with their ticker, name and price

---

Crypto Invoices Methods

createCryptoInvoice

▸ createCryptoInvoice(body): Promise<string>

Create crypto invoice

Creates a webpage with your crypto invoice details on 0xpay.app domain, usable for a one-time payment.

Remarks

Payment limits: Min — 25 UAH, Max — 29999 UAH. Status Updates: After creation, every invoice update will produce an invoice notification.

Throws

XPayApiError if validation failed

Parameters

Name	Type	Description
body	Object	Request body
body.email?	string	User email
body.name	string	Descriptional field, name of your invoice. For example: "Order payment"
body.amount?	Object	Amount of invoice in decimal format with ticker and blockchain
body.amount.value	string	-
body.amount.ticker	string	-
body.duration?	number	The lifetime of crypto invoice in ms. Default: 72 hours
body.clientDuration?	number	The lifetime of crypto invoice in ms on the frontend. Default: duration / 2
body.toPendingImmediate?	boolean	Jump immediately to pending status, it can be useful if you want to skip fist "user prompt" status.
body.meta?	string	-

Returns

Promise<string>

Invoice url

---

Exchange Methods

getAvailableExchangeDirections

▸ getAvailableExchangeDirections(): Promise<ExchangeDirection[]>

Get available exchange directions

Returned available directions to exchange with price and limits.

Remarks

1.Get available directions for exchange through 0xpay (tickers). 2.Get 0xpay exchange limitations (min, max). 3.Find the way how you should format your swaps (precision, step).

Returns

Promise<ExchangeDirection[]>

Exchange directions

---

estimateExchange

▸ estimateExchange(body): Promise<EstimatedExchange>

Estimate exchange

Estimate your exchange for later creation.

Throws

XPayApiError if validation failed or not enough liquidity

Parameters

Name	Type	Description
body	Object	Request body
body.spendTicker	string	Asset that you want to spend from your balance
body.targetTicker	string	Asset that you want to receive to your balance
body.amount	string	Amount you want to spend or receive
body.side	"target" | "spend"	Your chosen direction, two possible values: target or spend
body.price?	string	Actual price of the pair

Returns

Promise<EstimatedExchange>

Estimated exchange

---

exchange

▸ exchange(body): Promise<string>

Exchange

Create an exchange of two assets.

Remark

Status Notifications: After the Success response, 0xpay API will produce notifications according to status updates on your exchange.

Throws

XPayApiError if validation failed, not enough liquidity, not enough balance or not enough fee

Parameters

Name	Type	Description
body	Object	Request body
body.amount	string	Amount you want to spend or receive
body.side	"target" | "spend"	Your chosen direction, two possible values: target or spend
body.meta	string	Metadata to catch it back later with a notification
body.spendTicker	string	Asset that you want to spend from your balance
body.fee	string	Precalculated exchange fee
body.targetTicker	string	Asset that you want to receive to your balance
body.localId	string	If was specified - error will be thrown if not unique
body.price	string	Actual price of the pair

Returns

Promise<string>

Exchange id

---

Fiat Invoices Methods

createFiatInvoice

▸ createFiatInvoice(body): Promise<string>

Create fiat invoice

Creates a webpage with your fiat invoice details on 0xpay.app domain, usable for a one-time payment. Currently, the only supported fiat ticker is UAH.

Remarks

Payment limits: Min — 25 UAH, Max — 29999 UAH. Status Updates: After creation, every invoice update will produce an invoice notification.

Throws

XPayApiError if validation failed

Parameters

Name	Type	Description
body	Object	Request body
body.email?	string	User email
body.name	string	Descriptional field, name of your invoice. For example: "Order payment"
body.amount?	Object	Amount of invoice in decimal format with ticker
body.amount.value	string	-
body.amount.ticker	string	-
body.toPendingImmediate?	boolean	Jump immediately to pending status, it can be useful if you want to skip fist "user prompt" status.
body.meta?	string	-

Returns

Promise<string>

Invoice url

---

Merchant Info Methods

getBalances

▸ getBalances(tickers): Promise<Balance[]>

Get balances info

This method is used to get merchants balances.

Throws

XPayApiError if validation failed

Parameters

Name	Type	Description
tickers	string[]	Tickers of balances to get

Returns

Promise<Balance[]>

Balances

---

Utilities Methods

validateWebhookRequest

▸ validateWebhookRequest(payload): void | { code: -1 | -2 | -3 ; description: string }

Validate Webhook Requests

Parameters

Name	Type	Description
payload	Object	Request required payload
payload.method	string	Request method
payload.url	string	Request url
payload.rawBody	string	Request raw unparsed body
payload.timestamp	string | number	-
payload.signature	string	Request signature header

Returns

void | { code: -1 | -2 | -3 ; description: string }

Code and description of validation error if failed

---

isIpnReplenish

▸ isIpnReplenish(ipn): ipn is IpnReplenish

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnReplenish

---

isIpnInvoice

▸ isIpnInvoice(ipn): ipn is IpnInvoice

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnInvoice

---

isIpnWithdraw

▸ isIpnWithdraw(ipn): ipn is IpnWithdraw

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnWithdraw

---

isIpnExchange

▸ isIpnExchange(ipn): ipn is IpnExchange

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnExchange

---

isIpnWithdrawBatch

▸ isIpnWithdrawBatch(ipn): ipn is IpnWithdrawBatch

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnWithdrawBatch

---

isIpnWithdrawExchangeCrypto

▸ isIpnWithdrawExchangeCrypto(ipn): ipn is IpnWithdrawExchangeCrypto

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnWithdrawExchangeCrypto

---

isIpnWithdrawExchangeFiat

▸ isIpnWithdrawExchangeFiat(ipn): ipn is IpnWithdrawExchangeFiat

Parameters

Name	Type
ipn	Ipn

Returns

ipn is IpnWithdrawExchangeFiat

---

Withdraw With Exchange Methods

estimateExchangeWithdrawalCrypto

▸ estimateExchangeWithdrawalCrypto(body): Promise<EstimatedExchangeWithdraw>

Estimate crypto withdrawal with exchange

Throws

XPayApiError if validation failed, not enough liquidity

Parameters

Name	Type	Description
body	Object	Request body
body.price?	string	Actual price of the pair
body.spendTicker	string	Asset that you want to spend from your balance
body.ticker	string	Ticker for withdrawal. Example: You want to spend (exchange) USDT and make a withdrawal in BTC (ticker value)
body.blockchain	Blockchain	Blockchain network for withdrawal
body.amount	string	Amount you want to spend or withdraw
body.side	"spend" | "withdraw"	Impacts amount field. When you want to withdraw the exact amount – specify the "withdraw" side. When you want to spend (exchange) an exact amount specify "exchange"
body.to?	string	Destination wallet address(if you fill it in, we'll check if the transaction might be an internal transfer)

Returns

Promise<EstimatedExchangeWithdraw>

Estimated crypto withdraw with exchange

---

estimateExchangeWithdrawalFiat

▸ estimateExchangeWithdrawalFiat(body): Promise<EstimatedExchangeWithdraw>

Estimate fiat withdrawal with exchange

Throws

XPayApiError if validation failed, not enough liquidity

Parameters

Name	Type	Description
body	Object	Request body
body.price?	string	Actual price of the pair
body.spendTicker	string	Asset that you want to spend from your balance
body.ticker	string	Ticker for withdrawal(only UAH available)
body.amount	string	Amount you want to spend or withdraw
body.side	"spend" | "withdraw"	Impacts amount field. When you want to withdraw the exact amount – specify the "withdraw" side. When you want to spend (exchange) an exact amount specify "exchange"

Returns

Promise<EstimatedExchangeWithdraw>

Estimated fiat withdraw with exchange

---

withdrawExchangeCrypto

▸ withdrawExchangeCrypto(body): Promise<string>

Crypto Withdraw With Exchange

Remark

Status Notifications: After the Success response, 0xpay API will produce notifications according to status updates on your exchange.

Throws

XPayApiError if validation failed, not enough liquidity, not enough balance or not enough fee

Parameters

Name	Type	Description
body	Object	Request body
body.amount	string	Amount you want to spend or withdraw
body.side	"spend" | "withdraw"	Impacts amount field. When you want to withdraw the exact amount – specify the "withdraw" side. When you want to spend (exchange) an exact amount specify "exchange"
body.localId	string	If was specified - error will be thrown if not unique
body.spendTicker	string	Asset that you want to spend from your balance
body.to	string	Destination wallet address
body.blockchain	Blockchain	Blockchain network for withdrawal
body.fee	string	Withdrawal fee
body.exchangeFee	string	Fee for exchange operation
body.ticker	string	Ticker for withdrawal. Example: You want to spend (exchange) USDT and make a withdrawal in BTC (ticker value)
body.meta	string	Metadata to catch it back later with a notification
body.price	string	Actual price of the pair

Returns

Promise<string>

Crypto withdrawal with exchange id

---

withdrawExchangeFiat

▸ withdrawExchangeFiat(body): Promise<void>

Fiat Withdraw With Exchange

Remark

Status Notifications: After the Success response, 0xpay API will produce notifications according to status updates on your exchange.

Throws

XPayApiError if validation failed, not enough liquidity, not enough balance, not enough fee

Parameters

Name	Type	Description
body	Object	Request body
body.amount	string	Amount you want to spend or withdraw
body.side	"spend" | "withdraw"	Impacts amount field. When you want to withdraw the exact amount – specify the "withdraw" side. When you want to spend (exchange) an exact amount specify "exchange"
body.meta	string	Metadata to catch it back later with a notification
body.spendTicker	string	Asset that you want to spend from your balance
body.to	string	Credit card number
body.fee	string	Withdrawal fee
body.exchangeFee	string	Fee for exchange operation
body.ticker	string	Ticker for withdrawal(only UAh available)
body.localId	string	If was specified - error will be thrown if not unique
body.price	string	Actual price of the pair

Returns

Promise<string>

Crypto withdrawal with exchange id