List Invoices - Finrock

curl --request GET \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?id=b198d0f8-dc7d-4418-a504-73aec3d2dc37' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?memo=50k-s1870' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

[
  {
    "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": []
  }
]

GET

dac

invoice

curl --request GET \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?id=b198d0f8-dc7d-4418-a504-73aec3d2dc37' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?memo=50k-s1870' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

[
  {
    "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.read Use this endpoint to retrieve invoices previously created in your Finrock sub-account. You can fetch all invoices or narrow the results by providing a specific invoice ID or a memo string to match. This is useful for reconciling payments, checking invoice status, and building invoice management workflows in your application.

Query Parameters

string

The unique identifier of the invoice you want to retrieve. When provided, the response contains only the matching invoice.

string

Filter invoices by memo text. Returns all invoices whose memo field matches or contains the provided string.

curl --request GET \
     --url https://api.finrock.io/dac/v1/invoice \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?id=b198d0f8-dc7d-4418-a504-73aec3d2dc37' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
     --url 'https://api.finrock.io/dac/v1/invoice?memo=50k-s1870' \
     --header 'Authorization: Bearer {JWT}' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

Response

A successful request returns HTTP 200 with an array of invoice objects matching your filters. Each object has the same format as the Create Invoice response. If no invoice matches the id or memo you pass, the API returns an empty array, [].

If you connect through Finrock sign-in (for example, the Claude connector), you must pass id or memo. Listing all invoices without a filter works only with an API key.

string

Unique invoice identifier.

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.

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": []
  }
]

To retrieve a single invoice by ID, pass only the id query parameter. To browse all invoices for reconciliation, omit both parameters (API key connections only).