Checkout API

Accept payments across Africa

Centry Checkout is a payment orchestration platform that allows you to accept payments via multiple payment providers across Africa. One integration, all payment methods.

Introduction

How Centry Checkout works

Centry Checkout provides a unified API for accepting payments across multiple African countries and payment providers. Instead of integrating with each provider individually, you integrate once with Centry and we handle the routing.

The checkout flow:

1Your server creates a checkout session via our API
2Redirect your customer to the checkout URL (or embed the widget)
3Customer selects their country and payment method
4We route the payment to the appropriate provider
5You receive a webhook when the payment completes

Quick Start

Start accepting payments in minutes

1. Get your API key

Create an account and get your API key from the dashboard. API keys start with cen_.

2. Create a checkout session

Terminalbash

"text">-green-400">curl "text-blue-400">-X POST https://api.centry.io/api/v1/checkout/sessions/ \
  "text-blue-400">-H "Authorization: Api">-Key cen_your_api_key" \
  "text-blue-400">-H "Content">-Type: application/json" \
  "text-blue-400">-d '{
    "amount": "5000.00",
    "currency": "NGN",
    "reference": "ORDER-12345",
    "description": "Premium subscription",
    "customer_email": "customer@example.com",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "webhook_url": "https://yoursite.com/webhooks/centry"
  }'

3. Redirect to checkout

The response includes a checkout_url. Redirect your customer to this URL to complete payment.

Responsejson

{
  "id": "cs_abc123",
  "session_token": "tok_xyz789",
  "checkout_url": "https://checkout.centry.io/checkout/tok_xyz789",
  "status": "pending",
  "expires_at": "2024-01-15T12:00:00Z"
}

4. Handle the webhook

When the payment completes, we'll send a webhook to your server.

Webhook payloadjson

{
  "event": "session.completed",
  "data": {
    "session_id": "cs_abc123",
    "reference": "ORDER-12345",
    "amount": "5000.00",
    "currency": "NGN",
    "status": "completed",
    "payment": {
      "provider": "provider_name",
      "method": "card",
      "provider_reference": "PAY_xyz123"
    }
  }
}

Authentication

Secure your API requests

All API requests must include your API key in the Authorization header. Keep your API key secret and never expose it in client-side code.

Authorization: Api"text-blue-400">-Key cen_your_api_key

Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables to store your key securely.

Hosted Checkout

Redirect customers to our hosted checkout page

The simplest integration method. Create a session and redirect your customer to the checkout URL. We handle the entire payment flow.

server.jsjavascript

500">// Create a checkout session
400">"text-purple-400">const response = 400">"text-purple-400">await fetch(400">'https:500">//api.centry.io/api/v1/checkout/sessions/', {
  method: 400">'POST',
  headers: {
    400">'Authorization': 400">'Api-Key ' + process.env.CENTRY_API_KEY,
    400">'Content-Type': 400">'application/json'
  },
  body: JSON.stringify({
    amount: 400">'5000.00',
    currency: 400">'NGN',
    reference: 400">'ORDER-' + orderId,
    success_url: 400">'https:500">//yoursite.com/success?order=' + orderId,
    cancel_url: 400">'https:500">//yoursite.com/cart'
  })
});

400">"text-purple-400">const { checkout_url } = 400">"text-purple-400">await response.json();

500">// Redirect customer to checkout
res.redirect(checkout_url);

Embedded Widget

Embed checkout in your site with our JavaScript SDK

Keep customers on your site by embedding our checkout widget in a modal. The widget handles country selection, payment methods, and the entire payment flow.

1. Include the SDK

<"text-purple-400">class="text-pink-400">script "text-purple-400">src="https://checkout.centry.io/widget/centry-checkout.js"></"text-purple-400">class="text-pink-400">script>

2. Open the checkout modal

checkout.jsjavascript

500">// After creating a session on your server, open the widget
CentryCheckout.open({
  sessionToken: 400">'tok_xyz789', 500">// From your server
  onSuccess: 400">"text-purple-400">function(data) {
    console.log(400">'Payment successful!');
    window.location.href = 400">'/success';
  },
  onError: 400">"text-purple-400">function(error) {
    console.error(400">'Payment failed:', error);
  },
  onClose: 400">"text-purple-400">function() {
    console.log(400">'Checkout closed');
  }
});

Try it out

See the live example to test the embedded widget.

API Reference

Complete API documentation

Base URL: https://api.centry.io

Create Session

Create a new checkout session

POST

/api/v1/checkout/sessions/

