Payment Pages

Create and manage hosted payment pages

List payment pages

get

/api/v1/payments/pages

Returns all payment pages.

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 payment page title

Example: Monthly Subscription

isActivebooleanOptional

Filter by active status

Example: true

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

401

Unauthorized

403

Forbidden

get/api/v1/payments/pages

GET /api/v1/payments/pages 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": "1234567890",
      "merchant": {
        "businessName": "Acme Corporation",
        "logoUrl": "https://example.com/logo.png"
      },
      "title": "Donation Page",
      "description": "Support our cause with a donation",
      "isActive": true,
      "currency": "NGN",
      "minAmount": "1000",
      "enableQuantity": false,
      "bankAccounts": [
        {
          "isTemporary": true,
          "notes": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "accountName": "John Doe Business Ltd",
          "accountNumber": "****4852",
          "bankName": "Access Bank",
          "bankCode": "044",
          "accountType": "savings",
          "currency": "NGN",
          "nickName": "Main Account",
          "default": true,
          "isTrusted": false,
          "createdAt": "2024-01-01T00:00:00.000Z",
          "updatedAt": "2024-01-01T00:00:00.000Z"
        }
      ],
      "products": [
        {
          "id": "uuid-string",
          "title": "Standard Room",
          "description": "Single bed, breakfast included",
          "price": "50000.00",
          "isActive": true,
          "sortOrder": 0,
          "imageUrl": "https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
          "createdAt": "2024-01-15T10:30:00.000Z",
          "updatedAt": "2024-01-15T10:30:00.000Z"
        }
      ],
      "imageUrl": "https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
      "url": "https://checkout.coincircuit.io/static/1234567890",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 42,
    "totalPages": 5
  }
}

Create payment page

post

/api/v1/payments/pages

Creates a new payment page.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Body

titlestring · min: 1 · max: 50Required

Title for the payment page

Example: My Store Checkout

descriptionstringOptional

Description of the payment page

Example: Payment page for my online store

isActivebooleanRequired

Whether the payment page is active

Default: trueExample: true

minAmountnumberOptional

Minimum amount for payments

Example: 100

currencystring · enumRequired

Fiat currency for this payment page

Example: USDPossible values:

bankAccountIdsstring[]Optional

Array of bank account IDs to associate with this payment page

Example: ["uuid-1","uuid-2"]

enableQuantitybooleanOptional

Enable quantity selector (e.g. nights, units). Only valid when products are defined.

Responses

201Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Invalid input

401

Unauthorized

403

Forbidden

409

Conflict - Nickname already exists

post/api/v1/payments/pages

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

