Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Invoices

Create and manage invoices

List invoices

get
/api/v1/invoices

Returns all invoices.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Query parameters
pagenumber · min: 1Optional

Page number (1-based)

Default: 1Example: 1
sizenumber · min: 1 · max: 100Optional

Number of items per page

Default: 10Example: 10
searchstringOptional

Search by invoice reference

Example: INV-123
statusstring · enumOptional

Filter by invoice status

Example: pendingPossible values:
statestring · enumOptional

Filter by invoice state

Example: openPossible values:
currencystringOptional

Filter by currency

Example: NGN
startDatestringOptional

Filter invoices created from this date/time (ISO 8601)

Example: 2026-03-01T00:00:00Z
endDatestringOptional

Filter invoices created up to this date/time (ISO 8601)

Example: 2026-03-11T23:59:59Z
Responses
200Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
get/api/v1/invoices
GET /api/v1/invoices HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "reference": "inv_ref_abc123xyz789",
      "description": "Payment for subscription service",
      "status": "pending",
      "state": "open",
      "isRefunded": false,
      "isUnderpaymentAccepted": false,
      "amount": "100000",
      "amountPaid": "50000",
      "currency": "NGN",
      "items": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Pro Plan subscription",
          "description": "January 2025 billing period",
          "unit": "seats",
          "quantity": "3",
          "unitPrice": "5000.00",
          "lineTotal": "15000.00"
        }
      ],
      "asset": "USDT",
      "chain": "ethereum",
      "merchant": {
        "businessName": "Acme Corporation",
        "logoUrl": "https://example.com/logo.png"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "firstName": "John",
        "lastName": "Doe",
        "email": "customer@example.com",
        "phone": "+1234567890",
        "telegramId": "123456789",
        "metadata": {
          "source": "website",
          "referrer": "google"
        },
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      },
      "url": "https://checkout.coincircuit.io/invoice/inv-abc123",
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "metadata": {
        "orderId": "ORD-12345",
        "customerId": "CUST-67890"
      },
      "periodStart": "2024-01-01T00:00:00.000Z",
      "periodEnd": "2024-01-31T23:59:59.999Z",
      "paidAt": "2024-01-20T10:30:00.000Z",
      "expiresAt": "2024-02-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 42,
    "totalPages": 5
  }
}

Create invoice

post
/api/v1/invoices

Creates an invoice for a product/service.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Body
referencestringOptional

Custom invoice reference. If not provided, auto-generated.

Example: INV-2024-001
currencystring · enumRequired

Fiat currency for the invoice

Example: NGNPossible values:
descriptionstringRequired

Invoice description shown to the customer

Example: Payment for Pro Plan - January 2025
expiresAtstringRequired

Invoice expiry date in ISO 8601 format. Defaults to 1 day from creation, up to a maximum of 5 days.

Example: 2025-01-16T22:30:00.000Z
periodStartstringOptional

Billing period start date (for subscription/recurring invoices)

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

Billing period end date (for subscription/recurring invoices)

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

custom metadata

Example: {"orderId":"12345","customField":"value"}
successUrlstringOptional

Custom success redirect URL for invoice

Example: https://example.com/success
cancelUrlstringOptional

Custom cancel redirect URL for invoice

Example: https://example.com/cancel
webhookUrlstringOptional

Optional URL to receive webhook notifications for this invoice (must be HTTPS). Overrides your dashboard webhook URL for this invoice only.

Example: https://example.com/webhooks
assetstringOptional

Cryptocurrency asset

Example: USDT
chainstringOptional

Blockchain network

Example: ethereum
Responses
201Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
post/api/v1/invoices
POST /api/v1/invoices HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 705

{
  "reference": "INV-2024-001",
  "items": [
    {
      "name": "Pro Plan subscription",
      "description": "January 2025 billing period",
      "unit": "seats",
      "quantity": "3",
      "unitPrice": "5000.00"
    }
  ],
  "currency": "NGN",
  "description": "Payment for Pro Plan - January 2025",
  "expiresAt": "2025-01-16T22:30:00.000Z",
  "periodStart": "2024-12-01T00:00:00.000Z",
  "periodEnd": "2024-12-31T23:59:59.000Z",
  "metadata": {
    "orderId": "12345",
    "customField": "value"
  },
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "webhookUrl": "https://example.com/webhooks",
  "asset": "USDT",
  "chain": "ethereum",
  "customer": {
    "email": "customer@example.com",
    "firstName": "Jane Doe",
    "lastName": "Doe",
    "phone": "+2348012345678",
    "telegramId": "1283761283"
  }
}
{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "inv_ref_abc123xyz789",
    "description": "Payment for subscription service",
    "status": "pending",
    "state": "open",
    "isRefunded": false,
    "isUnderpaymentAccepted": false,
    "amount": "100000",
    "amountPaid": "50000",
    "currency": "NGN",
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Pro Plan subscription",
        "description": "January 2025 billing period",
        "unit": "seats",
        "quantity": "3",
        "unitPrice": "5000.00",
        "lineTotal": "15000.00"
      }
    ],
    "asset": "USDT",
    "chain": "ethereum",
    "merchant": {
      "businessName": "Acme Corporation",
      "logoUrl": "https://example.com/logo.png"
    },
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "customer@example.com",
      "phone": "+1234567890",
      "telegramId": "123456789",
      "metadata": {
        "source": "website",
        "referrer": "google"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "url": "https://checkout.coincircuit.io/invoice/inv-abc123",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "CUST-67890"
    },
    "periodStart": "2024-01-01T00:00:00.000Z",
    "periodEnd": "2024-01-31T23:59:59.999Z",
    "paidAt": "2024-01-20T10:30:00.000Z",
    "expiresAt": "2024-02-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Retrieve invoice by reference

get
/api/v1/invoices/reference/{reference}

Returns the invoice for the given reference.

Path parameters
referencestringRequired

Invoice reference

Example: inv-lx123abc-xyz789def0123456789
Responses
200Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
get/api/v1/invoices/reference/{reference}
GET /api/v1/invoices/reference/{reference} HTTP/1.1
Host: api.coincircuit.io
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "inv_ref_abc123xyz789",
    "description": "Payment for subscription service",
    "status": "pending",
    "state": "open",
    "isRefunded": false,
    "isUnderpaymentAccepted": false,
    "amount": "100000",
    "amountPaid": "50000",
    "currency": "NGN",
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Pro Plan subscription",
        "description": "January 2025 billing period",
        "unit": "seats",
        "quantity": "3",
        "unitPrice": "5000.00",
        "lineTotal": "15000.00"
      }
    ],
    "asset": "USDT",
    "chain": "ethereum",
    "merchant": {
      "businessName": "Acme Corporation",
      "logoUrl": "https://example.com/logo.png"
    },
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "customer@example.com",
      "phone": "+1234567890",
      "telegramId": "123456789",
      "metadata": {
        "source": "website",
        "referrer": "google"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "url": "https://checkout.coincircuit.io/invoice/inv-abc123",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "CUST-67890"
    },
    "periodStart": "2024-01-01T00:00:00.000Z",
    "periodEnd": "2024-01-31T23:59:59.999Z",
    "paidAt": "2024-01-20T10:30:00.000Z",
    "expiresAt": "2024-02-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
PreviousTestnet Faucets
NextPayments

Last updated

Was this helpful?