Charge Payment

curl -X POST https://api.chidori.africa/enterprise-service/api/payments/charge \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryId": "abc123-def456-ghi789",
    "reference": "order_12345_payment"
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/payments/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryId: 'abc123-def456-ghi789',
    reference: 'order_12345_payment'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.chidori.africa/enterprise-service/api/payments/charge',
    headers={
        'X-API-Key': 'sk_live_xxx.yyy',
        'Content-Type': 'application/json'
    },
    json={
        'deliveryId': 'abc123-def456-ghi789',
        'reference': 'order_12345_payment'
    }
)

data = response.json()

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": null,
    "amount": 2500,
    "paymentChannel": "Wallet",
    "reference": "order_12345_payment"
  }
}

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": "1a4f1a5e-5b79-4c4a-a0d4-4c5c7b7bb1aa",
    "amount": 7500,
    "paymentChannel": "Wallet",
    "reference": "bulk_order_payment"
  }
}

{
  "status": false,
  "message": "Insufficient wallet balance"
}

{
  "status": false,
  "message": "Delivery not found"
}

curl -X POST https://api.chidori.africa/enterprise-service/api/payments/charge \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryId": "abc123-def456-ghi789",
    "reference": "order_12345_payment"
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/payments/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryId: 'abc123-def456-ghi789',
    reference: 'order_12345_payment'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.chidori.africa/enterprise-service/api/payments/charge',
    headers={
        'X-API-Key': 'sk_live_xxx.yyy',
        'Content-Type': 'application/json'
    },
    json={
        'deliveryId': 'abc123-def456-ghi789',
        'reference': 'order_12345_payment'
    }
)

data = response.json()

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": null,
    "amount": 2500,
    "paymentChannel": "Wallet",
    "reference": "order_12345_payment"
  }
}

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": "1a4f1a5e-5b79-4c4a-a0d4-4c5c7b7bb1aa",
    "amount": 7500,
    "paymentChannel": "Wallet",
    "reference": "bulk_order_payment"
  }
}

{
  "status": false,
  "message": "Insufficient wallet balance"
}

{
  "status": false,
  "message": "Delivery not found"
}

Overview

Process payment for a delivery (or all deliveries in a bulk) from your wallet balance. This endpoint supports idempotency through the reference parameter.

Required permission: payment:create

Endpoint

POST /api/payments/charge

Request

Headers

string

required

Your Chidori API key

string

required

Must be application/json

Body parameters

string

required

The delivery ID to pay for. If this delivery belongs to a bulk, all deliveries in the bulk will be paid.

string

required

Client-generated idempotency key. Re-using the same reference will not double-charge.

number

Optional amount verification. If provided, must match the computed delivery amount.

Response

Success response

boolean

Always true for successful requests

object

Show properties

string

The delivery ID that was paid

string

Bulk ID if this was a bulk payment (null for single deliveries)

number

Total amount charged in Naira

string

Payment method used (e.g., “Wallet”)

string

Your idempotency reference

Examples

Single delivery payment

curl -X POST https://api.chidori.africa/enterprise-service/api/payments/charge \
  -H "X-API-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryId": "abc123-def456-ghi789",
    "reference": "order_12345_payment"
  }'

const response = await fetch('https://api.chidori.africa/enterprise-service/api/payments/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_xxx.yyy',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryId: 'abc123-def456-ghi789',
    reference: 'order_12345_payment'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.chidori.africa/enterprise-service/api/payments/charge',
    headers={
        'X-API-Key': 'sk_live_xxx.yyy',
        'Content-Type': 'application/json'
    },
    json={
        'deliveryId': 'abc123-def456-ghi789',
        'reference': 'order_12345_payment'
    }
)

data = response.json()

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": null,
    "amount": 2500,
    "paymentChannel": "Wallet",
    "reference": "order_12345_payment"
  }
}

{
  "status": true,
  "data": {
    "deliveryId": "abc123-def456-ghi789",
    "bulk": "1a4f1a5e-5b79-4c4a-a0d4-4c5c7b7bb1aa",
    "amount": 7500,
    "paymentChannel": "Wallet",
    "reference": "bulk_order_payment"
  }
}

{
  "status": false,
  "message": "Insufficient wallet balance"
}

{
  "status": false,
  "message": "Delivery not found"
}

Bulk payment behavior

When you pay for a delivery that belongs to a bulk:

The system identifies the bulk ID from the delivery
Calculates the total amount for all unpaid deliveries in that bulk
Charges the full bulk total from your wallet
Marks all deliveries in the bulk as paid

You can pass any deliveryId from the bulk—the system will find and charge the entire bulk.

Idempotency

The reference parameter ensures safe retries:

If a request fails due to network issues, you can safely retry with the same reference
If the original request succeeded, the retry will return the same response without double-charging
Use unique references for each distinct payment (e.g., include your order ID)

// Good: Unique reference per order
const reference = `order_${orderId}_delivery_payment`;

// Bad: Reusing references across different orders
const reference = 'payment'; // Don't do this!

Error handling

Status	Message	Action
`400`	Validation error	Check request parameters
`401`	Unauthorized	Verify API key
`402`	Insufficient wallet balance	Add funds to wallet
`403`	Forbidden	Check API key permissions
`404`	Delivery not found	Verify delivery ID

Wallet management

Ensure your wallet has sufficient balance before attempting payment. Fund your wallet through the Chidori Dashboard.

Overview

Pricing

Deliveries

Checkout

Payments

Webhooks

Real-time

Overview

Endpoint

Request

Headers

Body parameters

Response

Success response

Examples

Single delivery payment

Bulk payment behavior

Idempotency

Error handling

Wallet management

Next steps

List Transactions

Get Delivery

​Overview

​Endpoint

​Request

​Headers

​Body parameters

​Response

​Success response

​Examples

​Single delivery payment

​Bulk payment behavior

​Idempotency

​Error handling

​Wallet management

​Next steps

List Transactions

Get Delivery

Overview

Endpoint

Request

Headers

Body parameters

Response

Success response

Examples

Single delivery payment

Bulk payment behavior

Idempotency

Error handling

Wallet management

Next steps