API docs by Redocly

Cryptocurrency Invoice API (1.1.0)

Download OpenAPI specification:

API Support: [email protected] URL: https://itispay.com/support License: MIT

REST API for generating and managing cryptocurrency invoices with support for multiple transactions per invoice

Invoices

Invoice management operations

Create a new invoice

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
order_id
required
string
fiat_amount
number <double> >= 0
fiat_currency
string
Value: "EUR"
crypto_amount
number <double> >= 0
currency
required
string
allowed_error_percent
integer [ 0 .. 100 ]
order_name
string
expire_min
integer >= 1
callback_url
string <uri>

Responses

Request samples

Content type
application/json
{
  • "order_id": "string",
  • "fiat_amount": 0.1,
  • "fiat_currency": "EUR",
  • "crypto_amount": 0.1,
  • "currency": "string",
  • "allowed_error_percent": 100,
  • "order_name": "string",
  • "expire_min": 1,
  • "callback_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "invoice_id": "123e4567-e89b-12d3-a456-426614174000",
  • "order_id": "order-123",
  • "fiat_amount": 100,
  • "fiat_currency": "EUR",
  • "currency": "BTC",
  • "crypto_amount": 0.001,
  • "actual_crypto_amount_paid": 0,
  • "actual_crypto_amount_paid_in_units": 0,
  • "allowed_error_percent": 5,
  • "order_name": "Sample Order",
  • "expire_min": 30,
  • "callback_url": "https://example.com/webhook",
  • "status": "new",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T10:30:00Z",
  • "expires_at": "2024-01-15T11:00:00Z",
  • "blockchain_details": {
    },
  • "transactions": [ ]
}

List invoices with filtering and pagination

Authorizations:
ApiKeyAuth
query Parameters
status
string
Enum: "new" "pending" "completed" "expired" "cancelled" "paid_partial" "archived"

Filter by invoice status

currency
string

Filter by currency

created_after
string <date-time>

Filter invoices created after this date

created_before
string <date-time>

Filter invoices created before this date

page
integer >= 1
Default: 1

Page number for pagination

page_size
integer [ 1 .. 100 ]
Default: 20

Number of invoices per page

sort_by
string
Enum: "created_at" "updated_at" "fiat_amount" "crypto_amount"

Field to sort by

sort_order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Create an archived invoice

Create an invoice with archived status for historical record keeping. These invoices do not have blockchain details and are not processed for payments.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
order_id
required
string

Unique identifier for the order (must be unique within user/project scope)

fiat_amount
number <double> >= 0

Amount in fiat currency

fiat_currency
string

Fiat currency code

crypto_amount
number <double> >= 0

Amount in cryptocurrency

currency
required
string

Cryptocurrency code

allowed_error_percent
integer [ 0 .. 100 ]

Allowed error percentage for payments

order_name
string

Human-readable name for the order

callback_url
string <uri>

URL to receive webhook notifications

created_at
string

Optional custom creation timestamp (must not be in the future). Supported formats:

  • RFC3339: "2006-01-02T15:04:05Z07:00" (recommended)
  • RFC3339Nano: "2006-01-02T15:04:05.999999999Z07:00"
  • Date only: "2006-01-02"
  • DateTime: "2006-01-02 15:04:05"
  • US format: "02/01/2006 15:04:05"

Responses

Request samples

Content type
application/json
Example
{
  • "order_id": "historical-order-123",
  • "fiat_amount": 100,
  • "fiat_currency": "EUR",
  • "currency": "BTC",
  • "order_name": "Historical Order",
  • "created_at": "2023-01-01T10:00:00Z"
}

Response samples

Content type
application/json
{
  • "invoice_id": "123e4567-e89b-12d3-a456-426614174000",
  • "user_id": "user-123",
  • "project_id": "project-456",
  • "order_id": "historical-order-123",
  • "fiat_amount": 100,
  • "fiat_currency": "EUR",
  • "currency": "BTC",
  • "crypto_amount": 0.003,
  • "status": "archived",
  • "created_at": "2023-01-01T10:00:00Z",
  • "updated_at": "2023-01-01T10:00:00Z",
  • "expires_at": "2023-01-01T10:00:00Z",
  • "blockchain_details": { }
}

Get invoice by ID

Authorizations:
ApiKeyAuth
path Parameters
invoice_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "invoice_id": "123e4567-e89b-12d3-a456-426614174000",
  • "order_id": "order-123",
  • "fiat_amount": 100,
  • "fiat_currency": "EUR",
  • "currency": "BTC",
  • "crypto_amount": 0.001,
  • "actual_crypto_amount_paid": 0.001,
  • "actual_crypto_amount_paid_in_units": 100000,
  • "allowed_error_percent": 5,
  • "order_name": "Sample Order",
  • "expire_min": 30,
  • "callback_url": "https://example.com/webhook",
  • "status": "completed",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T11:00:00Z",
  • "expires_at": "2024-01-15T11:00:00Z",
  • "blockchain_details": {
    },
  • "transactions": [
    ]
}

Update invoice status

