Crypto Invoices

Every request listed on this page requires authorization to be successfully completed.

Create crypto invoice (server-side)

POST https://public.api.0xpay.app/merchants/invoices/crypto

Returns a webpage URL on 0xpay.app domain for one-time payment.

Important note: crypto invoices will expire after 72 hours. However, the time displayed on payment page is 48 hours. Additional time is given to lower the risk of expiration in case of network delays.

Status Updates: Every invoice update will produce an invoice notification.

Request Body

Name	Type	Description
amount	object	value: string – invoice amount you want to receive from user, this value is optional if baseAmount provided ticker: string – find values using "List all supported assets" request blockchain: string – available values you can find here ("API value" column) This field is optional, if not specified user will fill this fields on his demand
description	string	descriptional field, will be shown to the user on invoice page
meta	string	your metadata that will be passed along to you later with a notification
name*	string	descriptional field, name of your invoice. For example: "Order payment"
baseAmount	object	If specified baseAmount.value will be converted to the amount after a user clicks the "Continue" button on the invoice page. Useful when you want to bill your user with fiat assets but pay an invoice in crypto. value: string – invoice amount you want to receive from the user ticker: string – only fiat tickers supported now, available values: "UAH", "USD", "EUR"
duration	number	the lifetime of crypto invoice in ms. Default: 72 hours
clientDuration	number	the lifetime of crypto invoice in ms on the frontend. Default: duration / 2
toPendingImmediate	boolean	jump immediately to pending status, it can be useful if you want to skip fist "user prompt" status.
email	string	user email
target	object	ticker: string - the currency to which we will try to exchange the received funds if target.ticker == amount.ticker no exchange will happen address: string - the address, to which we will withdraw invoice funds in the currency specified in target.ticker blockchain: string - network in which withdrawal will be made, this field is required if target.address is provided, available values you can find here ("API value" column)
redirectUrl	string	URL to redirect user after payment

200: OK Invoice URL generated succesfully

{
    "id": "123e4567-e89b-12d3-a456-426614174000" //internal ID has been assigned to the invoice
     "url": "https://my.0xpay.app/invoices/crypto/123e4567-e89b-12d3-a456-426614174000" // feel free to redirect user to this URL for payment
}

Create crypto invoice via web form (client-side)

POST https://public.api.0xpay.app/merchants/invoices/crypto/form

Creates a cryptocurrency invoice using parameters from your HTML form defined defined parameters and redirects users to 0xpay URL for payment. on 0xpay.app domain for one-time payment. Instead of authorizing a request, just pass your merchantID along with other parameters.

Expiration time: 72 hours for crypto. However, the time displayed on payment page is 48 hours. Additional time is given to lower the risk of expiration in case of network delays.

Status Updates: Every invoice update will produce an invoice notification.

Request Body

Name	Type	Description
baseValue	string	If specified will be converted to the value after a user clicks the "Continue" button on the invoice page. Useful when you want to bill your user with fiat assets but pay an invoice in crypto.
description	string	descriptional field, will be shown to the user on invoice page
meta	string	your metadata that will be passed along to you later with a notification
name*	string	descriptional field, name of your invoice. For example: "Order payment"
merchantId*	string	internal id of your 0xpay merchant account
value	string	invoice amount you want to receive from the user, this value is optional if baseValue provided
ticker	string	find values using "List all supported assets" request
baseTicker	string	only fiat tickers are supported now, available values: "UAH", "USD", "EUR"
blockchain	string	available values you can find here ("API value" column) This field is optional, if not specified user will fill this fields on his demand
targetTicker	string	the currency to which we will try to exchange the received funds if targetTicker == ticker no exchange will happen
targetAddress	string	the address, to which we will withdraw invoice funds in the currency specified in targetTicker
targetBlockchain	string	network in which withdrawal will be made, this field is required if targetAddress is provided, available values you can find here ("API value" column)
redirectUrl	string	URL to redirect user after payment

