ZixiPay Merchant API Version 2

Merchant Integration and Payment Acceptance

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.
ZixiPay Merchant API provides two methods of integration with the client’s platfrom:
- Total integration: using ZixiPay as Wallet as a Service to fully integrate with your own platfrom. The best use case for this option is giving your users their own dedicated and permanent wallet addresses on your platfrom (getpaymentwallet endpoint)
- Invoicing: issuing invoices and letting ZixiPay handle the UI and the payment (createinvoice endpoint) (INVOICE SAMPLE)

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.
Logo URL is the URL to the merchant’s logo file to be used in the invoices.
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 with HMAC-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. This option completely protects the merchant from crypto price fluctuation.

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, TRX, USDC 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
    }
  ]
}

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.

createinvoice

POST /apiv2/createinvoice

Create a payment invoice.

Parameters:

Name	Type	Mandatory	Description
amount	number	YES	Invoice amount
currency	string	YES	Any of the supported currencies (USDZ, EURZ, LTC, BTC, ETH, TRX, USDC or USDT)
multicurrency	binary	NO	Can the invoice be paid by any of the supported cryptocurrencies? 0: Disabled (default). Invoice can only be paid by the invoice currency 1: Enabled. Available when the invoice currency is USDZ
validity	number	NO	The invoice validity in minutes. 0 (default) means the invoice will be valid for 7 days
ref	string	YES	A reference tag to this invoice (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

Calls to this endpoint returns a unique invoice_id plus the invoice URL and URL of the QR-Code of the invoice URL will returned as well.

IMPORTANT: Invoices will be cancelled automatically when the validity period is expired. Cancelled invoices will be deleted after one day.

Response: (Example)

{
  "result":"ok",
  "payload":{
    "invoice_id":"RC38OQ2NXJQ77GSSU7R728BUHSOLNK",
    "invoice_url":"https://zixipay.com/invoice?id=RC38OQ2NXJQ77GSSU7R728BUHSOLNK",
    "invoice_url_qrcode":"https://qrg.zixipay.com/api/qr.php?data=https://zixipay.com/invoice?id=RC38OQ2NXJQ77GSSU7R728BUHSOLNK"
  }
}

cancelinvoice

POST /apiv2/cancelinvoice

Cancel a payment invoice.

Parameters:

Name	Type	Mandatory	Description
invoice_id	string	YES	The `invoice_id` of the invoice to be cancelled
uid	string	YES	ZixiPay User ID
ts	number	YES	Unix time
sig	string	YES	HMAC-SHA256 signature

IMPORTANT: Cancelled invoices will be deleted after one week.

Response: (Example)

{
  "result":"ok",
  "payload":"invoice cancelled successfully"
}

getinvoice

POST /apiv2/getinvoice

Get an invoice details.

Parameters:

Name	Type	Mandatory	Description
invoice_id	string	YES	The `invoice_id` of the invoice
uid	string	YES	ZixiPay User ID
ts	number	YES	Unix time
sig	string	YES	HMAC-SHA256 signature

Response: (Example)

{
  "result":"ok",
  "payload":{
    "invoice_id":"RC38OQ2NXJQ77GSSU7R728BUHSOLNK",
    "amount":"0.40000000",
    "currency":"BTC",
    "date":"2021-11-20 10:14:26",
    "status":"paid",
    "ref":"some1random2ref",
    "accept_multi":"0",
    "validity":"1000"
  }
}

listinvoices

POST /apiv2/listinvoices

Get all the invoices. Optional filters could be used to narrow down the search.

Parameters:

Name	Type	Mandatory	Description
invoice_id	string	NO	The `invoice_id` of the invoice
ref	string	NO	Reference tag to the invoice
datefrom	string	NO	From this issue date (YYYY-MM-DD)
dateto	string	NO	To this issue date (YYYY-MM-DD)
currency	string	NO	Invoice currency (USDZ, EURZ, LTC, BTC, ETH, TRX, USDC or USDT)
status	string	NO	Invoice status (paid, pending or cancelled)
uid	string	YES	ZixiPay User ID
ts	number	YES	Unix time
sig	string	YES	HMAC-SHA256 signature

Response: (Example)

{
  "result":"ok",
  "payload":{
    "records":1,
    "invoices":[
      {
        "invoice_id":"RC38OQ2NXJQ77GSSU7R728BUHSOLNK",
        "amount":"0.40000000",
        "currency":"BTC",
        "date":"2021-11-20 10:14:26",
        "status":"paid",
        "ref":"some1random2ref",
        "accept_multi":"0",
        "validity":"1000"
      }
    ]
  }
}

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 or invoices created by the createinvoice endpoint, an HTTPS POST will be made to the Callback URL with the following parameters in urlencoded format.

Parameters:

Name	Type	Description
ref	string	reference tag to this payment wallet
invoice	string	receiving `invoice_id` if this an invoive payment, null if it is not an invoice payment.
wallet	string	receiving wallet address.
amount	number	amount of the incoming payment
fee	number	merchant API processing fee + the exhange fee if the auto-exchange to USDZ has been enabled.
currency	string	any of the supported currencies (USDZ, EURZ, LTC, BTC, ETH, TRX, USDC or USDT)
exchange^*	binary	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 txid/hash
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 or this was an invoice payment with enabled multicurrency.

IMPORTANT 1: If the receiving end is behind a firewall, ZixiPay’s IP addresses and TCP port 443 needs to be permitted to pass through.

IMPORTANT 2: Callback is HTTPS only, so SSL needs to be enabled and the SSL certificate has to be valid on the receiving end.

IMPORTANT 3: Callback isn’t a real-time service, it might take a few minutes for each incoming payment callback to hit the receiving endpoint.

IMPORTANT 4: Each Callback waits a maximum of 5 seconds to receive an HTTP 200 response or it is considered failed. So the code that handles the callback on the receiving end has to be fast and quick.

IMPORTANT 5: If Callback doesn’t receive an HTTP 200 response, for whatever reason (SSL handshake validation, network problem, timeout, server error, etc), then ZixiPay will retry delivery of the IPN message up to an additional 10 times.

VERY IMPORTANT: If there was an error/technical problem during IPN callback, our system would try up to 10 times until it is done successfully and nevertheless there is a tiny chance your system receives more than one IPN callback for the same transaction. The IPN callback handler must always watch for duplicate callbacks by checking zxid (ZixiPay transaction id) or a method of your choice to avoid double deposits/credits on your side.

Sample code has been provided to simulate the call back in the samples folder