Authorizations:
ApiKeyAuth
path Parameters
invoice_id
required
string <uuid>
Request Body schema: application/json
required
status
required
string
Enum: "new" "pending" "completed" "expired" "cancelled" "paid_partial" "archived"
comment
string

Optional comment explaining the status change

Responses

Request samples

Content type
application/json
{
  • "status": "new",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
  • "order_id": "string",
  • "fiat_amount": 0.1,
  • "fiat_currency": "string",
  • "currency": "string",
  • "currency_paid": "string",
  • "crypto_amount": 0.1,
  • "crypto_amount_in_units": 0,
  • "actual_crypto_amount_paid": 0.1,
  • "actual_crypto_amount_paid_in_units": 0,
  • "allowed_error_percent": 0,
  • "order_name": "string",
  • "expire_min": 0,
  • "callback_url": "string",
  • "status": "new",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "blockchain_details": {
    },
  • "transactions": [
    ]
}

Export settlements CSV

Returns a CSV file containing all completed invoices that were settled via Paygateway cash-out operations. This endpoint matches invoices to cash-out operations based on time windows and currency.

Requirements:

  • Only available for Paygateway custody projects
  • Operations are grouped by currency and processed chronologically
  • Each operation settles invoices completed between the previous operation and the current operation
  • Only invoices matching the operation's currency are included

CSV Format:

  • order_id: Invoice order ID (empty if null)
  • invoice_id: Invoice unique identifier
  • currency: Invoice currency
  • currency_paid: Currency that was actually used for payment (empty if same as currency)
  • crypto_amount: Crypto amount with 8 decimal places
  • Date of settlement: Operation creation date in UTC (YYYY-MM-DD HH:mm:ss)
  • Hash of settlement: Transaction hash(es), comma-separated if multiple
Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
text/csv
order_id,invoice_id,currency,currency_paid,crypto_amount,Date of settlement,Hash of settlement
order-123,123e4567-e89b-12d3-a456-426614174000,BTC,,0.00100000,2024-01-15 10:30:00,abc123def456
order-456,223e4567-e89b-12d3-a456-426614174001,ETH,USDT,0.05000000,2024-01-15 11:00:00,def456ghi789

Admin

Admin operations across all users and projects

Admin - list invoices across all users and projects

Returns a paginated list of invoices from all users and projects. Supports filtering by currency, fiat_currency and status, plus a free-form search that performs a case-insensitive partial match across invoice_id, user_id, project_id, order_id, order_name and paybis_event_id. Default page size is 20 (max 100).

Items include full blockchain details. Status history and callback history are returned only by GET /admin/invoices/{invoice_id}.

Authorizations:
ApiKeyAuth
query Parameters
status
string

Filter by invoice status

currency
string

Filter by crypto currency (e.g. BTC, ETH, USDT)

fiat_currency
string

Filter by fiat currency (e.g. EUR)

search
string

Free-form search matched (case-insensitive, partial) against invoice_id, user_id, project_id, order_id, order_name and paybis_event_id.

page
integer >= 1
Default: 1

Page number

page_size
integer [ 1 .. 100 ]
Default: 20

Items per page

sort_by
string
Enum: "created_at" "updated_at" "fiat_amount" "crypto_amount"

Field to sort by

sort_order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Admin - get full invoice details

Returns full invoice information including data from invoice_blockchain_details, status history from invoice_status_history and callback history from invoice_callbacks.

Authorizations:
ApiKeyAuth
path Parameters
invoice_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
  • "user_id": "string",
  • "project_id": "string",
  • "order_id": "string",
  • "fiat_amount": 0.1,
  • "fiat_currency": "string",
  • "currency": "string",
  • "currency_paid": "string",
  • "rate_created": 0.1,
  • "crypto_amount": 0.1,
  • "crypto_amount_in_units": 0,
  • "actual_crypto_amount_paid": 0.1,
  • "actual_crypto_amount_paid_in_units": 0,
  • "allowed_error_percent": 0,
  • "order_name": "string",
  • "expire_min": 0,
  • "callback_url": "string",
  • "status": "string",
  • "custody": "amanipay",
  • "int_trans_id": "string",
  • "paybis_event_id": "string",
  • "settlement_date": "2019-08-24T14:15:22Z",
  • "settlement_txid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "blockchain_details": {
    },
  • "transactions": [
    ],
  • "status_history": [
    ],
  • "callbacks": [
    ]
}

Public

Public endpoints that don't require authentication

Get public invoice by ID (no authentication required)

Retrieve invoice information without authentication.

  • For invoices with status 'new', 'pending', or 'paid_partial': returns full invoice details
  • For invoices with other statuses (completed, expired, cancelled, archived): returns only invoice_id and status
path Parameters
invoice_id
required
string <uuid>

Invoice unique identifier

Responses

Response samples

Content type
application/json
Example
{
  • "invoice_id": "123e4567-e89b-12d3-a456-426614174000",
  • "order_id": "order-123",
  • "fiat_amount": 100,
  • "fiat_currency": "EUR",
  • "currency": "BTC",
  • "crypto_amount": 0.001,
  • "actual_crypto_amount_paid": 0.0005,
  • "actual_crypto_amount_paid_in_units": 50000,
  • "allowed_error_percent": 5,
  • "order_name": "Sample Order",
  • "expire_min": 30,
  • "callback_url": "https://example.com/webhook",
  • "status": "pending",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T10:45:00Z",
  • "expires_at": "2024-01-15T11:00:00Z",
  • "blockchain_details": {
    },
  • "transactions": [ ]
}