Create a new checkout session for payment collection

Request Parameters

Parameter	Type	Description
`amount`required	string	Payment amount (e.g., "5000.00")
`currency`required	string	ISO 4217 currency code (e.g., "NGN", "KES", "ZAR")
`reference`required	string	Your unique order/invoice reference
`success_url`required	string	URL to redirect after successful payment
`cancel_url`required	string	URL to redirect if customer cancels
`webhook_url`	string	URL to receive webhook notifications
`description`	string	Payment description shown to customer
`customer_email`	string	Pre-fill customer email
`customer_phone`	string	Pre-fill customer phone
`customer_name`	string	Pre-fill customer name
`allowed_countries`	array	Restrict to specific countries (e.g., ["NG", "GH"])
`allowed_providers`	array	Restrict to specific providers (optional)
`metadata`	object	Custom metadata (returned in webhooks)

Example Request

400">"text-purple-400">const response = 400">"text-purple-400">await fetch(400">'https:500">//api.centry.io/api/v1/checkout/sessions/', {
  method: 400">'POST',
  headers: {
    400">'Authorization': 400">'Api-Key cen_your_api_key',
    400">'Content-Type': 400">'application/json'
  },
  body: JSON.stringify({
    amount: 400">'5000.00',
    currency: 400">'NGN',
    reference: 400">'ORDER-12345',
    description: 400">'Premium subscription - Monthly',
    customer_email: 400">'john@example.com',
    success_url: 400">'https:500">//yoursite.com/success',
    cancel_url: 400">'https:500">//yoursite.com/cancel',
    webhook_url: 400">'https:500">//yoursite.com/webhooks/centry',
    metadata: {
      order_id: 400">'12345',
      product: 400">'premium_monthly'
    }
  })
});

Response

{
  "id": "cs_1a2b3c4d5e6f",
  "session_token": "tok_9z8y7x6w5v",
  "checkout_url": "https://checkout.centry.io/checkout/tok_9z8y7x6w5v",
  "reference": "ORDER-12345",
  "amount": "5000.00",
  "currency": "NGN",
  "status": "pending",
  "expires_at": "2024-01-15T13:00:00Z",
  "created_at": "2024-01-15T12:00:00Z"
}

Get Session

Retrieve a checkout session

GET

/api/v1/checkout/sessions/{session_id}/

Retrieve details of an existing checkout session

Responsejson

{
  "id": "cs_1a2b3c4d5e6f",
  "reference": "ORDER-12345",
  "amount": "5000.00",
  "currency": "NGN",
  "status": "completed",
  "payment": {
    "id": "pay_abc123",
    "provider": "provider_name",
    "method": "card",
    "status": "success",
    "provider_reference": "PAY_xyz789"
  },
  "created_at": "2024-01-15T12:00:00Z",
  "completed_at": "2024-01-15T12:05:00Z"
}

Webhooks

Receive real-time payment notifications

Webhooks notify your server when payment events occur. Configure your webhook URL when creating a session or set a default in your dashboard.

Webhook Events

session.completed

Payment was successful

session.failed

Payment failed

session.expired

Session expired without payment

Signature Verification

Webhooks include an HMAC signature in the X-Centry-Signature header. Verify this signature to ensure the webhook is authentic.

webhook_handler.pypython

400">"text-purple-400">import hmac
400">"text-purple-400">import hashlib

