Invoices

Invoices are payment requests addressed to specific buyers or payers. Invoice has a unique receiving address and optional fixed price, typically denominated in fiat currency. It also has a crypto equivalent price, calculated by Uniwire, with an optional expiration time. If you need just an address you can leave amount blank.

List Invoices

This endpoint retrieves all invoices. Endpoint uses pagination and returns 25 invoices per page. Invoices are sorted by creation time in descending order.

HTTP Request

GET /v1/invoices/

Query Parameters

Parameter	Default	Description
p	None	Page number.
txid	None	Filter invoices by txid.
address	None	Filter invoices by receiving address.
status	None	Filter invoices by status. Available values: "new", "pending", "complete", "expired".
profile_id	None	Filter invoices by Profile ID.

python

invoices = uniwire_api_request('/v1/invoices/')

javascript

uniwire_api_request('/v1/invoices/').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

php

$response = cryptochill_api_request('invoices/');
var_dump($response);

The above command returns JSON structured like this:

{
  "pagination": {
    "num_pages": 1,
    "count": 12,
    "page": 1,
    "next_page": null,
    "previous_page": null,
    "per_page": 25
  },
  "result": [
    {
      "id": "123",
      "kind": "BTC",
      "created_at": "2019-01-23T14:31:20.750500+00:00",
      "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
      "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
      "lightning": null,
      "network": "mainnet",
      "status": "paid",
      "amount": {
        "requested": {
          "amount": "99.00000000",
          "currency": "USD"
        },
        "invoiced": {
          "amount": "0.02732120",
          "currency": "BTC",
          "rate_usd": "3624.886995160658"
        },
        "paid": {
          "amount": "0.02731120",
          "currency": "BTC"
        },
        "paid_total": {
          // If custom fee is used
          "amount": "0.02732120",
          "currency": "BTC"
        }
      },
      "custom_fee": {
        "amount": "0.00001",
        "currency": "BTC"
      },
      "min_confirmations": null,
      "zero_conf_enabled": null,
      "notes": null,
      "passthrough": "{\"user_id\":1}"
    }
  ]
}

Get Invoice

This endpoint retrieves a specific invoice.

HTTP Request

GET /v1/invoices/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the invoice to retrieve.

python

invoice = uniwire_api_request('/v1/invoices/42dbee1d-8659-44c3-aab2-6e414c5825a5/')

javascript

uniwire_api_request('/v1/invoices/42dbee1d-8659-44c3-aab2-6e414c5825a5/').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
  "result": {
    "id": "42dbee1d-8659-44c3-aab2-6e414c5825a5",
    "kind": "BTC",
    "created_at": "2019-02-08T01:06:11.799601+00:00",
    "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
    "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
    "lightning": null,
    "network": "mainnet",
    "status": "new",
    "amount": {
      "requested": {
        "amount": "10.00",
        "currency": "USD"
      },
      "invoiced": {
        "amount": "0.00292111",
        "currency": "BTC"
      },
      "paid": null
    },
    "custom_fee": null,
    "min_confirmations": null,
    "zero_conf_enabled": null,
    "notes": null,
    "passthrough": "{\"user_id\": 123}",
    "transactions": []
  }
}

Create Invoice

This endpoint creates an invoice. Response is identical to Get Invoice endpoint response.

TIP

Important:

• Create invoices and reusable addresses only after the user explicitly specifies the blockchain they intend to use for the deposit. Avoid creating addresses for all chains at user signup.
• For reusable addresses create invoice/address only when user has clearly indicated which chain he will deposit on. Do not create all addresses on user signup.
• Reuse the same address for deposits of tokens on the same blockchain.
• All transactions will have USD quotes for transaction amount regardless of invoice specification.

HTTP Request

POST /v1/invoices/

Payload Parameters

