How to use Bitfinex Pay for merchants? (Payment integration)

Bitfinex Pay Overview

1. Bitfinex Pay is a merchant-facing payment processing solution developed by iFinex Inc., the same entity operating Bitfinex and Tether.

2. It enables businesses to accept cryptocurrency payments directly on their websites or point-of-sale systems without requiring customers to hold exchange accounts.

3. The service supports major cryptocurrencies including BTC, ETH, USDT, and UNUS SED LEO, with real-time conversion options into fiat currencies.

4. Integration relies on RESTful APIs and webhook-based notification architecture for order status updates and settlement reconciliation.

5. Merchants must complete KYC verification through Bitfinex’s institutional onboarding portal before accessing production credentials.

Technical Integration Steps

1. Developers access the Bitfinex Pay Developer Portal to register a merchant application and obtain API keys scoped to payment initiation and webhook signing.

2. A pre-signed invoice payload is generated server-side using HMAC-SHA256 with the merchant’s secret key, embedding amount, currency, callback URL, and expiration timestamp.

3. The signed payload is sent via POST request to https://pay.bitfinex.com/api/v1/invoice, returning a unique invoice ID and QR code SVG data.

4. The merchant renders the QR code or redirects the customer to the hosted checkout page using the provided URL.

5. Upon successful on-chain confirmation, Bitfinex Pay dispatches an HTTP POST to the registered webhook endpoint containing a JSON object with status, transaction hash, and settlement details.

Settlement & Reconciliation

1. Settlements occur in batches every 6 hours, with funds credited to the merchant’s designated Bitfinex wallet or external bank account if fiat conversion is enabled.

2. Each settlement includes a cryptographically signed receipt referencing the original invoice ID, block height, and net amount after network fees.

3. Merchants can query historical invoices using the /api/v1/invoices endpoint with pagination and date-range filters.

4. Failed or expired invoices automatically trigger webhook notifications with error codes such as ERR_INVOICE_EXPIRED or ERR_INSUFFICIENT_CONFIRMATIONS.

5. Refunds are initiated exclusively through the merchant dashboard or via the /api/v1/refund endpoint, requiring the original invoice ID and reason code.

Security Protocols

1. All webhook payloads include a X-BFX-Signature header containing a base64-encoded HMAC of the raw body using the merchant’s shared secret.

2. IP allowlisting is enforced at the account level; only whitelisted IPv4/IPv6 ranges may initiate invoice creation requests.

3. Callback URLs must use TLS 1.2+ with valid X.509 certificates issued by trusted CAs; self-signed certificates are rejected.

4. Invoice payloads expire within 15 minutes of generation, preventing replay attacks.

5. Private keys used for signature verification are never transmitted over the network and must be stored in hardware security modules (HSMs) or equivalent secure enclaves.

Frequently Asked Questions

Q: Does Bitfinex Pay support recurring billing or subscription models?A: No. Bitfinex Pay is designed for one-time, atomic invoice settlements. Recurring logic must be implemented externally using scheduled invoice generation.

Q: Can merchants disable automatic fiat conversion during settlement?A: Yes. Merchants may configure settlement currency per invoice or globally via the dashboard under “Settlement Preferences”, retaining crypto balances in native wallets.

Q: What happens if a blockchain transaction confirms but fails final settlement due to insufficient liquidity?A: Bitfinex Pay guarantees settlement upon confirmation. Liquidity shortfalls are resolved internally by iFinex; merchants receive full value regardless of market conditions.

Q: Is there a sandbox environment for testing integration flows?A: Yes. The Developer Portal provides a staging endpoint at https://pay-staging.bitfinex.com with mock blockchain confirmations and zero-fee test transactions.