Payments

Create and manage payment sessions

List payment sessions

get

/api/v1/payments

Returns all Payment Sessions.

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 session reference, payment/deposit address, or transaction hash.

Example: ORDER-123

invoiceReferencestringOptional

Filter by invoice reference

Example: inv_abc123xyz789

customerIdstringOptional

Filter by customer ID

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

pageReferencestringOptional

Filter by payment page reference

Example: page_abc123def456

statestring · enumOptional

Filter by session state: open or closed

Example: openPossible values:

paymentStatusstring · enumOptional

Filter by payment status

Example: completedPossible values:

assetstringOptional

Filter by asset

Example: USDT

chainstringOptional

Filter by blockchain

Example: ethereum

minAmountnumberOptional

Minimum amount (in fiat)

Example: 10

maxAmountnumberOptional

Maximum amount (in fiat)

Example: 1000

includeTransactionsstringOptional

Set to true to add transactions to each session.

Example: true

typestring · enumOptional

Filter by session type

Example: checkoutPossible values:

currencystring · enumOptional

Filter by fiat currency

Example: NGNPossible values:

isRefundedbooleanOptional

Filter by refund status. Pass true to return only refunded sessions.

Example: true

startDatestringOptional

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

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

endDatestringOptional

Filter sessions 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

401

Unauthorized

get/api/v1/payments

GET /api/v1/payments 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": "cs_ref_abc123xyz789",
      "title": "Payment for invoice 112",
      "description": "Payment for invoice 112",
      "state": "open",
      "type": "checkout",
      "amount": "100.00",
      "amountPaid": "100.00",
      "currency": "NGN",
      "settlements": {
        "currency": "USDT",
        "customerPaid": {
          "amount": "29850.00"
        },
        "gross": {
          "amount": "5.00",
          "conversionRate": "1.00000000"
        },
        "fees": {
          "processing": {
            "amount": "0.05",
            "paidBy": "merchant"
          },
          "gas": {
            "amount": "0.05",
            "paidBy": "merchant"
          }
        },
        "net": {
          "amount": "3.85"
        }
      },
      "payment": {
        "status": "pending",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "10.00",
        "amountReceived": "0.00",
        "address": "0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25",
        "gasFee": "0.50",
        "feePaidBy": "customer",
        "conversionRate": "1.00"
      },
      "url": "https://checkout.coincircuit.io/pay/session-ref-123",
      "cancelUrl": "https://example.com/cancel",
      "successUrl": "https://example.com/success",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "phone": "[phone]",
        "telegramId": "123456789",
        "metadata": {
          "source": "website",
          "referrer": "google"
        },
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      },
      "metadata": {
        "orderId": "ORD-9981"
      },
      "invoiceId": null,
      "refundStatus": null,
      "isRefunded": false,
      "isUnderpaymentAccepted": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 42,
    "totalPages": 5
  }
}

Create payment session

post

/api/v1/payments

Creates a new payment session (payment link) to receive payments. You can set the asset and chain together, set one now and the other later, or leave both unset. A deposit address is created immediately only when the session already has the asset, chain, and customer details.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Body

titlestringRequired

Session title

Example: Payment for invoice 112

descriptionstringRequired

Session description

Example: Payment for invoice 112

amountstringRequired

Amount in fiat currency (e.g. 100000.00)

Example: 100000.00

currencystring · enumRequired

Fiat currency

Default: NGNPossible values:

assetstring · enumOptional

Cryptocurrency to accept (optional - can be set later)

Possible values:

chainstring · enumOptional

Blockchain network to accept the crypto on (optional - can be set later)

Possible values:

metadataobjectOptional

Additional metadata object

Example: {"orderId":"ORD-9981","purpose":"Payment for invoice 112"}

cancelUrlstringOptional

Redirect URL when the customer cancels the payment (must be HTTPS)

Example: https://example.com/cancel

successUrlstringOptional

Redirect URL on successful payment (must be HTTPS)

Example: https://example.com/success

webhookUrlstringOptional

URL to receive webhook notifications for this session (must be HTTPS)

Example: https://example.com/webhook

feePaidBystring · enumOptional

