Create Checkout

curl -X POST https://api.chidori.africa/enterprise-service/api/checkout/create-checkout \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Mama Ada Kitchen",
    "customerEmail": "[email protected]",
    "customerName": "Ada",
    "senderPhone": "08012345678",
    "pickupAddress": "5 Marina St, Lagos Island",
    "pickupLat": 6.4541,
    "pickupLon": 3.3947,
    "externalReference": "order_12345",
    "redirectUrl": "https://shop.example.com/thank-you",
    "goods": [
      { "id": "sku_1", "name": "Jollof platter", "quantity": 2, "price": 6000 }
    ]
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/checkout/create-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    businessName: 'Mama Ada Kitchen',
    customerEmail: '[email protected]',
    senderPhone: '08012345678',
    pickupAddress: '5 Marina St, Lagos Island',
    pickupLat: 6.4541,
    pickupLon: 3.3947,
    externalReference: 'order_12345'
  })
});

const data = await response.json();

{
  "status": true,
  "data": {
    "token": "v9aQ2k7r...base64url",
    "url": "https://chidori.africa/checkout/v9aQ2k7r...base64url",
    "status": "awaiting_address"
  }
}

{
  "message": "Collecting for goods requires a verified payment profile. Complete verification first."
}

curl -X POST https://api.chidori.africa/enterprise-service/api/checkout/create-checkout \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Mama Ada Kitchen",
    "customerEmail": "[email protected]",
    "customerName": "Ada",
    "senderPhone": "08012345678",
    "pickupAddress": "5 Marina St, Lagos Island",
    "pickupLat": 6.4541,
    "pickupLon": 3.3947,
    "externalReference": "order_12345",
    "redirectUrl": "https://shop.example.com/thank-you",
    "goods": [
      { "id": "sku_1", "name": "Jollof platter", "quantity": 2, "price": 6000 }
    ]
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/checkout/create-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    businessName: 'Mama Ada Kitchen',
    customerEmail: '[email protected]',
    senderPhone: '08012345678',
    pickupAddress: '5 Marina St, Lagos Island',
    pickupLat: 6.4541,
    pickupLon: 3.3947,
    externalReference: 'order_12345'
  })
});

const data = await response.json();

{
  "status": true,
  "data": {
    "token": "v9aQ2k7r...base64url",
    "url": "https://chidori.africa/checkout/v9aQ2k7r...base64url",
    "status": "awaiting_address"
  }
}

{
  "message": "Collecting for goods requires a verified payment profile. Complete verification first."
}

Overview

Create a hosted checkout and get back a link to send your customer. On the Chidori-hosted page the customer picks a delivery address, the delivery fee is computed, and they pay by bank transfer. When payment lands, Chidori auto-creates the delivery and sends you a checkout.paid webhook. Two modes, chosen by whether you include goods:

Delivery-only — omit goods. The customer pays only the Chidori delivery fee.
Goods + delivery — include goods. The customer pays for your products plus delivery; your goods total settles directly to your bank via your Paystack subaccount. Requires a verified payment profile.

Required permission: payment:charge

Collecting for goods requires verification

Including goods collects money for your products (not just delivery), which settles to your bank via your Paystack subaccount. To unlock this you must first have an approved payment profile:

Submit your CAC certificate image, NIN, business name and settlement bank account (via the dashboard).
Chidori reviews and verifies the submission; on approval a Paystack subaccount is created for you.
Once your profile status is verified, create-checkout requests that include goods are accepted.

Until then, including goods returns 403 with:

{ "message": "Collecting for goods requires a verified payment profile. Complete verification first." }

Delivery-only checkouts need no verification — omit goods and you can create checkouts immediately. Verification is required only to collect for goods.

Endpoint

POST /api/checkout/create-checkout

Request

Headers

string

required

Your Chidori API key

string

required

Must be application/json

Body parameters

string

required

Your business name — shown on the checkout page and in customer emails.

string

required

Customer email. The checkout link is emailed here, and so is the payment confirmation.

string

required

Sender (pickup) contact phone.

string

required

Human-readable pickup address.

number

required

Pickup latitude.

number

required

Pickup longitude.

string

Customer name (optional).

string

Where to send the customer after successful payment. Chidori appends ?reference=&checkout=&status=success. If omitted, the page shows a success screen with a delivery-tracking link.

string

Your idempotency key. Re-using it returns the same checkout instead of creating a new one.

array

Line items to collect for. Omit for a delivery-only checkout.

Show item

string

Your product/SKU id

string

required

Item name

number

required

Quantity (> 0)

number

required

Unit price in Naira

Response

boolean

Always true for successful requests

object

Show properties

string

The checkout’s public token

string

The hosted checkout URL to send your customer (https://chidori.africa/checkout/{token})

string

Checkout status — awaiting_address for a new checkout

Examples

curl -X POST https://api.chidori.africa/enterprise-service/api/checkout/create-checkout \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Mama Ada Kitchen",
    "customerEmail": "[email protected]",
    "customerName": "Ada",
    "senderPhone": "08012345678",
    "pickupAddress": "5 Marina St, Lagos Island",
    "pickupLat": 6.4541,
    "pickupLon": 3.3947,
    "externalReference": "order_12345",
    "redirectUrl": "https://shop.example.com/thank-you",
    "goods": [
      { "id": "sku_1", "name": "Jollof platter", "quantity": 2, "price": 6000 }
    ]
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/checkout/create-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    businessName: 'Mama Ada Kitchen',
    customerEmail: '[email protected]',
    senderPhone: '08012345678',
    pickupAddress: '5 Marina St, Lagos Island',
    pickupLat: 6.4541,
    pickupLon: 3.3947,
    externalReference: 'order_12345'
  })
});

const data = await response.json();

{
  "status": true,
  "data": {
    "token": "v9aQ2k7r...base64url",
    "url": "https://chidori.africa/checkout/v9aQ2k7r...base64url",
    "status": "awaiting_address"
  }
}

{
  "message": "Collecting for goods requires a verified payment profile. Complete verification first."
}

What happens next

Send the link

Share data.url with your customer (Chidori also emails it to customerEmail).

Customer pays

The customer enters their delivery address, gets a total, and pays by bank transfer on the hosted page.

You get notified

On payment, Chidori auto-creates the delivery and sends a checkout.paid webhook. Reconcile using your externalReference.

Idempotency

Pass an externalReference unique to the order. Re-sending create-checkout with the same reference returns the existing checkout rather than creating a duplicate.

Error handling

Status	Example message	Action
`400`	`businessName is required` / `pickupLat and pickupLon are required`	Provide all required fields
`400`	`Each goods item needs name, quantity > 0, and price >= 0`	Fix the `goods` items
`401`	`Unauthorized`	Verify API key
`403`	`Collecting for goods requires a verified payment profile. Complete verification first.`	Complete payment-profile verification

Next steps

Webhooks

Handle the checkout.paid event

Get Delivery

Track the auto-created delivery

Overview

Pricing

Deliveries

Checkout

Payments

Webhooks

Real-time

Create Checkout

Overview

Collecting for goods requires verification

Endpoint

Request

Headers

Body parameters

Response

Examples

What happens next

Idempotency

Error handling

Next steps

Webhooks

Get Delivery

​Overview

​Collecting for goods requires verification

​Endpoint

​Request

​Headers

​Body parameters

​Response

​Examples

​What happens next

​Idempotency

​Error handling

​Next steps

Webhooks

Get Delivery

Overview

Collecting for goods requires verification

Endpoint

Request

Headers

Body parameters

Response

Examples

What happens next

Idempotency

Error handling

Next steps