Submit a point of sale invoice for payment
Response data
| Term | Type | Description |
|---|---|---|
| ID | string | Unique invoice identifier |
| T | int | Timestamp when invoice is created |
| TYPE | string | Invoice type, currently supported ECOMMERCE and POS |
| DURATION | int | Invoice expire time in seconds |
| AMOUNT | float | Invoice amount in currency |
| CURRENCY | string | Invoice currency |
| ORDER_ID | string | Reference order identifier in merchant's platform |
| PAY_CURRENCIES | array of strings | Currencies in which invoice accepts the payments |
| WEBHOOK | string | Optional, the endpoint that will be called once the payment is completed/expired |
| REDIRECT_URL | string | Optional, merchant redirect URL, this one is used in UI to redirect customer to merchant's site once the payment is completed/expired |
| STATUS | string | Payment status, should be one of: CREATED, PENDING, COMPLETED, EXPIRED |
| CUSTOMER_INFO | object | Always NULL for POS invoices, for other types see https://docs.bitfinex.com/reference/submit-invoice response |
| INVOICES | array of objects | Payment details for each payable currency |
| INVOICES_AMOUNT | float | Amount in specific payable currency |
| INVOICES_BFXPAY_CCY | string | Bitfinex pay currency that corresponds to list of PAY_CURRENCIES |
| INVOICES_PAY_CCY | string | Payment currency |
| INVOICES_POOL_CCY | string | Underlying technology used by payment currency |
| INVOICES_ADDRESS | string | Deposit/Payment address |
| INVOICES_EXT | object | Optional, additional data related to payment |
| METADATA | object | Optional, invoice metadata |
| FLAGS | array of strings | Optional, flags related to invoice |
| RECALCULATED_AT | int | Optional, timestamp in milliseconds when invoice prices got recalculated |
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, PENDING 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 // optional, omitted in case of EXPIRED invoice
- 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": "POS", "orderId": "order123", "status": "PENDING", "amount": 2.5, "currency": "USD", "t": 1612460165497, "invoices": [ { "amount": 0.00604018, "currency": "ETH", "payCurrency": "ETH", "poolCurrency": "ETH", "address": "0xcbebcd41ceabbc85da9bb67527f58d69ad4dfff5" } ], "payment": { "txid": "0x5119b4caaad1af22bebb2373995d8ecd8dfb23cc1971d0347aaa516b4e0f3e3a", "amount": 0.00604018, "currency": "ETH", "method": "ETHEREUM", "status": "COMPLETED", "confirmations": 6, "created_at": "2021-01-06 21:16:28", "updated_at": "2021-01-06 21:16:40", "depositId": 1357996, "amountDiff": "-0.0000001" }, "additionalPayments": [ { "txid": "0x44fa3dbdc2fa763e3f808ea77895d5204a658e3ba3dd7e5909c06f0689158442", "amount": 0.0000069, "currency": "ETH", "method": "ETHEREUM", "status": "COMPLETED", "confirmations": 6, "created_at": "2021-01-06 21:18:31", "updated_at": "2021-01-06 21:18:39", "depositId": 1357997, } ] }
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