Invoices

Methods for creating, listing, and updating invoices in B2BINPAY DeFi API

Get list

get

Get list of entities

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

deploymentIdstring · uuidRequired

Deployment unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

idstringOptional

Filter by invoice ID (text includes)

Example: 1234567890

createdFromstringOptional

Filter invoices created from this date (ISO string)

Example: 2024-01-01T00:00:00Z

createdTostringOptional

Filter invoices created to this date (ISO string)

Example: 2024-12-31T23:59:59Z

updatedFromstringOptional

Filter invoices updated from this date (ISO string)

Example: 2024-01-01T00:00:00Z

updatedTostringOptional

Filter invoices updated to this date (ISO string)

Example: 2024-12-31T23:59:59Z

currencyIdsone ofOptional

Filter by currency IDs

Example: ["1-0xdac17f958d2ee523a2206206994597c13d831ec7","1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"]

string · min: 1Optional

or

string[]Optional

statusesone ofOptional

Filter by invoice statuses (multiselect)

Example: ["CREATED","PAID"]

string · enumOptionalPossible values:

or

trackingIdstringOptional

Filter by tracking ID (text includes)

Example: TRACK_123456

sortBystring · enumOptional

Field to sort by

Default: createdAtExample: idPossible values:

sortOrderstring · enumOptional

Sort order (ascending or descending)

Default: descExample: descPossible values:

pagenumberOptional

Page number (starts from 1)

Default: 1Example: 1

pageSizenumber · max: 100Optional

Number of items per page (max 100)

Default: 10Example: 10

Responses

200

Entity retrieved successfully

application/json

totalnumberRequired

Total number of items across all pages

pagenumberRequired

Current page number (starts from 1)

pageSizenumberRequired

Number of items per page

401

Invalid or missing token

404

[ERR_404] Team not found or [ERR_403] You are not a member of this team

get

/api/v1/deployments/{deploymentId}/invoices

HTTPcURLJavaScriptPython

GET /api/v1/deployments/{deploymentId}/invoices HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "total": 1,
  "page": 1,
  "pageSize": 1,
  "items": [
    {
      "id": "1234567890123456789",
      "publicId": "1234567890123456789",
      "invoiceAddress": "0x1234567890123456789012345678901234567890",
      "requestedAmount": "1500.75",
      "paidAmount": "0.00",
      "paidAmountBaseCurrency": "text",
      "status": "CREATED",
      "trackingId": "INV-2024-0001",
      "callbackUrl": "https://example.com/webhook/invoice",
      "paymentPageButtonUrl": "https://example.com/invoice/pay",
      "paymentPageButtonText": "Pay Invoice",
      "paymentPageUrl": "https://frontend.example.com/pay/1234567890123456789",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "availableCurrencies": [
        {
          "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
          "symbol": "USDT",
          "name": "Tether USD",
          "chainId": "1",
          "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "decimals": 18,
          "isScam": false,
          "isVerified": true
        }
      ],
      "isTron": false
    }
  ]
}

Create

post

Create new entity

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

deploymentIdstring · uuidRequired

Deployment unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

Body

application/json

requestedAmountstring · min: 1 · nullableRequiredPattern: ^\d+(\.\d+)?$

trackingIdstring · min: 1 · max: 128 · nullableRequiredPattern: ^[A-Za-z0-9\-]+$

callbackUrlstring · uri · nullableRequired

paymentPageButtonUrlstring · uri · nullableRequired

paymentPageButtonTextstring · min: 1 · max: 26 · nullableRequired

currencyIdsstring[]OptionalDefault: []

Responses

201

Entity created successfully

application/json

400

Invalid input

401

Invalid or missing token

404

[ERR_404] Team not found or [ERR_403] You are not a member of this team

409

[ERR_409] Invoice with this tracking ID already exists or [ERR_409] Invoice with this address already exists

post

/api/v1/deployments/{deploymentId}/invoices

HTTPcURLJavaScriptPython

POST /api/v1/deployments/{deploymentId}/invoices HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "requestedAmount": "text",
  "trackingId": "text",
  "callbackUrl": "https://example.com",
  "paymentPageButtonUrl": "https://example.com",
  "paymentPageButtonText": "text",
  "currencyIds": [
    "text"
  ]
}

{
  "id": "1234567890123456789",
  "publicId": "1234567890123456789",
  "invoiceAddress": "0x1234567890123456789012345678901234567890",
  "requestedAmount": "1500.75",
  "paidAmount": "0.00",
  "paidAmountBaseCurrency": "text",
  "status": "CREATED",
  "trackingId": "INV-2024-0001",
  "callbackUrl": "https://example.com/webhook/invoice",
  "paymentPageButtonUrl": "https://example.com/invoice/pay",
  "paymentPageButtonText": "Pay Invoice",
  "paymentPageUrl": "https://frontend.example.com/pay/1234567890123456789",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "availableCurrencies": [
    {
      "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "symbol": "USDT",
      "name": "Tether USD",
      "chainId": "1",
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "decimals": 18,
      "isScam": false,
      "isVerified": true
    }
  ],
  "isTron": false
}