Parameter	Description	Required
profile_id	Profile ID to use for settings, callback and wallet address generation.	Yes
amount	Payment amount as decimal string. Leave amount blank for reusable addresses. Only Transactions Callbacks will be sent if no amount is specified while creating invoice.	No
currency	Currency for the specified payment amount. Available values: USD, USDT, BTC, LTC, ETH, TRX, SOL, POL, XRP, DOGE, TUSD, USDC, PAX, GUSD, BUSD, WBNB, SAND, DAI, SHIB, L-BTC, L-USDT, EUR, GBP, AUD, CAD, CHF, ZAR, NOK, NZD, MXN, CLP, KRW, JPY, PLN, DKK, SEK, ARS, KES.	Yes
kind	Invoice kind and chain. It is not necessary to create dedicated addresses for tokens. For example use kind=ETH for any ETH and ETH token deposits like USDT, etc. Same address can be reused unlimited amount of times for any main asset and token deposits. Available Values	Yes
passthrough	String. Meta-data you wish to store with the invoice. Will be sent alongside all callbacks associated with the invoice.	No
fee_amount	Custom fee amount in same currency as specified in kind field that will be deducted from paid amount response.	No
min_confirmations	Minimum confirmations required to change status to "confirmed" and trigger callback. Available values: 1-5. Default: Profile min_confirmations setting value.	No
notes	Can be product or service name or any other notes. Visible in dashboard and in public invoice link.	No
zero_conf_enabled	Boolean. Enables instant zero confirmation deposits. Available for Bitcoin On-chain only. Default: False.	No
exchange_rate_limit	Object. Enables comparison and validation between provided exchange rates and Uniwire exchange rates. Rejects request if difference is greater than what is specified in allowed_difference field. Full specification of exchange_rate_limit object see in the table below.	No

exchange_rate_limit object parameters

Parameter	Description	Required
pair	String. Colon separated crypto to fiat pair name. Example: "BTC:USD".	Yes
exchange_rate	Decimal. Your exchange rate.	Yes
allowed_difference	Decimal. Allowed difference. Example for 5% use 0.05.	Yes

python

import json

payload = {
    "amount": "10",
    "currency": "USD",
    "kind": "BTC",
    "profile_id": "456",
    "passthrough": json.dumps({"user_id": 123})
}
invoice = uniwire_api_request('/v1/invoices/', payload, 'POST')
print(json.dumps(invoices, indent=2))

javascript

var payload = {
  "amount": "10",
  "currency": "USD",
  "kind": "BTC",
  "profile_id": "456",
  "passthrough": JSON.stringify({"user_id": 123})
}
uniwire_api_request('/v1/invoices/', payload, 'POST').then(function(response) {
  console.log(response);
}).catch(function(error) {
  console.log(error);
});

php

$response = cryptochill_api_request('invoices/', $payload, 'POST');
var_dump($response);

JSON response for Create Invoice endpoint:

{
  "result": {
    "id": "42dbee1d-8659-44c3-aab2-6e414c5825a5",
    "kind": "BTC",
    "created_at": "2019-02-08T01:06:11.799601+00:00",
    "profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
    "address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
    "lightning": null,
    "network": "mainnet",
    "status": "new",
    "amount": {
      "requested": {
        "amount": "10.00",
        "currency": "USD"
      },
      "invoiced": {
        "amount": "0.00292111",
        "currency": "BTC"
      },
      "paid": {
        "amount": "0.00292111",
        "currency": "BTC"
      }
    },
    "custom_fee": null,
    "min_confirmations": null,
    "zero_conf_enabled": null,
    "notes": null,
    "passthrough": "{\"user_id\": 123}",
    "transactions": [
      {
        "id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
        "kind": "BTC",
        "txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
        "confirmations": 6,
        "amount": "0.00292111",
        "created_at": "2019-02-08T01:08:11.799601+00:00"
      }
    ]
  }
}

Lightning Network

If you specify BTC_LIGHTNING or BTC_LIGHTNING_LNURL for invoice kind field then address won't be generated, instead lightning key will be present in response having sub-keys: payment_request , payment_hash, lnurl, lnurl_invoice_id:

Parameter	Description
payment_request	Payment request string required for client to pay lightning network payment request.
payment_hash	Unique ID of payment request.
lnurl	Unique ID of LNURL.
lnurl_invoice_id	LNURL invoice ID.

JSON response for Create Invoice with kind=lightning endpoint:

{
  "result": {
    ...
    "kind": "lightning",
    "lightning": {
      "payment_request": "...",
      "payment_hash": "...",
      "lnurl": null,
      "lnurl_invoice_id": null
    },
    ...
  }
}

Expiration