{
  "title": "My Store Checkout",
  "description": "Payment page for my online store",
  "isActive": true,
  "minAmount": 100,
  "currency": "USD",
  "bankAccountIds": [
    "uuid-1",
    "uuid-2"
  ],
  "products": [
    {
      "title": "Standard Room",
      "description": "Single bed, breakfast included",
      "price": 50000,
      "isActive": true,
      "sortOrder": 0
    },
    {
      "title": "Deluxe Room",
      "description": "King bed, breakfast & dinner",
      "price": 80000,
      "isActive": true,
      "sortOrder": 1
    }
  ],
  "enableQuantity": true
}

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "1234567890",
    "merchant": {
      "businessName": "Acme Corporation",
      "logoUrl": "https://example.com/logo.png"
    },
    "title": "Donation Page",
    "description": "Support our cause with a donation",
    "isActive": true,
    "currency": "NGN",
    "minAmount": "1000",
    "enableQuantity": false,
    "bankAccounts": [
      {
        "isTemporary": true,
        "notes": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "accountName": "John Doe Business Ltd",
        "accountNumber": "****4852",
        "bankName": "Access Bank",
        "bankCode": "044",
        "accountType": "savings",
        "currency": "NGN",
        "nickName": "Main Account",
        "default": true,
        "isTrusted": false,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "products": [
      {
        "id": "uuid-string",
        "title": "Standard Room",
        "description": "Single bed, breakfast included",
        "price": "50000.00",
        "isActive": true,
        "sortOrder": 0,
        "imageUrl": "https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "imageUrl": "https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
    "url": "https://checkout.coincircuit.io/static/1234567890",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Retrieve payment page by reference

get

/api/v1/payments/pages/{reference}/sessions

Returns the payment page for the given reference.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters

referencestringRequired

Payment page reference

Example: abc123def456

Header parameters

x-api-keystringOptional

API key for authentication

Example: pk_live_1234567890abcdef

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

404

Payment page not found

500

Internal server error

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

GET /api/v1/payments/pages/{reference}/sessions HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "Success",
  "data": {
    "merchant": {
      "businessName": "Acme Corporation",
      "logoUrl": "https://example.com/logo.png"
    },
    "title": "text",
    "description": "text",
    "currency": "text",
    "minAmount": "text",
    "enableQuantity": true,
    "products": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Basic Plan",
        "price": "100000",
        "description": "Basic subscription plan with essential features",
        "sortOrder": 1,
        "imageUrl": "https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg"
      }
    ],
    "bankAccounts": [
      {
        "id": "bacc-123e4567-e89b-12d3-a456-426614174000",
        "accountName": "John Smith",
        "accountNumber": "******4321",
        "bankName": "GT Bank"
      }
    ],
    "imageUrl": "https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
    "url": "https://checkout.coincircuit.io/static/1234567890"
  }
}

Delete payment page

delete

/api/v1/payments/pages/{id}

Deletes the payment page.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters

idstringRequired

Payment page ID

Example: uuid-string

Responses

200Success

No content

401

Unauthorized

403

Forbidden

404

Payment page not found

delete/api/v1/payments/pages/{id}

DELETE /api/v1/payments/pages/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*

No content

Update payment page

patch

/api/v1/payments/pages/{id}

Updates the payment page.

Authorizations

x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters

idstringRequired

Payment page ID

Example: uuid-string

Body

titlestring · min: 1 · max: 50Optional

Title for the payment page

Example: My Store Checkout

descriptionstringOptional

Description of the payment page

Example: Payment page for my online store

isActivebooleanOptional

Whether the payment page is active

Default: trueExample: true

minAmountnumberOptional

Minimum amount for payments

Example: 100

currencystring · enumOptional

Fiat currency for this payment page

Example: USDPossible values:

bankAccountIdsstring[]Optional

Array of bank account IDs to associate with this payment page

Example: ["uuid-1","uuid-2"]

enableQuantitybooleanOptional

Enable quantity selector (e.g. nights, units). Only valid when products are defined.

Responses

200Success

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

messagestringRequired

Response message

Example: Success

400

Bad request

401

Unauthorized

403

Forbidden

404

Payment page not found

409

Conflict - Nickname already exists

patch/api/v1/payments/pages/{id}

PATCH /api/v1/payments/pages/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 429

{
  "title": "My Store Checkout",
  "description": "Payment page for my online store",
  "isActive": true,
  "minAmount": 100,
  "currency": "USD",
  "bankAccountIds": [
    "uuid-1",
    "uuid-2"
  ],
  "products": [
    {
      "title": "Standard Room",
      "description": "Single bed, breakfast included",
      "price": 50000,
      "isActive": true,
      "sortOrder": 0
    },
    {
      "title": "Deluxe Room",
      "description": "King bed, breakfast & dinner",
      "price": 80000,
      "isActive": true,
      "sortOrder": 1
    }
  ],
  "enableQuantity": true
}

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "1234567890",
    "merchant": {
      "businessName": "Acme Corporation",
      "logoUrl": "https://example.com/logo.png"
    },
    "title": "Donation Page",
    "description": "Support our cause with a donation",
    "isActive": true,
    "currency": "NGN",
    "minAmount": "1000",
    "enableQuantity": false,
    "bankAccounts": [
      {
        "isTemporary": true,
        "notes": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "accountName": "John Doe Business Ltd",
        "accountNumber": "****4852",
        "bankName": "Access Bank",
        "bankCode": "044",
        "accountType": "savings",
        "currency": "NGN",
        "nickName": "Main Account",
        "default": true,
        "isTrusted": false,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "products": [
      {
        "id": "uuid-string",
        "title": "Standard Room",
        "description": "Single bed, breakfast included",
        "price": "50000.00",
        "isActive": true,
        "sortOrder": 0,
        "imageUrl": "https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "imageUrl": "https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg",
    "url": "https://checkout.coincircuit.io/static/1234567890",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

PreviousRefunds

NextMiscellaneous

Last updated 1 hour ago

Was this helpful?