Get by ID

get

Get entity by ID

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

deploymentIdstring · uuidRequired

Deployment unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

invoiceIdstringRequired

Entity ID

Example: 1234567890123456789

Responses

200

Entity retrieved successfully

application/json

401

Invalid or missing token

404

[ERR_404] Invoice not found or [ERR_403] You are not a member of this team

get

/api/v1/deployments/{deploymentId}/invoices/{invoiceId}

HTTPcURLJavaScriptPython

GET /api/v1/deployments/{deploymentId}/invoices/{invoiceId} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "invoice": {
    "id": "1234567890123456789",
    "publicId": "1234567890123456789",
    "invoiceAddress": "0x1234567890123456789012345678901234567890",
    "requestedAmount": "1500.75",
    "paidAmount": "0.00",
    "paidAmountBaseCurrency": "text",
    "status": "CREATED",
    "trackingId": "INV-2024-0001",
    "callbackUrl": "https://example.com/webhook/invoice",
    "paymentPageButtonUrl": "https://example.com/invoice/pay",
    "paymentPageButtonText": "Pay Invoice",
    "paymentPageUrl": "https://frontend.example.com/pay/1234567890123456789",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "availableCurrencies": [
      {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": "1",
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "decimals": 18,
        "isScam": false,
        "isVerified": true
      }
    ],
    "isTron": false
  }
}

Update

put

Update entity

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

deploymentIdstring · uuidRequired

Deployment unique identifier

Example: 123e4567-e89b-12d3-a456-426614174000

invoiceIdstringRequired

Entity ID

Example: 1234567890123456789

Body

application/json

requestedAmountstring · min: 1 · nullableRequiredPattern: ^\d+(\.\d+)?$

trackingIdstring · min: 1 · max: 128 · nullableRequiredPattern: ^[A-Za-z0-9\-]+$

callbackUrlstring · uri · nullableRequired

paymentPageButtonUrlstring · uri · nullableRequired

paymentPageButtonTextstring · min: 1 · max: 26 · nullableRequired

currencyIdsstring[]Optional

statusstring · enumOptionalPossible values:

Responses

200

Entity retrieved successfully

application/json

idstringRequired

Entity unique identifier

Example: 1234567890123456789

publicIdstringRequired

Invoice public identifier (Snowflake ID)

Example: 1234567890123456789

invoiceAddressstringRequired

Invoice payment address

Example: 0x1234567890123456789012345678901234567890

requestedAmountstring · nullableRequired

Requested payment amount

Example: 1500.75

paidAmountstring · nullableRequired

Paid amount in crypto; null for multi-currency invoices (see paidAmountBaseCurrency)

Example: 0.00

paidAmountBaseCurrencystring · nullableRequired

Paid amount converted to user base currency (2 decimals) for multi-currency invoices; null otherwise

statusstring · enumRequired

Invoice status

Example: CREATEDPossible values:

trackingIdstring · nullableRequired

Tracking identifier

Example: INV-2024-0001

callbackUrlstring · nullableRequired

Callback URL for notifications

Example: https://example.com/webhook/invoice

paymentPageButtonUrlstring · nullableRequired

Custom payment page button URL

Example: https://example.com/invoice/pay

paymentPageButtonTextstring · nullableRequired

Custom payment page button text

Example: Pay Invoice

paymentPageUrlstringRequired

Payment page URL for the invoice

Example: https://frontend.example.com/pay/1234567890123456789

createdAtstringRequired

Creation timestamp

Example: 2024-01-01T00:00:00.000Z

updatedAtstringRequired

Last update timestamp

Example: 2024-01-01T00:00:00.000Z

isTronbooleanRequired

Whether the entity relates to Tron (TVM)

Example: false

400

Invalid input

401

Invalid or missing token

404

[ERR_404] Invoice not found or [ERR_403] You are not a member of this team

409

[ERR_409] Invoice with this tracking ID already exists

put

/api/v1/deployments/{deploymentId}/invoices/{invoiceId}

HTTPcURLJavaScriptPython

PUT /api/v1/deployments/{deploymentId}/invoices/{invoiceId} HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 200

{
  "requestedAmount": "text",
  "trackingId": "text",
  "callbackUrl": "https://example.com",
  "paymentPageButtonUrl": "https://example.com",
  "paymentPageButtonText": "text",
  "currencyIds": [
    "text"
  ],
  "status": "CREATED"
}

