ZixiPay Merchant API Version 2
Merchant integration and payment acceptance
ZixiPay Merchant API alllows accepting crypto payments with an automated payment notification callback function. Merchant API could be integrated and utilized in all kind of use cases such as invoice payments, wallet services, e-commerce, exchange services, etc.
- All General API Information, Endpoints Limit and Endpoints security are valid and applies.
- All the merchant API endpoints are accessible only if your ZixiPay wallet is verified and the Merchant Setting are set and active.
Merchant Settings
How to set up and activate the ZixiPay Merchant API:
- Login to your ZixiPay Wallet at https://zixipay.com/login
- Go to the
Merchants
menu. If your wallet account is not verified, you willl be asked to verify your account. Website URL
is the website the payment acceptance service is going to be used for.Category
is the most relevant business category the website fits in.IPN Callback URL
needs to be set only if a callback payment notification is required for each payment. If left empty, no callback will be done.IPN callback hash key
is the key to be used to sign the payment callback withHMAC-SHA256
. If left empty, callback will not be signed.Automatic exchange to USDZ
if enabled, all incoming payments in other currencies will be automatically exchanged to and deposited in USDZ.
API Endpoints
Merchant API Endpoints
getpaymentwallet
POST /apiv2/getpaymentwallet
Get payment wallet address. This endpoint returns a new wallet address everytime it is called.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
currency | string | YES | Any of the supported currencies (USDZ, EURZ, LTC, BTC, ETH or USDT) |
ref | string | YES | A reference tag to this payment wallet (depeneding on the usage this could be an invoice number, account number, userid, username, email address or any other kind of unique reference in your platform) |
uid | string | YES | ZixiPay User ID |
ts | number | YES | Unix time |
sig | string | YES | HMAC-SHA256 signature |
IMPORTANT: Calls to this endpoint with the same ref
tag would return the same wallet address. This is useful when you need to have persistant wallet address for each client/account in your platform.
Response: (Example)
{
"result":"ok",
"payload":[
{
"name":"Tether TRC20", // currency name
"code":"USDT", // currency symbol
"address":"TH53ejapLDKDFxxqP2RREfxCNtW26gFKeb", // wallet address
"qr-code":"https://qrg.zixipay.com/api/qr.php?data=TH53ejapLDKDFxxqP2RREfxCNtW26gFKeb", // QR-Code of the address
"confirm":20 // number of confirmations required
},
{
"name":"Tether ERC20",
"code":"USDT",
"address":"0x0ed8991afc868c45ffbcd4afdf7ebc273cf38ed2",
"qr-code":"https://qrg.zixipay.com/api/qr.php?data=0x0ed8991afc868c45ffbcd4afdf7ebc273cf38ed2",
"confirm":3
},
{
"name":"Tether OMNI",
"code":"USDT",
"address":"1PkYiGCF3zVif5vm1ogXYuvtGaK3p7qLgK",
"qr-code":"https://qrg.zixipay.com/api/qr.php?data=1PkYiGCF3zVif5vm1ogXYuvtGaK3p7qLgK",
"confirm":1
}
]
}
QR-Code: Calls to this endpoint returns a URL for the qr-code
of the wallet address which could be easily used in the <img>
HTML tag as its src
.
IPN Callback Parameters
If the IPN Callback URL is set in the Merchant settings, upon receiving funds in any of the wallet addresses generated by the getpaymentwallet
endpoint, an HTTPS POST will be made to the Callback URL with the following parameters:
Parameters:
Name | Type | Description |
---|---|---|
ref | string | reference tag to this payment wallet |
wallet | string | receiving wallet address that has been generated using getpaymentwallet API endpoint. |
amount | number | amount of the incoming payment |
fee | number | processing fee for auto-exhange, callback or both. Will be zero if no fees was applicable. |
currency | string | any of the supported currencies (USDZ, EURZ, LTC, BTC, ETH or USDT) |
exchange* | boolean | 0: if auto-echange to USDZ has NOT been done. 1: if auto-exchange to USDZ has been done. |
xamount* | number | actual incoming payment amount if auto-exchange to USDZ has been done, null otherwise. |
xcurrency* | string | actual incoming currency if auto-exchange to USDZ has been done, null otherwise. |
xrate* | number | applied exchange rate if auto-exchange to USDZ has been done, null otherwise. |
txid | string | blockchain transaction id |
zxid | string | ZixiPay transaction id |
time | number | Transaction time (Unix time) |
sig | string | HMAC-SHA256 signature (will be null if IPN callback hash key has not been set in the Merchant Settings) |
* exchange, xamount, xcurrency and xrate are used when Automatic exchange to USDZ
is activated in the Merchant Settings.
IMPORTANT: If the receiving end is behind a firewall, ZixiPay’s IP address (185.17.146.83) and TCP port 443 needs to be permitted to pass through.
IMPORTANT: Callback is HTTPS only, so SSL needs to be enabled and valid on the receiving end.