Create Invoice - Finrock

curl --request POST \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "fiat": {
         "asset_id": "USD",
         "amount": 160.59
       },
       "crypto": {
         "asset_id": "BNB_TEST",
         "amount": 0.27
       },
       "memo": "50k-s1870",
       "payer": {
         "name": null,
         "email": null,
         "mobile": null,
         "country_code": null,
         "ip": null,
         "browser": null,
         "os": null
       },
       "ipn_url": "https://example.com/webhooks/finrock",
       "success_url": "https://example.com/payment/success",
       "failed_url": "https://example.com/payment/failed"
     }'

{
  "fiat": {
    "asset_id": "USD",
    "asset": "USD",
    "symbol": "$",
    "asset_name": "US Dollars",
    "amount": 160.59,
    "paid": 0.0,
    "pending": 160.59
  },
  "crypto": {
    "asset_id": "BNB_TEST",
    "asset": "BNB",
    "network": "",
    "asset_name": "Binance Smart Chain (BEP20)",
    "icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "network_icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "amount": 0.27,
    "paid": 0.00000000,
    "pending": 0.27,
    "address": "0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF",
    "address_tag": "",
    "testnet": true,
    "address_url": "https://testnet.bscscan.com/address/0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF"
  },
  "memo": "50k-s1870",
  "payer": {
    "name": null,
    "email": null,
    "mobile": null,
    "country_code": null,
    "ip": null,
    "browser": null,
    "os": null
  },
  "company": {
    "name": "Acme Retail Ltd.",
    "email": "billing@example.com",
    "country_code": "AE"
  },
  "id": "b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "expiry_ts": 1781163070,
  "status": "Pending",
  "txn_hash": null,
  "explorer_url": null,
  "payment_url": "https://finrock.io/wpay/b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "ipn_url": "https://example.com/webhooks/finrock",
  "success_url": "https://example.com/payment/success",
  "failed_url": "https://example.com/payment/failed",
  "confirmations": "0/5",
  "txns": []
}

POST

dac

invoice

curl --request POST \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "fiat": {
         "asset_id": "USD",
         "amount": 160.59
       },
       "crypto": {
         "asset_id": "BNB_TEST",
         "amount": 0.27
       },
       "memo": "50k-s1870",
       "payer": {
         "name": null,
         "email": null,
         "mobile": null,
         "country_code": null,
         "ip": null,
         "browser": null,
         "os": null
       },
       "ipn_url": "https://example.com/webhooks/finrock",
       "success_url": "https://example.com/payment/success",
       "failed_url": "https://example.com/payment/failed"
     }'

{
  "fiat": {
    "asset_id": "USD",
    "asset": "USD",
    "symbol": "$",
    "asset_name": "US Dollars",
    "amount": 160.59,
    "paid": 0.0,
    "pending": 160.59
  },
  "crypto": {
    "asset_id": "BNB_TEST",
    "asset": "BNB",
    "network": "",
    "asset_name": "Binance Smart Chain (BEP20)",
    "icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "network_icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "amount": 0.27,
    "paid": 0.00000000,
    "pending": 0.27,
    "address": "0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF",
    "address_tag": "",
    "testnet": true,
    "address_url": "https://testnet.bscscan.com/address/0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF"
  },
  "memo": "50k-s1870",
  "payer": {
    "name": null,
    "email": null,
    "mobile": null,
    "country_code": null,
    "ip": null,
    "browser": null,
    "os": null
  },
  "company": {
    "name": "Acme Retail Ltd.",
    "email": "billing@example.com",
    "country_code": "AE"
  },
  "id": "b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "expiry_ts": 1781163070,
  "status": "Pending",
  "txn_hash": null,
  "explorer_url": null,
  "payment_url": "https://finrock.io/wpay/b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "ipn_url": "https://example.com/webhooks/finrock",
  "success_url": "https://example.com/payment/success",
  "failed_url": "https://example.com/payment/failed",
  "confirmations": "0/5",
  "txns": []
}

MCP scope: dac.write Finrock’s invoicing feature lets you generate on-chain payment requests that your customers can settle in cryptocurrency. When you create an invoice you specify either a fiat price or a crypto asset and amount, a descriptive memo, optional payer details, and URLs for payment notifications and payer redirects. Finrock returns the invoice with a deposit address, a hosted payment page URL, an expiry time, and the payment status.

Body Parameters

Method: POST URL: https://api.finrock.io/dac/v1/invoice

Every invoice needs crypto.asset_id, the asset the payer pays in. Set the price in one of two ways: with fiat, which Finrock converts into the crypto amount, or with crypto.amount. A request with fiat but no crypto.asset_id returns HTTP 400 with {"code": 1002, "error": "ASSET_REQUIRED"}.

object

Fiat price of the invoice. Finrock uses it only to calculate the crypto amount due. Use it instead of crypto.amount when you price in fiat. You still need crypto.asset_id.

Show properties

string

Fiat currency code (e.g., USD, EUR, GBP, AED).

double

Invoice amount in the fiat currency.

object

Crypto asset and amount the payer settles the invoice in. Always required, because it sets the asset the payer pays with.

Show properties

string

required