{
  "id": "1234567890123456789",
  "publicId": "1234567890123456789",
  "invoiceAddress": "0x1234567890123456789012345678901234567890",
  "requestedAmount": "1500.75",
  "paidAmount": "0.00",
  "paidAmountBaseCurrency": "text",
  "status": "CREATED",
  "trackingId": "INV-2024-0001",
  "callbackUrl": "https://example.com/webhook/invoice",
  "paymentPageButtonUrl": "https://example.com/invoice/pay",
  "paymentPageButtonText": "Pay Invoice",
  "paymentPageUrl": "https://frontend.example.com/pay/1234567890123456789",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "availableCurrencies": [
    {
      "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "symbol": "USDT",
      "name": "Tether USD",
      "chainId": "1",
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "decimals": 18,
      "isScam": false,
      "isVerified": true
    }
  ],
  "isTron": false
}

Get public invoice details

get

Get public invoice information without authentication

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

publicIdstringRequired

Invoice public identifier (Snowflake ID)

Example: 1234567890123456789

Responses

200

Public invoice details

application/json

publicIdstringRequired

Invoice public identifier (Snowflake ID)

Example: 1234567890123456789

invoiceAddressstringRequired

Invoice payment address

Example: 0x1234567890123456789012345678901234567890

chainIdstringRequired

Blockchain network chain ID

Example: 1

requestedAmountstring · nullableRequired

Requested payment amount

Example: 1500.75

paymentPageButtonUrlstring · nullableRequired

Custom payment page button URL

Example: https://example.com/invoice/pay

paymentPageButtonTextstring · nullableRequired

Custom payment page button text

Example: Pay Invoice

paymentPageUrlstringRequired

Payment page URL for the invoice

Example: https://frontend.example.com/pay/1234567890123456789

statusstring · enumRequired

Invoice status

Example: CREATEDPossible values:

createdAtstringRequired

Creation timestamp

Example: 2024-01-01T00:00:00.000Z

isTronbooleanRequired

Whether the entity relates to Tron (TVM)

Example: false

404

[ERR_404] Invoice not found

get

/api/v1/public/invoices/{publicId}

HTTPcURLJavaScriptPython

GET /api/v1/public/invoices/{publicId} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "publicId": "1234567890123456789",
  "invoiceAddress": "0x1234567890123456789012345678901234567890",
  "chainId": "1",
  "requestedAmount": "1500.75",
  "availableCurrencies": [
    {
      "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "symbol": "USDT",
      "name": "Tether USD",
      "chainId": "1",
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "decimals": 18,
      "isScam": false,
      "isVerified": true
    }
  ],
  "paymentPageButtonUrl": "https://example.com/invoice/pay",
  "paymentPageButtonText": "Pay Invoice",
  "paymentPageUrl": "https://frontend.example.com/pay/1234567890123456789",
  "status": "CREATED",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "isTron": false
}

Get public invoice transactions

get

Get list of transactions for a public invoice without authentication

Authorizations

ApiKeyAuth

x-api-keystringRequired

Provide API key in X-API-Key header

Path parameters

publicIdstringRequired

Invoice public identifier (Snowflake ID)

Example: 1234567890123456789

Query parameters

txHashstringOptional

Filter by transaction hash

Example: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

currencyIdsone ofOptional

Filter by currency IDs

Example: ["1-0xdac17f958d2ee523a2206206994597c13d831ec7","1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"]

string · min: 1Optional

or

string[]Optional

statusesone ofOptional

Filter by transaction statuses

Example: ["EXECUTED"]

string · enumOptionalPossible values:

or

operationTypesone ofOptional

Filter by operation types

Example: ["invoice","claim"]

string · enumOptionalPossible values:

or

createdFromstringOptional

Filter transactions created after this date (ISO 8601)

Example: 2024-01-01T00:00:00.000Z

createdTostringOptional

Filter transactions created before this date (ISO 8601)

Example: 2024-12-31T23:59:59.999Z

pagenumberOptional

Page number (starts from 1)

Default: 1Example: 1

pageSizenumber · max: 100Optional

Number of items per page (max 100)

Default: 10Example: 10

idstringOptional

updatedFromstringOptional

updatedTostringOptional

operationIdstringOptional

isClaimedone ofOptional

booleanOptional

or

anyOptional

Responses

200

Paginated list

application/json

totalnumberRequired

Total number of items

Example: 100

pagenumberRequired

Current page number

Example: 1

pageSizenumberRequired

Number of items per page

Example: 10

404

[ERR_404] Invoice not found

get

/api/v1/public/invoices/{publicId}/transactions

HTTPcURLJavaScriptPython

GET /api/v1/public/invoices/{publicId}/transactions HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "EXECUTED",
      "chainId": "1",
      "txHash": "0x5555666677778888999900001111222233334444555566667777888899990000",
      "currencyId": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "100.50",
      "toAddress": "0x9876543210987654321098765432109876543210",
      "blockNumber": 12345678,
      "confirmations": 12,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "currency": {
        "id": "1-0xdac17f958d2ee523a2206206994597c13d831ec7",
        "symbol": "USDT",
        "name": "Tether USD",
        "chainId": "1",
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "decimals": 18,
        "isScam": false,
        "isVerified": true
      }
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 10
}