Payment requests are valid for exact amount specified in payload data and will expire after time set in Profile Details -> Invoice Expiration or as set per specific invoice.

LNURL support

To create an LNURL invoice use kind BTC_LIGHTNING_LNURL. LNURL invoices never expire and return lightning.lnurl instead of a payment_request.

How LNURL works:

1. Create an LNURL invoice with kind BTC_LIGHTNING_LNURL
2. Display the returned lightning.lnurl as a QR code to your customer
3. When the customer scans the QR code and initiates payment, their wallet sends a callback to our system
4. Our system automatically creates a new Lightning invoice (kind BTC_LIGHTNING) for the payment
5. The new Lightning invoice appears as a separate invoice entry with lnurl_invoice_id field referencing the original LNURL invoice ID

Ripple

All our invoices on Ripple network uses destination tag. Account address and destination tag are combined as single field separated by colon. Ripple X-address format is also supported.

For Ripple invoices you will receive extra x_address field:

Parameter	Description
address	Combined address of account address and destination tag.
x_address	Ripple X-address format.

JSON response for Create Invoice endpoint Ripple:

{
  "result": {
    ...
    "address": "rQ9zXuCaJfrW1tNiGk9t57GyKB5dmNHdof:1402",
    "x_address": "XVmrpsnjrbc2wamZxxbkSnEn3hGXDRpUzKCnh54gcHPYdsm",
    ...
  }
}

Liquid Network

Liquid Network is a sidechain-based settlement network for traders & exchanges. Liquid enables faster, more confidential Bitcoin and Tether transactions, and the issuance of digital assets. Read more on Liquid.net

For Liquid invoices you will receive extra public_address field:

Parameter	Description
address	Liquid confidential address (default).
public_address	Liquid non-confidential address.

JSON response for Create Invoice endpoint for any of currencies on Liquid Network:

{
  "result": {
    ...
    "address": "VJLJhm3NhyvgnahxMNkV2BfaLktKSwJWxh96qDNYjuxzuqqGzW7GWUJNiJEstVdzVbzzXix1j9Kgu94k",
    "public_address": "GvQH26UTNZacuUf3mBXTbBmcnQ24u3fdkm",
    ...
  }
}

Liquid Confidential Transactions

Liquid uses Confidential Transactions, which hides the amounts and asset types within transactions from all third parties. This information is only known by the parties involved in the transaction and other third parties they designate. Liquid transactions use confidential addresses that include a public blinding key and a base address. Only the receiver alone can decrypt the amount sent in a transaction. The receiver can share the private blinding key with any third party in order for that party to be able to validate the amount and asset type.

Invoice Callbacks

Callbacks provide same exact response format as in Get Invoice API endpoint in result field plus three extra fields specified in Callbacks Documentation.

Only Transactions Callbacks will be sent if no amount is specified while creating invoice.

You can view history of callbacks (if any) in Uniwire in Invoice detail view.

Invoice Callback Statuses

Status	Description
invoice_pending	Sum of all incoming transactions matches requested amount (0 confirmations).
invoice_confirmed	Sum of all incoming transactions matches requested amount (at last 1 confirmations).
invoice_complete	Sum of all incoming transactions matches requested amount (6+ confirmations).
invoice_incomplete	Transaction(s) were made, but amount is less than requested in the invoice. Requires manual handling.

Public Link

All invoices can be accessed on a Public link using address format: https://uniwire.com/invoice/INVOICE_ID/. Where INVOICE_ID can be unchanged invoice ID as returned in API call or it can also be Invoice ID value, but with all dashes removed and all letters in uppercase.

If you would like to have an invoice URL with fiat price being renewed when link is opened, you can add renew/ suffix in the end of the URL: https://uniwire.com/invoice/INVOICE_ID/renew/. This is useful when sending an invoice to a client and you want the invoice to reflect the most up-to-date fiat price rates. Additionally, the countdown will only start once the client opens the invoice link.

To redirect users to another page after successful payment use ?success_url=URL_HERE URL parameter.

QR Code

For a QR image that represents invoice address and metadata, you can use following image endpoint:

https://uniwire.com/sdk/v1/invoices/qr/INVOICE_ID/

Add ?full=1 to URL if you'd like to have QR code with an address and amount (this format is supported by limited number of wallets).