List supported currencies

Responses

Response samples

Content type
application/json
{
  • "currencies": [
    ]
}

Get exchange rates

Responses

Response samples

Content type
application/json
{
  • "rates": {
    }
}

Testing

Endpoints for testing and development

Simulate webhook for testing purposes

Request Body schema: application/json
required
invoice_id
required
string
status
required
string
Enum: "new" "pending" "completed" "expired" "cancelled" "paid_partial" "archived"

Responses

Request samples

Content type
application/json
{
  • "invoice_id": "string",
  • "status": "new"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string"
}

Projects

Endpoints for create new projects

Create new project via API

Create a new project using account API key authentication. Returns only the essential information: project ID and API key.

Features:

  • Account-level authentication via Api-Key header
  • Auto-generates secure 64-character API key
  • Supports IP restrictions for API key access
  • Streamlined response format for API integration

Authentication:

  • Requires account API key in Api-Key header
  • API key must be a valid 64-character hex string
  • User account must be active and verified
Authorizations:
accountApiKeyAuth
Request Body schema: application/json
required
name
required
string <= 100 characters

Project name (must be unique)

description
string <= 1024 characters

Project description (optional)

api_allowed_ips
string

Comma-separated list of allowed IPs/CIDR blocks for API key access. Examples: "192.168.1.1", "10.0.0.0/8,172.16.1.100", ""

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My API Project",
  • "description": "Created via API"
}

Response samples

Content type
application/json
{
  • "project_id": "550e8400-e29b-41d4-a716-446655440000",
  • "api_key": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
}

Webhook

Webhook management endpoints

Resend the latest webhook callback

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
invoice_id
string <uuid>

Invoice ID to resend callback for

order_id
string

Order ID used to resolve the invoice when invoice_id is not provided

Responses

Request samples

Content type
application/json
{
  • "invoice_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "status": "resent",
  • "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
  • "callback_id": 0
}

Withdraw

Withdrawal operations for paygateway custody

Withdraw cryptocurrency to external wallet

Initiate a cryptocurrency withdrawal to an external wallet address.

Process:

  1. Validates the withdrawal request
  2. Calls paygateway API to initiate the withdrawal
  3. Returns transaction details including fee and transaction ID
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
currency
required
string

Cryptocurrency code (e.g., BTC, ETH, USDT)

to
required
string

Destination wallet address for the withdrawal

amount
required
string

Amount to withdraw in native cryptocurrency units (e.g., "0.002" for BTC, "100" for USDT)

Responses

Request samples

Content type
application/json
Example
{
  • "currency": "BTC",
  • "to": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  • "amount": "0.002"
}

Response samples

Content type
application/json
{
  • "status": "pending",
  • "fee": "0.0001",
  • "wallet_hash": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  • "amount": "0.002",
  • "txn_id": "txn_abc123def456"
}

Payouts

Fiat and crypto payouts via payment-gateway-sdk providers

Send a fiat or crypto payout

Use this endpoint to send a fiat or cryptocurrency payout from your ItisPay account to a customer's bank account or crypto wallet.

Provide the payout details in the request body. The API creates the payout when your account has enough available balance in the selected fiat currency.

Authorizations:
ApiKeyAuth
header Parameters
X-Client-ID
required
string
X-Project-ID
required
string
Request Body schema: application/json
required
type
required
string
Enum: "FIAT_PAYOUT" "CRYPTO_PAYOUT"

Payout type, accepted case-insensitively. New values may be added later.

required
object (PayoutFiat)
object

Required when type is CRYPTO_PAYOUT.

object

Required when type is FIAT_PAYOUT.

callback_url
string <uri>

Webhook URL to receive payout status updates.

user_id
string

End-user identifier in the partner's system.

order_id
string

Partner-side order reference.

merchant
string

Merchant / sender display name.

reference
string

Free-form reference (appears in bank transfer details for FIAT_PAYOUT).

Responses

Request samples

Content type
application/json
Example
{
  • "type": "CRYPTO_PAYOUT",
  • "fiat": {
    },
  • "crypto": {
    },
  • "user_id": "user-001",
  • "order_id": "order-001",
  • "merchant": "Itispay test payout",
  • "reference": "crypto payout test"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "transaction_id": "string",
  • "type": "FIAT_PAYOUT",
  • "status": "string",
  • "amount": "string",
  • "currency": "string",
  • "fiat_amount": "string",
  • "fiat_currency": "string",
  • "crypto_amount": "string",
  • "crypto_currency": "string",
  • "crypto_address": "string",
  • "hash": "string",
  • "quote_id": "string",
  • "exchange_rate": "string",
  • "beneficiary": {
    },
  • "callback_url": "http://example.com",
  • "reference": "string",
  • "user_id": "string",
  • "order_id": "string",
  • "merchant": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}