400">"text-purple-400">def verify_webhook(payload, signature, webhook_secret):
    expected = hmac.new(
        webhook_secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    400">"text-purple-400">return hmac.compare_digest(expected, signature)

500"># In your webhook handler
@app.post(400">'/webhooks/centry')
400">"text-purple-400">def handle_webhook(request):
    signature = request.headers.get(400">'X-Centry-Signature')
    400">"text-purple-400">if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
        400">"text-purple-400">return {400">'error': 400">'Invalid signature'}, 401

    event = request.json
    400">"text-purple-400">if event[400">'event'] == 400">'session.completed':
        500"># Handle successful payment
        fulfill_order(event[400">'data'][400">'reference'])

    400">"text-purple-400">return {400">'received': 400">"text-purple-400">True}

Supported Countries

Available countries and payment methods

Centry supports payment collection across multiple African countries including Nigeria, Ghana, South Africa, Kenya, Uganda, Tanzania, and Rwanda.

Available payment methods vary by country and include cards, bank transfers, mobile money, and instant EFT. Contact sales for specific country and payment method availability.

Need help? Contact support@centry.io

Website GitHub Dashboard

Checkout API

Accept payments across Africa

Centry Checkout is a payment orchestration platform that allows you to accept payments via multiple payment providers across Africa. One integration, all payment methods.

Quick Start

Get up and running in 5 minutes

API Reference

Explore the full API

Webhooks

Handle payment events

Introduction

How Centry Checkout works

The checkout flow:

1Your server creates a checkout session via our API
2Redirect your customer to the checkout URL (or embed the widget)
3Customer selects their country and payment method
4We route the payment to the appropriate provider
5You receive a webhook when the payment completes

Quick Start

Start accepting payments in minutes

1. Get your API key

Create an account and get your API key from the dashboard. API keys start with cen_.

2. Create a checkout session

Terminalbash

"text">-green-400">curl "text-blue-400">-X POST https://api.centry.io/api/v1/checkout/sessions/ \
  "text-blue-400">-H "Authorization: Api">-Key cen_your_api_key" \
  "text-blue-400">-H "Content">-Type: application/json" \
  "text-blue-400">-d '{
    "amount": "5000.00",
    "currency": "NGN",
    "reference": "ORDER-12345",
    "description": "Premium subscription",
    "customer_email": "customer@example.com",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "webhook_url": "https://yoursite.com/webhooks/centry"
  }'

3. Redirect to checkout

The response includes a checkout_url. Redirect your customer to this URL to complete payment.

Responsejson

{
  "id": "cs_abc123",
  "session_token": "tok_xyz789",
  "checkout_url": "https://checkout.centry.io/checkout/tok_xyz789",
  "status": "pending",
  "expires_at": "2024-01-15T12:00:00Z"
}

4. Handle the webhook

When the payment completes, we'll send a webhook to your server.

Webhook payloadjson

{
  "event": "session.completed",
  "data": {
    "session_id": "cs_abc123",
    "reference": "ORDER-12345",
    "amount": "5000.00",
    "currency": "NGN",
    "status": "completed",
    "payment": {
      "provider": "provider_name",
      "method": "card",
      "provider_reference": "PAY_xyz123"
    }
  }
}

Authentication

Secure your API requests

All API requests must include your API key in the Authorization header. Keep your API key secret and never expose it in client-side code.

Authorization: Api"text-blue-400">-Key cen_your_api_key

Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables to store your key securely.

Hosted Checkout

Redirect customers to our hosted checkout page

The simplest integration method. Create a session and redirect your customer to the checkout URL. We handle the entire payment flow.

server.jsjavascript

500">// Create a checkout session
400">"text-purple-400">const response = 400">"text-purple-400">await fetch(400">'https:500">//api.centry.io/api/v1/checkout/sessions/', {
  method: 400">'POST',
  headers: {
    400">'Authorization': 400">'Api-Key ' + process.env.CENTRY_API_KEY,
    400">'Content-Type': 400">'application/json'
  },
  body: JSON.stringify({
    amount: 400">'5000.00',
    currency: 400">'NGN',
    reference: 400">'ORDER-' + orderId,
    success_url: 400">'https:500">//yoursite.com/success?order=' + orderId,
    cancel_url: 400">'https:500">//yoursite.com/cart'
  })
});

400">"text-purple-400">const { checkout_url } = 400">"text-purple-400">await response.json();

500">// Redirect customer to checkout
res.redirect(checkout_url);

Embedded Widget

Embed checkout in your site with our JavaScript SDK

Keep customers on your site by embedding our checkout widget in a modal. The widget handles country selection, payment methods, and the entire payment flow.

1. Include the SDK

<"text-purple-400">class="text-pink-400">script "text-purple-400">src="https://checkout.centry.io/widget/centry-checkout.js"></"text-purple-400">class="text-pink-400">script>

2. Open the checkout modal

checkout.jsjavascript

500">// After creating a session on your server, open the widget
CentryCheckout.open({
  sessionToken: 400">'tok_xyz789', 500">// From your server
  onSuccess: 400">"text-purple-400">function(data) {
    console.log(400">'Payment successful!');
    window.location.href = 400">'/success';
  },
  onError: 400">"text-purple-400">function(error) {
    console.error(400">'Payment failed:', error);
  },
  onClose: 400">"text-purple-400">function() {
    console.log(400">'Checkout closed');
  }
});

Try it out

See the live example to test the embedded widget.

API Reference

Complete API documentation

Base URL: https://api.centry.io

Create Session

Create a new checkout session

POST

/api/v1/checkout/sessions/

