Submit Invoice

Response data

🚧

key permissions

The api key permissions should include these settings in order to be able to create the invoice:

• Account Info - both get account fee and edit account info should be enabled
• Orders - both get orders and create/cancel orders should be enabled

The api key permissions can be checked through key permissions endpoint, where it should have read and write flags set to 1 for these options:

• settings
• account
• orders

🚧

payment addresses

All the payments are done against user's merchant sub account, before being able to accept the deposits the user should generate deposit addresses for currencies that expects to be paid with. This can be done either through UI by going on deposit page, or through api by calling deposit address endpoint

📘

webhook

Webhook must be an endpoint that would accept POST requests with JSON body. In request body the following invoice fields will be send:

• id: string
• type: string // invoice type
• orderId: string
• status: string // COMPLETED or EXPIRED
• amount: float
• currency: string
• t: int // timestamp
• invoices: array of object // if expired no item will be included, if paid only the paid invoice
• payment: object // present only in case of success
  • txid: string // transaction hash
  • amount: float // amount in payable ccy
  • currency: string
  • method: string // method of deposit. For an up-to-date mapping of methods and their respective currencies see: https://api-pub.bitfinex.com//v2/conf/pub:map:tx:method [[[METHOD,[CURRENCY]]...]]
  • status: 'COMPLETED'
  • confirmations: int
  • created_at: 'YYYY-MM-DD hh:mm:ss'
  • updated_at: 'YYYY-MM-DD hh:mm:ss'
  • depositId: int // optional, deposit id linked to payment, present when payment is done through wallet deposit
  • ledgerId: int // optional, ledger id linked to payment, present when payment is realized through "Instant Payment",
  • forceCompleted: boolean // optional, flag indicating that invoice is manually marked as completed
  • amountDiff: string // optional, paid amount difference from deposited amount and expected amount in invoice
• additionalPayments: array // optional, additional payments, applied when invoice has partial underpaid payments, it's basically array of objects with same structure as payment field

Example request:

POST https://example.com/api/v3/order/order123
{
  "id": "a6761c8b-468f-40ad-a522-cc5e41c39757",
  "type": "ECOMMERCE",
  "orderId": "order123",
  "status": "COMPLETED",
  "amount": 2.5,
  "currency": "USD",
  "t": 1612460165497,
  "invoices": [
    {
      "amount": 0.00006262,
      "currency": "BTC",
      "payCurrency": "BTC",
      "poolCurrency": "BTC",
      "address": "bc1qyegkyyk656vrqp0pzyg8p4yy9xlqfhxlrg0jtf"
    }
  ],
  "payment": {
    "txid": "5119b4caaad1af22bebb2373995d8ecd8dfb23cc1971d0347aaa516b4e0f3e3a",
    "amount": 0.00006262,
    "currency": "BTC",
    "method": "BITCOIN",
    "status": "COMPLETED",
    "confirmations": 6,
    "created_at": "2021-01-06 21:16:28",
    "updated_at": "2021-01-06 21:16:28",
    "depositId": 1357996
  }
}

🚧

webhook

Warning! Webhook will be called only once and in case of failure it's not triggered again, due to that case merchants can also use /v2/auth/r/ext/pay/invoices endpoint to query the invoice states.

📘

invoices: { ext: ... }

Ext field contains additional data related to payment. In case of lighting network (LNX) payment it should look like this: { "hash": string, "payment_request": string, "node_pub": string }.

📘

invoices: { poolCurrency: ... }

Pool currency represents the underlying blockchain used by payable currency, e.g. in case of UST-ETH which is an ERC-20 token poolCurrency is ETH.

📘

flags

Invoice might have flags that are automatically added depending on data. Currently supported flags are:

• ip:prohibited - added when customer's ip belongs to a prohibited jurisdiction

Ratelimit: 90 req/min