Payins, Payouts & Balances

Introduction

How Centry Merchant API works

The Centry Merchant API gives you programmatic access to payins (money in) and payouts (money out) across multiple African payment providers. Each transaction automatically calculates fees, updates your balance, and optionally syncs to your ERP system.

Quick Start

Your first payin in under 5 minutes

curl -X POST https://api.getcentry.io/v1/payins \
  -H "Authorization: Merchant-Key mk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "UG",
    "currency_code": "UGX",
    "amount": 50000,
    "payment_method": "mobile_money",
    "gateway": "mtn",
    "customer_name": "Jane Doe",
    "customer_phone": "+256700000000",
    "reference": "ORDER-1234",
    "create_invoice": false
  }'

import requests

resp = requests.post(
    "https://api.getcentry.io/v1/payins",
    headers={"Authorization": "Merchant-Key mk_test_xxx"},
    json={
        "country_code": "UG",
        "currency_code": "UGX",
        "amount": 50000,
        "payment_method": "mobile_money",
        "gateway": "mtn",
        "customer_name": "Jane Doe",
        "customer_phone": "+256700000000",
        "reference": "ORDER-1234",
        "create_invoice": False,
    },
)
payin = resp.json()
print(payin["id"], payin["status"])

pip install pycentry

pip install --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  pycentry

pip install 'pycentry==0.1.1'

from centry import Client

client = Client(merchant_key="mk_test_xxx")

payin = client.payins.create(
    country_code="UG",
    currency_code="UGX",
    amount=50000,
    payment_method="mobile_money",
    gateway="mtn",
    customer_name="Jane Doe",
    customer_phone="+256700000000",
    reference="ORDER-1234",
    create_invoice=False,
)
print(payin.id, payin.status, payin.net_amount)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "50000.00",
  "currency_code": "UGX",
  "payment_method": "mobile_money",
  "gateway": "mtn_momo",
  "centry_fee": "250.00",
  "gateway_fee": "500.00",
  "fee_amount": "750.00",
  "net_amount": "49250.00",
  "status": "pending",
  "reference": "ORDER-1234",
  "create_invoice": true,
  "invoice": null,
  "created_at": "2026-04-14T10:30:00Z"
}

Authentication

Secure your API requests

Every request must include your API key in the Authorization header:

Authorization: Merchant-Key mk_live_xxxxxxxxxxxxxxxxxxxxx

Or alternatively:

X-Merchant-Key: mk_live_xxxxxxxxxxxxxxxxxxxxx

Environments

Sandbox vs production

API Keys

How keys work

API keys are issued per merchant by Centry admins. Each key carries these attributes:

Provider Accounts

How gateway credentials & fees are managed

A ProviderAccount is the unified record for one payment gateway (Ozow, MTN Mobile Money, Airtel Money, CallPay, M-Pesa). It stores both sandbox and production credentials in a single record, plus the gateway's pass-through fees. Centry resolves the right credentials at request time based on your API key's environment — you never have to switch between separate sandbox/live accounts.

Fields

Endpoints

Payins

Money in from customers

pending → processing → completed
                    ↓
                  failed → cancelled / refunded

Payouts

Money out to recipients

{
  "country_code": "UG",
  "amount": 100000,
  "payment_method": "mobile_money",
  "gateway": "mtn_momo",
  "recipient_name": "John Supplier",
  "recipient_phone": "+256700000001",
  "reference": "PAY-9876",
  "create_bill": true
}

{
  "country_code": "ZA",
  "amount": 250000,
  "currency_code": "ZAR",
  "payment_method": "bank_transfer",
  "gateway": "ozow",
  "recipient_name": "Acme Suppliers Ltd",
  "recipient_account_number": "1234567890",
  "recipient_bank_name": "Standard Bank",
  "recipient_bank_code": "051001",
  "create_bill": true
}

{
  "country_code": "UG",
  "amount": 0,
  "payment_method": "mobile_money",
  "gateway": "mtn_momo",
  "recipient_name": "Bulk batch",
  "is_bulk": true,
  "bulk_recipients": [
    { "name": "Alice", "phone": "+256701111111", "amount": 50000 },
    { "name": "Bob",   "phone": "+256702222222", "amount": 75000 }
  ]
}