200: OK Redirects to payment webpage URL

Redirects to payment webpage URL

Crypto invoice web form example:

<!DOCTYPE html>
<html lang="en">
  <body>
    <script src="index.js"></script>
    <form method="post" action="https://public.api.0xpay.app/merchants/invoices/crypto/form">
      <input type="text" name="merchantId" value="806dbc17-d371-4179-8718-b208be848180" /> <br />
      <input type="number" name="value" value="0.01"> // optional value, can be hidden
      <input type="text" name="ticker" value="BTC"> // optional input, cn be hidden
      <input type="text" name="blockchain" value="BITCOIN"> // optional input, cn be hidden
      <input type="text" name="meta" value="user-id" /> <br />
      <input type="text" name="name" value="invoice name" /> <br />
      
      <!-- auto-targeting -->
      <!-- 
        here is, after depositing to invoice, 
        0.1 BTC will be exchanged for USDT and after this withdraw 
        to the address T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb in the TRON network
      -->
      <input type="text" name="targetTicker" value="USDT" /> // optional <br />
      <input type="text" name="targetAddress" value="T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb" /> // optional <br />
      <input type="text" name="targetBlockchain" value="TRON" /> // optional <br />
      <button type="submit">Pay!</button>
    </form>
  </body>
</html>

Find crypto invoice details by ID

GET https://public.api.0xpay.app/merchants/invoices/crypto/:id

This method is used to get invoice's data by it's id.

Path Parameters

Name	Type	Description
id*	string	internal identificator of 0xpay invoice

200: OK Examples of invoices:

When fetching an invoice, it can come with different status that can be equal to: | 1. CREATED 2. REGISTERED (address allocated) 3. PENDING (1 deposit at least catched) 4. PAID 5. EXPIRED (ran out of timeout)

Overpaid Invoice

{
    "id": "eb929d63-5f05-4d9f-9d3e-854384009ef1", //invoice id
    "name": "Order payment",
    "merchantId": "asdasd-asdasd-asdasd-asdad" 
    "company": {
        "name": "CompanyName",
        "url": "example.com"
    },
    "amount": {    //amount of assets to be paid via invoice
        "value": "0.4",
        "ticker": "BTC",
        "blockchain": "BITCOIN"
    },
    "fee": "0.0025", //only exists if status is PAID
    "paidAmount": "0.5", // amount received to the invoice. Note: paidAmount can be less then amount in case of underpayment and more then amount in case of overpayment
    "status": "PAID", //status of the invoice
    "createdAt": 1666091014270, //time of invoice creation
    "expiredAt": 1666350193695, //time of invoice expiration, exists after status changes to "REGISTERED"
    "meta": "i-want-to-know-about-that"
}

Invoice with base amount

{
    "id": "c1493562-abf9-4817-8d95-1fe3f10c1419",
    "name": "Invoice 2",
    "address": "0xc6f62a8b6a8448edeaf664bbf78845db5d0b01ce",
    "expiredAt": 1668761762903,
    "clientExpiredAt": 1668632162903,
    "createdAt": 1668502552573,
    "price": "44286.20000000000120128089",
    "paidPrice": "44286.2",
    "email": "[e-mail]",
    "company": {
        "name": "asd",
        "url": "https://asd.com"
    },
    "status": "PAID",
    "fee": "0.000225803975053177",
    "paidAmount": "0.0225804",
    "baseAmount": {
        "value": "1000",
        "ticker": "UAH"
    },
    "amount": {
        "ticker": "ETH",
        "blockchain": "ETHEREUM",
        "value": "0.022580397505317683"
    }
}

Close invoice

POST https://public.api.0xpay.app/merchants/invoices/crypto/:id/close

Close invoice on-demand. For example: the user paid half of the invoice amount and you want to close it before the full payment

The invoice will be immediately transferred to the "PAID" status

200: OK invoice id