Submit Invoice

Submit an invoice for payment

Response Fields

TermTypeDescription
IDstringUnique invoice identifier
TintTimestamp when invoice is created
TYPEstringInvoice type, currently supported ECOMMERCE and POS
DURATIONintInvoice expire time in seconds
AMOUNTfloatInvoice amount in currency
CURRENCYstringInvoice currency
ORDER_IDstringReference order identifier in merchant's platform
PAY_CURRENCIESarray of stringsCurrencies in which invoice accepts the payments
WEBHOOKstringOptional, the endpoint that will be called once the payment is completed/expired
REDIRECT_URLstringOptional, merchant redirect URL, this one is used in UI to redirect customer to merchant's site once the payment is completed/expired
STATUSstringPayment status, should be one of: CREATED, PENDING, COMPLETED, EXPIRED
CUSTOMER_INFOobjectInformation related to customer against who the invoice is issued, it's NULL when type is POS
CUSTOMER_NATIONALITYstringCustomer's nationality, alpha2 code format
CUSTOMER_RESID_COUNTRYstringCustomer's residential country, alpha2 code format
CUSTOMER_RESID_STATEstringOptional, customer's residential state/province
CUSTOMER_RESID_CITYstringCustomer's residential city/town
CUSTOMER_RESID_ZIPstringCustomer's residential zip code/postal code
CUSTOMER_RESID_STREETstringCustomer's residential street address
CUSTOMER_RESID_NOstringOptional, customer's residential building number/name
CUSTOMER_FULLNAMEstringCustomer's full name
CUSTOMER_EMAILstringCustomer's email address
CUSTOMER_TOS_ACCEPTEDbooleanFlag that specified whenever the customer has accepted terms of service
INVOICESarray of objectsPayment details for each payable currency
INVOICES_AMOUNTfloatAmount in specific payable currency
INVOICES_PAY_CCYstringPayment currency
INVOICES_POOL_CCYstringUnderlying technology used by payment currency
INVOICES_ADDRESSstringDeposit/Payment address
INVOICES_EXTobjectOptional, additional data related to payment

🚧

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,
      "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.

Ratelimit: 90 req/min

Language