Unified Banking-as-a-Service API Reference

Deterministic Sandbox Magic Values

Supported Webhook Event Types

Initialize Gateway Checkout Session

Generates a hosted authorization URL or iframe checkout session. Returns dedicated dynamic bank transfer coordinates, unique session reference, and USSD dial strings.

{
  "success": true,
  "message": "Checkout session created successfully.",
  "data": {
    "authorization_url": "https://pay.getpaddle.online/t?ref=PAD_GW_17913...&amount=5000",
    "reference": "PAD_GW_1791311707_34AB",
    "access_code": "acc_87e1a3b5c4",
    "account_number": "7943128784",
    "bank_name": "Wema Bank",
    "account_name": "pickpadi Global Ltd (via Paddle Pay)",
    "ussd_codes": {
      "GTBank": "*737*2*5000*7943128784#",
      "ZenithBank": "*966*5000*7943128784#"
    }
  }
}

Initialize Global Acquiring Intent (USD, EUR, GBP, CAD, AUD)

Initializes a white-labeled global checkout intent supporting international cards (Visa, Mastercard, American Express with 3DS2), Apple Pay, Google Pay, Buy Now Pay Later (Klarna, Afterpay, Affirm), and automatic local virtual bank transfer coordinates (US ACH/Fedwire, EU SEPA IBAN, UK Bacs). Settles directly into the merchant's multi-currency treasury wallet.

{
  "success": true,
  "message": "Paddle Global Payment Intent initialized.",
  "data": {
    "intent_id": "pi_pad_94a08bc71e",
    "client_token": "tok_pad_sec_87e1a3b5c4",
    "reference": "PAD_GLB_1792348120_A1",
    "amount": 150.00,
    "currency": "USD",
    "status": "REQUIRES_PAYMENT_METHOD",
    "checkout_url": "https://pay.getpaddle.online/t?ref=PAD_GLB_1792348120_A1&currency=USD&amount=150",
    "supported_methods": ["card", "apple_pay", "google_pay", "bank_transfer", "klarna"],
    "bank_transfer_instructions": {
      "rail": "US ACH / Fedwire Wire Transfer",
      "account_number": "0284719283",
      "routing_number": "021000021",
      "bank_name": "JPMorgan Chase / Paddle Federal Rail"
    },
    "statement_descriptor": "PADDLE* PICKPADI"
  }
}

Direct Bank Debit (US ACH, EU SEPA & UK Bacs)

Authorizes and pulls funds directly from customer bank accounts globally with compliant mandate tracking. Supports US ACH (Routing/Account), EU SEPA Core Direct Debit (IBAN), and UK Bacs (Sort Code/Account).

{
  "success": true,
  "message": "US_ACH_DIRECT_DEBIT authorization mandate accepted.",
  "data": {
    "debit_id": "ach_pad_31f7ac981b",
    "mandate_reference": "MND_ACH_US_1792348120",
    "reference": "PAD_DBT_1792348120_01",
    "rail": "US_ACH_DIRECT_DEBIT",
    "amount": 250.00,
    "currency": "USD",
    "status": "PROCESSING",
    "estimated_settlement": "1-2 Business Days"
  }
}

Nigerian Card & 3D Secure Acquiring

Initializes a direct 3D Secure authorization flow for Mastercard, Visa, and Verve debit/credit cards with bank OTP authentication.

Pan-African Multi-Currency Acquiring (35 African Countries)

Charge customers seamlessly across Kenya (M-Pesa STK Push), Ghana (MTN MoMo, Telecel), South Africa (Ozow EFT, Capitec), Uganda, Rwanda, Côte d'Ivoire, Senegal, Cameroon, and Egypt. The gateway auto-detects payment options and currency symbols based on the order currency.

curl -X POST https://api.getpaddle.online/v1/gateway/pan-africa/charge \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "KES",
    "country": "KE",
    "network": "MPESA",
    "customerPhone": "254712345678",
    "customerEmail": "customer@nairobi.ke"
  }'

Instant Multi-Currency Refunds

Issue full or partial refunds for settled transactions across any currency (USD, EUR, GBP, NGN, KES, GHS, ZAR). Atomically adjusts double-entry ledgers, deducts merchant wallet balance, and executes upstream payment reversal to the customer.

{
  "success": true,
  "message": "Refund processed and settled successfully.",
  "data": {
    "refund_id": "re_pad_78dae39c",
    "transaction_reference": "PAD_GLB_1792348120_A1",
    "amount_refunded": 150.00,
    "currency": "USD",
    "status": "SUCCEEDED",
    "reason": "requested_by_customer",
    "created_at": "2026-10-18T15:20:00.000Z"
  }
}

Verify Payment Settlement (Server-to-Server)

Call from your backend using your Secret Key (Authorization: Bearer sk_live_...) to confirm genuine ledger settlement before delivering goods or services.

{
  "success": true,
  "message": "Transaction verified successfully.",
  "data": {
    "reference": "PAD_GW_1791311707_34AB",
    "amount": 5000,
    "currency": "NGN",
    "channel": "BANK_TRANSFER",
    "status": "SUCCESSFUL",
    "customer_name": "Patrick Achua",
    "settled_at": "2026-10-06T18:35:07.000Z"
  }
}

Search 300+ global airports, metropolitan areas, cities, and countries. Supports fuzzy keyword matching, ISO country code filtering, and primary international gateway identification.

{
  "success": true,
  "data": {
    "count": 5,
    "query": "Nigeria",
    "airports": [
      {
        "code": "LOS",
        "city": "Lagos",
        "country": "Nigeria",
        "countryCode": "NG",
        "airport": "Murtala Muhammed International Airport",
        "isHub": true
      },
      {
        "code": "ABV",
        "city": "Abuja",
        "country": "Nigeria",
        "countryCode": "NG",
        "airport": "Nnamdi Azikiwe International Airport",
        "isHub": true
      }
    ]
  }
}

Issue an electronic airline ticket for a selected offer. Automatically debits your spend wallet.

{
  "offer_id": "off_034ka1V9eHUwPMiTVmqMC0",
  "amount": 439.62,
  "currency": "USD",
  "clientReference": "PDL-FLT-10029",
  "passengers": [
    {
      "title": "mr",
      "given_name": "Tunde",
      "family_name": "Adekunle",
      "born_on": "1992-04-18",
      "gender": "m",
      "email": "tunde.adekunle@example.com",
      "phone_number": "+2348031234567"
    }
  ]
}

{
  "success": true,
  "message": "Flight ticket issued successfully",
  "data": {
    "bookingId": "ord_0000A1234B",
    "reference": "PDL-FLT-10029",
    "status": "confirmed",
    "ticketNumbers": ["085-2412891230"],
    "passengers": [
      { "name": "Tunde Adekunle", "email": "tunde.adekunle@example.com" }
    ]
  }
}

Insufficient Spend Wallet Equity (402 Payment Required)

If your Available Spend Wallet balance is below the total required ticket fare, the issuance is safely blocked with a transparent breakdown:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_WALLET_EQUITY",
    "message": "Insufficient USD wallet equity to issue flight ticket. Required: $439.62, Available: $0.00. Please fund your USD Available Spend Wallet."
  }
}

Rate Limit Headers

Every response includes RFC 6585 headers detailing current quota:

Programmatically query our turnkey engineering catalog, delivery SLAs, and tech stack via GET /v1/build-with-us/services, or submit a project scoping & quote request directly via POST /v1/build-with-us/inquire.