Asset to accept, using the id value from Supported Assets (e.g., BTC, ETH, BNB_TEST).

double

Amount due in the crypto asset. Maximum precision is 8 decimal places. Leave it out to have Finrock calculate it from fiat.

string

required

A descriptive note for this payment. Use it to identify the invoice in your records, and to filter with List Invoices.

object

Information about the payer. Each field can be null.

Show properties

string

Full name of the payer.

string

Email address of the payer.

string

Mobile number of the payer.

string

Country code of the payer.

string

IP address of the payer.

string

Browser the payer is using.

string

Operating system the payer is using.

string

URL that receives an instant payment notification (IPN) for this invoice.

string

URL the payer is redirected to after a successful payment.

string

URL the payer is redirected to when the payment fails.

curl --request POST \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "fiat": {
         "asset_id": "USD",
         "amount": 160.59
       },
       "crypto": {
         "asset_id": "BNB_TEST",
         "amount": 0.27
       },
       "memo": "50k-s1870",
       "payer": {
         "name": null,
         "email": null,
         "mobile": null,
         "country_code": null,
         "ip": null,
         "browser": null,
         "os": null
       },
       "ipn_url": "https://example.com/webhooks/finrock",
       "success_url": "https://example.com/payment/success",
       "failed_url": "https://example.com/payment/failed"
     }'

Response

A successful request returns HTTP 200 with the created invoice object.

string

Unique invoice identifier. Use it with the id filter on List Invoices.

string

Invoice status. One of Pending, Processing, Paid, Expired, Failed, Cancelled, or Refunded.

object

Fiat price of the invoice and how much of it has been paid.

Show properties

string

Fiat currency identifier, for example USD.

string

Fiat currency code.

string

Currency symbol, for example $.

string

Display name of the currency, for example US Dollars.

double

Invoice amount in the fiat currency.

double

Fiat amount paid so far.

double

Fiat amount still outstanding.

object

Crypto asset, amount due, and the deposit address the payer sends funds to.

Show properties

string

Finrock asset identifier, for example BNB_TEST.

string

Asset ticker, for example BNB.

string

Network name. Can be an empty string.

string

Display name of the asset and network, for example Binance Smart Chain (BEP20).

string

URL of the asset icon.

string

URL of the network icon.

double

Amount due in the crypto asset.

double

Crypto amount received so far.

double

Crypto amount still outstanding.

string

Deposit address the payer sends funds to.

string

Destination tag or memo for the deposit address, on chains that use one. Empty string otherwise.

boolean

true if the asset is on a test network.

string

Block explorer URL for the deposit address.

string

The memo attached to the invoice.

object

Payer details. Each field is null when not provided.

Show properties

string

Full name of the payer.

string

Email address of the payer.

string

Mobile number of the payer.

string

Country code of the payer.

string

IP address of the payer.

string

Browser the payer is using.

string

Operating system the payer is using.

object

Details of the company issuing the invoice.

Show properties

string

Company name.

string

Company email address.

string

Company country code, for example AE.

integer

Invoice expiry time as a Unix timestamp in seconds.

string

On-chain hash of the payment transaction. null until a payment is received.

string

Block explorer URL for the payment transaction. null until a payment is received.

string

URL of the hosted payment page. Send your payer here to complete the payment.

string

URL that receives payment notifications for this invoice.

string

URL the payer is redirected to after a successful payment.

string

URL the payer is redirected to when the payment fails.

string

Block confirmations received out of the number required, for example 0/5.

array

Payment transactions received against this invoice. Empty until a payment arrives.

{
  "fiat": {
    "asset_id": "USD",
    "asset": "USD",
    "symbol": "$",
    "asset_name": "US Dollars",
    "amount": 160.59,
    "paid": 0.0,
    "pending": 160.59
  },
  "crypto": {
    "asset_id": "BNB_TEST",
    "asset": "BNB",
    "network": "",
    "asset_name": "Binance Smart Chain (BEP20)",
    "icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "network_icon": "https://finrock.io/assets/icons/coins/BNB.png",
    "amount": 0.27,
    "paid": 0.00000000,
    "pending": 0.27,
    "address": "0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF",
    "address_tag": "",
    "testnet": true,
    "address_url": "https://testnet.bscscan.com/address/0xA5a90F5411e74aEFaD1E9234993d3da90C51cFAF"
  },
  "memo": "50k-s1870",
  "payer": {
    "name": null,
    "email": null,
    "mobile": null,
    "country_code": null,
    "ip": null,
    "browser": null,
    "os": null
  },
  "company": {
    "name": "Acme Retail Ltd.",
    "email": "billing@example.com",
    "country_code": "AE"
  },
  "id": "b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "expiry_ts": 1781163070,
  "status": "Pending",
  "txn_hash": null,
  "explorer_url": null,
  "payment_url": "https://finrock.io/wpay/b198d0f8-dc7d-4418-a504-73aec3d2dc37",
  "ipn_url": "https://example.com/webhooks/finrock",
  "success_url": "https://example.com/payment/success",
  "failed_url": "https://example.com/payment/failed",
  "confirmations": "0/5",
  "txns": []
}

Invoices are time-limited. Ensure your payer sends the payment before expiry_ts. Payments received after expiry may require manual reconciliation.