Who pays gas/network fees for this session. If not specified, uses dashboard default settings

Example: customerPossible values:

settlementCurrencystring · enumOptional

currency this payment settles into. Defaults to your account currency

Example: USDTPossible values:

Responses

201Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Invalid input or unsupported asset/blockchain combination

401

Unauthorized

500

Internal server error

post/api/v1/payments

POST /api/v1/payments HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 412

{
  "title": "Payment for invoice 112",
  "description": "Payment for invoice 112",
  "amount": "1000.00",
  "currency": "NGN",
  "asset": "USDT",
  "chain": "bsc",
  "customer": {
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe"
  },
  "metadata": {
    "orderId": "ORD-123",
    "purpose": "Payment for invoice"
  },
  "webhookUrl": "https://example.com/webhook",
  "cancelUrl": "https://example.com/cancel",
  "successUrl": "https://example.com/success"
}

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "cs_ref_abc123xyz789",
    "title": "Payment for invoice 112",
    "description": "Payment for invoice 112",
    "state": "open",
    "type": "checkout",
    "amount": "100.00",
    "amountPaid": "100.00",
    "currency": "NGN",
    "settlements": {
      "currency": "USDT",
      "customerPaid": {
        "amount": "29850.00"
      },
      "gross": {
        "amount": "5.00",
        "conversionRate": "1.00000000"
      },
      "fees": {
        "processing": {
          "amount": "0.05",
          "paidBy": "merchant"
        },
        "gas": {
          "amount": "0.05",
          "paidBy": "merchant"
        }
      },
      "net": {
        "amount": "3.85"
      }
    },
    "payment": {
      "status": "pending",
      "asset": "USDT",
      "chain": "ethereum",
      "amount": "10.00",
      "amountReceived": "0.00",
      "address": "0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25",
      "gasFee": "0.50",
      "feePaidBy": "customer",
      "conversionRate": "1.00"
    },
    "url": "https://checkout.coincircuit.io/pay/session-ref-123",
    "cancelUrl": "https://example.com/cancel",
    "successUrl": "https://example.com/success",
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]",
      "phone": "[phone]",
      "telegramId": "123456789",
      "metadata": {
        "source": "website",
        "referrer": "google"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "metadata": {
      "orderId": "ORD-9981"
    },
    "invoiceId": null,
    "refundStatus": null,
    "isRefunded": false,
    "isUnderpaymentAccepted": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "completedAt": null
  }
}

Generate deposit address

post

/api/v1/payments/{reference}/address

Generates a deposit address for the session. If the session already has an asset or chain assigned, those values cannot be overridden. Any missing asset or chain must be provided before the address can be created. If the session does not already have a customer, include customer details (email, and optionally firstName, lastName, phone). If the session already has a customer, the customer field is ignored.

Path parameters

referencestringRequired

Payment session reference

Body

assetstring · enumOptional

Cryptocurrency to accept. Optional when the session already has a fixed asset.

Example: USDTPossible values:

chainstring · enumOptional

Blockchain network. Optional when the session already has a fixed chain.

Example: ethereumPossible values:

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Invalid session state, missing required asset/chain context, or unsupported asset/blockchain

404

Session not found

post/api/v1/payments/{reference}/address

POST /api/v1/payments/{reference}/address HTTP/1.1
Host: api.coincircuit.io
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "asset": "USDT",
  "chain": "ethereum",
  "customer": {
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "telegramId": "1283761283"
  }
}

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "cs_ref_abc123xyz789",
    "title": "Payment for invoice 112",
    "description": "Payment for invoice 112",
    "state": "open",
    "type": "checkout",
    "amount": "100.00",
    "amountPaid": "100.00",
    "currency": "NGN",
    "settlements": {
      "currency": "USDT",
      "customerPaid": {
        "amount": "29850.00"
      },
      "gross": {
        "amount": "5.00",
        "conversionRate": "1.00000000"
      },
      "fees": {
        "processing": {
          "amount": "0.05",
          "paidBy": "merchant"
        },
        "gas": {
          "amount": "0.05",
          "paidBy": "merchant"
        }
      },
      "net": {
        "amount": "3.85"
      }
    },
    "payment": {
      "status": "pending",
      "asset": "USDT",
      "chain": "ethereum",
      "amount": "10.00",
      "amountReceived": "0.00",
      "address": "0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25",
      "gasFee": "0.50",
      "feePaidBy": "customer",
      "conversionRate": "1.00"
    },
    "url": "https://checkout.coincircuit.io/pay/session-ref-123",
    "cancelUrl": "https://example.com/cancel",
    "successUrl": "https://example.com/success",
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]",
      "phone": "[phone]",
      "telegramId": "123456789",
      "metadata": {
        "source": "website",
        "referrer": "google"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "metadata": {
      "orderId": "ORD-9981"
    },
    "invoiceId": null,
    "refundStatus": null,
    "isRefunded": false,
    "isUnderpaymentAccepted": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "completedAt": null
  }
}

