Quickstart

Create your organization

Before interacting with the API, you need a registered CarlPay organization. This acts as the root container for your ledger, configurations, and team members.

Retrieve your API keys

Navigate to Developers > API Keys in the Dashboard. You will find two sets of keys: Test and Live. For this tutorial, ensure the Dashboard is toggled to Test Mode and copy your Secret Key.

Create your first Payment Order

A Payment Order represents an intent to collect funds. Use the /v1/payment_orders endpoint to initiate a Wallet Collect collection. Provide amount, currency, and set route to "managed" for CarlPay's Wallet Collect product.

curl -X POST "$NEXT_PUBLIC_SITE_URL/api/v1/payment_orders" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_001" \
  -d '{
    "amount": "50.00",
    "currency": "KES",
    "route": "managed",
    "customer_reference": "INV-001",
    "msisdn": "254712345678"
  }'

A successful request returns a Payment Order object with status requires_action.

Marketplaces: create a connected account first, then include connected_account_id (ca_*) and application_fee_cents on managed orders only. payment.succeeded webhooks include split fields when present.

Handle incoming webhooks

Payment state changes happen asynchronously. Configure an endpoint to receive webhook events (e.g., payment.succeeded, payment.failed, payout.succeeded, payout.pending_approval) to update your internal ledger.