Create a new checkout session for payment collection

Request Parameters

Parameter	Type	Description
`amount`required	string	Payment amount (e.g., "5000.00")
`currency`required	string	ISO 4217 currency code (e.g., "NGN", "KES", "ZAR")
`reference`required	string	Your unique order/invoice reference
`success_url`required	string	URL to redirect after successful payment
`cancel_url`required	string	URL to redirect if customer cancels
`webhook_url`	string	URL to receive webhook notifications
`description`	string	Payment description shown to customer
`customer_email`	string	Pre-fill customer email
`customer_phone`	string	Pre-fill customer phone
`customer_name`	string	Pre-fill customer name
`allowed_countries`	array	Restrict to specific countries (e.g., ["NG", "GH"])
`allowed_providers`	array	Restrict to specific providers (optional)
`metadata`	object	Custom metadata (returned in webhooks)

Example Request

400">"text-purple-400">const response = 400">"text-purple-400">await fetch(400">'https:500">//api.centry.io/api/v1/checkout/sessions/', {
  method: 400">'POST',
  headers: {
    400">'Authorization': 400">'Api-Key cen_your_api_key',
    400">'Content-Type': 400">'application/json'
  },
  body: JSON.stringify({
    amount: 400">'5000.00',
    currency: 400">'NGN',
    reference: 400">'ORDER-12345',
    description: 400">'Premium subscription - Monthly',
    customer_email: 400">'john@example.com',
    success_url: 400">'https:500">//yoursite.com/success',
    cancel_url: 400">'https:500">//yoursite.com/cancel',
    webhook_url: 400">'https:500">//yoursite.com/webhooks/centry',
    metadata: {
      order_id: 400">'12345',
      product: 400">'premium_monthly'
    }
  })
});

Response

{
  "id": "cs_1a2b3c4d5e6f",
  "session_token": "tok_9z8y7x6w5v",
  "checkout_url": "https://checkout.centry.io/checkout/tok_9z8y7x6w5v",
  "reference": "ORDER-12345",
  "amount": "5000.00",
  "currency": "NGN",
  "status": "pending",
  "expires_at": "2024-01-15T13:00:00Z",
  "created_at": "2024-01-15T12:00:00Z"
}

Get Session

Retrieve a checkout session

GET

/api/v1/checkout/sessions/{session_id}/

Retrieve details of an existing checkout session

Responsejson

{
  "id": "cs_1a2b3c4d5e6f",
  "reference": "ORDER-12345",
  "amount": "5000.00",
  "currency": "NGN",
  "status": "completed",
  "payment": {
    "id": "pay_abc123",
    "provider": "provider_name",
    "method": "card",
    "status": "success",
    "provider_reference": "PAY_xyz789"
  },
  "created_at": "2024-01-15T12:00:00Z",
  "completed_at": "2024-01-15T12:05:00Z"
}

Webhooks

Receive real-time payment notifications

Webhooks notify your server when payment events occur. Configure your webhook URL when creating a session or set a default in your dashboard.

Webhook Events

session.completed

Payment was successful

session.failed

Payment failed

session.expired

Session expired without payment

Signature Verification

Webhooks include an HMAC signature in the X-Centry-Signature header. Verify this signature to ensure the webhook is authentic.

webhook_handler.pypython

400">"text-purple-400">import hmac
400">"text-purple-400">import hashlib

400">"text-purple-400">def verify_webhook(payload, signature, webhook_secret):
    expected = hmac.new(
        webhook_secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    400">"text-purple-400">return hmac.compare_digest(expected, signature)

500"># In your webhook handler
@app.post(400">'/webhooks/centry')
400">"text-purple-400">def handle_webhook(request):
    signature = request.headers.get(400">'X-Centry-Signature')
    400">"text-purple-400">if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
        400">"text-purple-400">return {400">'error': 400">'Invalid signature'}, 401

    event = request.json
    400">"text-purple-400">if event[400">'event'] == 400">'session.completed':
        500"># Handle successful payment
        fulfill_order(event[400">'data'][400">'reference'])

    400">"text-purple-400">return {400">'received': 400">"text-purple-400">True}

Supported Countries

Available countries and payment methods

Centry supports payment collection across multiple African countries including Nigeria, Ghana, South Africa, Kenya, Uganda, Tanzania, and Rwanda.

Available payment methods vary by country and include cards, bank transfers, mobile money, and instant EFT. Contact sales for specific country and payment method availability.

Need help? Contact support@centry.io

Website GitHub Dashboard