draft → pending → approved → processing → completed
              ↓                        ↓
           rejected                  failed

Balance

Check your available funds

Returns one row per country + currency. If the API key is country-scoped, only that country's balance is returned.

[
  {
    "country_code": "UG",
    "country_name": "Uganda",
    "currency_code": "UGX",
    "available_balance": "1250000.00",
    "pending_balance": "75000.00",
    "reserved_balance": "100000.00",
    "total_balance": "1325000.00",
    "lifetime_payin_volume": "5000000.00",
    "lifetime_payout_volume": "2500000.00",
    "lifetime_centry_fees": "37500.00",
    "lifetime_gateway_fees": "75000.00",
    "last_movement_at": "2026-04-14T10:30:00Z"
  }
]

Balance states

Fees

Transparent, itemized pricing

Centry breaks out fees into two components stored on every payin and payout:

Where rates come from

• • Centry fee — Merchant.payin_fee_percentage / payout_fee_percentage, falling back to platform defaults from settings
• • Gateway fee — ProviderAccount.fee_percentage / fee_fixed for the gateway resolved from the request

Payin fee calculation

centry_fee  = amount × Merchant.payin_fee_percentage%  + Merchant.payin_fee_fixed
gateway_fee = amount × ProviderAccount.fee_percentage% + ProviderAccount.fee_fixed
net_amount  = amount − (centry_fee + gateway_fee)   ← what you receive

Payout fee calculation

centry_fee  = amount × Merchant.payout_fee_percentage% + Merchant.payout_fee_fixed
gateway_fee = amount × ProviderAccount.fee_percentage% + ProviderAccount.fee_fixed
net_amount  = amount + (centry_fee + gateway_fee)   ← what you pay in total

ERP Bridge

Auto-sync to your accounting system

Set create_invoice: true on a payin or create_bill: true on a payout. When the payment completes, Centry creates a record in your connected ERP automatically.

Idempotency

Safely retry payins and payouts without double-charging

Network blips happen. To make a retry safe, send an Idempotency-Key header on every POST to /v1/payins and /v1/payouts. If the same key reaches us twice, we replay the original response instead of creating a second transaction.

• The key is an opaque client-generated string — a UUIDv4 is the safe default. 8–255 chars, from A-Z a-z 0-9 _ - : .
• Keys are scoped per merchant and remembered for 24 hours.
• Reusing a key with a different request body returns 409 idempotency_key_reused.
• If the original request is still in-flight, retries get 409 idempotent_request_in_flight — back off and retry shortly.
• 5xx responses are not cached, so you can safely retry after server errors.

curl -X POST https://api.getcentry.io/v1/payins \
  -H "Authorization: Merchant-Key mk_live_xxx" \
  -H "Idempotency-Key: 9b2c1d6e-7a3f-4d4e-b1c8-2f6a8c0d4e11" \
  -H "Content-Type: application/json" \
  -d '{ "country_code": "UG", "amount": 50000, "payment_method": "mobile_money",
        "gateway": "mtn", "customer_phone": "+256700000000", "reference": "ORDER-1234" }'

Strongly recommended for production. Without an Idempotency-Key, a network retry can create a duplicate transaction — and for payouts, that means money out twice.

Webhooks

Receive payment events in real time

Centry POSTs to your configured webhook URL whenever payment status changes. Every request is signed with HMAC-SHA256 so you can prove it came from us and wasn't tampered with in transit.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "payin.completed",
  "created": 1713090900,
  "livemode": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_id": "b2d7...",
    "status": "completed",
    "amount": "50000.00",
    "currency": "UGX",
    "fee_amount": "750.00",
    "net_amount": "49250.00",
    "gateway": "mtn",
    "payment_method": "mobile_money",
    "reference": "ORDER-1234",
    "customer_phone": "+256700000000",
    "created_at": "2026-04-14T10:35:00+00:00"
  }
}

Centry-Signature: t=1713090900,v1=5257a8695...

const crypto = require('crypto');