Retrieve payment session by reference

get

/api/v1/payments/reference/{reference}

Returns the session for the given reference.

Path parameters

referencestringRequired

Payment session reference

Query parameters

includeTransactionsbooleanOptional

When true, the response includes the transactions array.

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

404

Session not found

get/api/v1/payments/reference/{reference}

GET /api/v1/payments/reference/{reference} HTTP/1.1
Host: api.coincircuit.io
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "cs_ref_abc123xyz789",
    "title": "Payment for invoice 112",
    "description": "Payment for invoice 112",
    "state": "open",
    "type": "checkout",
    "amount": "100.00",
    "amountPaid": "100.00",
    "currency": "NGN",
    "settlements": {
      "currency": "USDT",
      "customerPaid": {
        "amount": "29850.00"
      },
      "gross": {
        "amount": "5.00",
        "conversionRate": "1.00000000"
      },
      "fees": {
        "processing": {
          "amount": "0.05",
          "paidBy": "merchant"
        },
        "gas": {
          "amount": "0.05",
          "paidBy": "merchant"
        }
      },
      "net": {
        "amount": "3.85"
      }
    },
    "payment": {
      "status": "pending",
      "asset": "USDT",
      "chain": "ethereum",
      "amount": "10.00",
      "amountReceived": "0.00",
      "address": "0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25",
      "gasFee": "0.50",
      "feePaidBy": "customer",
      "conversionRate": "1.00"
    },
    "url": "https://checkout.coincircuit.io/pay/session-ref-123",
    "cancelUrl": "https://example.com/cancel",
    "successUrl": "https://example.com/success",
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]",
      "phone": "[phone]",
      "telegramId": "123456789",
      "metadata": {
        "source": "website",
        "referrer": "google"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "metadata": {
      "orderId": "ORD-9981"
    },
    "invoiceId": null,
    "refundStatus": null,
    "isRefunded": false,
    "isUnderpaymentAccepted": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "completedAt": null
  }
}

Calculate crypto amount for session

get

/api/v1/payments/estimate

Calculate the required crypto amount for a session based on selected asset and chain without locking the rate.

Query parameters

amountstringRequired

Amount in fiat currency

Example: 100.00

currencystring · enumRequired

Fiat currency for the amount

Example: USDPossible values:

assetstring · enumRequired

Crypto asset to pay with

Example: USDTPossible values:

chainstring · enumRequired

Blockchain network

Example: TRONPossible values:

feePaidBystring · enumOptional

Fee paid by: who pays the network fee (merchant or customer)

Possible values:

settlementCurrencystring · enumOptional

Settlement currency (optional)

Possible values:

referencestringOptional

Session reference

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Invalid input or unsupported asset/blockchain

get/api/v1/payments/estimate

GET /api/v1/payments/estimate?amount=100.00&currency=USD&asset=USDT&chain=TRON HTTP/1.1
Host: api.coincircuit.io
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": {
    "fiat": {
      "amount": "100.00",
      "currency": "USD"
    },
    "crypto": {
      "amount": "50.234567",
      "asset": "USDT",
      "chain": "TRON"
    },
    "fees": {
      "networkFee": "1.200000",
      "paidBy": "merchant"
    },
    "conversionRate": "0.00234"
  }
}