# Crypto Invoices

{% hint style="warning" %}
Every request listed on this page requires [authorization](https://docs.0xpay.app/public-api/endpoints/broken-reference) to be successfully completed. 
{% endhint %}

## Create crypto invoice (server-side)

<mark style="color:green;">`POST`</mark> `https://public.api.0xpay.app/merchants/invoices/crypto`

Returns a webpage URL on 0xpay.app domain for one-time payment.&#x20;

**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.&#x20;

**Status Updates:** Every invoice update will produce an [invoice notification](https://docs.0xpay.app/notifications#fiat-invoice).

#### Request Body

| Name                                   | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount                                 | object  | <p><code>value: string</code> – invoice amount you want to receive from user, this value is optional if <code>baseAmount</code> provided<br><code>ticker: string</code> – find values using "List all supported assets" request</p><p><code>blockchain: string</code> – available values you can find <a href="../../../general/networks-and-assets#blockchains">here</a> ("API value" column)<br><em>This field is optional, if not specified user will fill this fields on his demand</em></p>                                                                                                             |
| 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<mark style="color:red;">\*</mark> | string  | descriptional field, name of your invoice. For example: "Order payment"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| baseAmount                             | object  | <p>If specified <code>baseAmount.value</code> will be converted to the <code>amount</code> 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.</p><p><code>value: string</code> – invoice amount you want to receive from the user<br><code>ticker: string</code> – only fiat tickers supported now, available values: "UAH", "USD", "EUR"</p>                                                                                                                                                             |
| 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  | <p><code>ticker: string</code> - the currency to which we will try to exchange the received funds if <code>target.ticker == amount.ticker</code> no exchange will happen</p><p><code>address: string</code> - the address, to which we will withdraw invoice funds in the currency specified in <code>target.ticker</code> </p><p><code>blockchain: string</code> - network in which withdrawal will be made, this field is required if <code>target.address</code> is provided, available values you can find <a href="../../../general/networks-and-assets#blockchains">here</a> ("API value" column) </p> |
| redirectUrl                            | string  | URL to redirect user after payment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

{% tabs %}
{% tab title="200: OK Invoice URL generated succesfully" %}
{% code overflow="wrap" %}

```javascript
{
    "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
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Create crypto invoice via web form (client-side)

<mark style="color:green;">`POST`</mark> `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.&#x20;

**Status Updates:** Every invoice update will produce an [invoice notification](https://docs.0xpay.app/notifications#fiat-invoice).

#### 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<mark style="color:red;">\*</mark>       | string | descriptional field, name of your invoice. For example: "Order payment"                                                                                                                                                     |
| merchantId<mark style="color:red;">\*</mark> | 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 | <p>available values you can find <a href="../../../general/networks-and-assets#blockchains">here</a> ("API value" column)<br><em>This field is optional, if not specified user will fill this fields on his demand</em></p> |
| 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](https://docs.0xpay.app/general/networks-and-assets#blockchains) ("API value" column)  |
| redirectUrl                                  | string | URL to redirect user after payment                                                                                                                                                                                          |

{% tabs %}
{% tab title="200: OK Redirects to payment webpage URL" %}
Redirects to payment webpage URL
{% endtab %}
{% endtabs %}

**Crypto invoice web form example:**&#x20;

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

<mark style="color:blue;">`GET`</mark> `https://public.api.0xpay.app/merchants/invoices/crypto/:id`

This method is used to get invoice's data by it's id.&#x20;

#### Path Parameters

| Name                                 | Type   | Description                             |
| ------------------------------------ | ------ | --------------------------------------- |
| id<mark style="color:red;">\*</mark> | string | internal identificator of 0xpay invoice |

{% tabs %}
{% tab title="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)

{% tabs %}
{% tab title="Overpaid Invoice" %}
{% code overflow="wrap" %}

```json
{
    "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"
}
```

{% endcode %}
{% endtab %}

{% tab title="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": "dmytro@gmail.com",
    "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"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Close invoice

<mark style="color:green;">`POST`</mark> `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

{% tabs %}
{% tab title="200: OK invoice id" %}

{% endtab %}
{% endtabs %}