function verifyCentryWebhook(rawBody, headerValue, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    headerValue.split(',').map(p => p.split('=').map(s => s.trim()))
  );
  const t = parseInt(parts.t, 10);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1 || '', 'hex'),
  );
}

// Express: use express.raw({ type: 'application/json' }) so req.body stays
// as a Buffer — JSON-parsing before verification will break the signature.
app.post('/webhooks/centry', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyCentryWebhook(
    req.body.toString('utf8'),
    req.get('Centry-Signature'),
    process.env.CENTRY_WEBHOOK_SECRET,
  );
  if (!ok) return res.status(400).send('invalid signature');
  const event = JSON.parse(req.body.toString('utf8'));
  // ... handle event ...
  res.status(200).send();
});

Error Codes

HTTP status codes and messages

Error response format

{
  "error": "Insufficient balance: available 10000 < required 50750"
}

Rate Limits

API usage limits

• • 60 requests/minute per API key prefix
• • Rate limit information returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining
• • Exceeding the limit returns 429 Too Many Requests
• • Contact support for higher limits on production workloads

OpenAPI / Swagger

Interactive API reference with Try it out

The public API schema is published as OpenAPI 3.0 and rendered in Swagger UI + ReDoc. Both are served unauthenticated, so you can browse without a dashboard session. Point your code generator (Postman, Insomnia, openapi-generator, orval, …) at the raw schema URL.

Going-Live Checklist

Work through these in order before flipping mk_test_ for mk_live_

We've seen most launch incidents trace back to one of these items being skipped. Tick each one in your dashboard before pointing real customer traffic at us.

1. 1

   Confirm sandbox flow end-to-end

   Create a payin and payout against mk_test_, watch them complete via the gateway sandbox. Use the Python demo or pycentry SDK if you want a working starting point.

2. 2

   Set webhook_url + generate signing secret

   Merchant detail → Webhooks tab. URL must be https; private/loopback/metadata IPs are rejected. Click "Generate" to mint a webhook_secret — copy it now, it is shown once.

3. 3

   Verify signatures + send a test event

   Wire verify_centry_signature into your receiver. From the dashboard, click "Send test" — a webhook.test event arrives. Confirm your handler validates and 2xxs within 10s.

4. 4

   Replay one event, then trigger a real one

   Use the Replay button in the Webhooks tab to verify your idempotent handling. Then run a real sandbox payin and verify the payin.completed event lands.

5. 5

   Add IP whitelist to the production key

   Integration tab → Edit Key Limits. Paste the CIDR of your egress IPs. Empty whitelist on mk_live_ is dangerous and we will warn you in the UI.

6. 6

   Set per-key spend caps

   Same dialog: single_txn_cap (largest single payin/payout you ever expect) and daily_payout_cap (rolling 24h budget). A leaked key with caps is a contained incident.

7. 7

   Configure payout approval threshold (recommended)

   For your organization, set merchant_payout_approval_threshold per currency. Payouts above the threshold flip to pending and need a human click — small operational cost, huge fraud win.

8. 8

   Send Idempotency-Key on every payin and payout

   UUIDv4 per logical request. Without it, a network retry can charge or pay out twice. We also send 409 idempotency_key_reused if the same key arrives with a different body — surface this to ops, do not auto-retry.

9. 9

   Rotate the sandbox key, mint a fresh production key

   Never re-use sandbox keys in live. Generate a new mk_live_ explicitly for production, with the right country scope, permission set, IP whitelist, and caps.

10. 10

    Run reconciliation against your accounting system

    For your first week of live traffic, reconcile our payin/payout records against your books daily. Confirm fees and net amounts match. Stuck transactions are auto-failed after 30m and the merchant balance released.

Security Best Practices

• Use separate keys per environment. Never mix sandbox and production credentials.
• Scope keys to a country. If an integrator only handles Uganda, their key shouldn't be able to transact in South Africa.
• Always verify webhook signatures. Reject webhooks without a valid signature header.
• Send an Idempotency-Key on every payin and payout. Without it, a network retry can charge or pay out twice. See Idempotency.
• Attach spend caps to production keys. A single_txn_cap and daily_payout_cap turn a stolen key from a disaster into a contained incident.
• Rotate keys periodically. Revoke any key that may have been exposed.