Payments

Create a collection

Merchants send payment details to Tunnel. Tunnel applies your routing rules, calls the selected provider with your connected credentials, and returns one normalized response — you never integrate Paystack or Flutterwave directly for the charge itself.

POST/v1/collections

Validate → route → charge PSP → return unified response

Also available as POST /v1/transactions

Same orchestrator and response shape. Prefer /collections for new integrations.

Request

Amount units

Amounts are in the major unit of the currency (naira, not kobo). Example: ₦5,000.00 → 5000. Tunnel adapters convert to minor units only where a PSP requires it (e.g. Paystack).
Body (UnifiedCollectionRequest)
{
  "reference": "ord_1001",
  "operation": "charge",
  "amount": 5000,
  "currency": "NGN",
  "channel": "card",
  "customer": {
    "email": "customer@example.com",
    "name": "Ada Lovelace",
    "phone": "+2348012345678"
  },
  "redirectUrl": "https://yoursite.com/payment/callback",
  "metadata": {
    "order_id": "ord_1001"
  }
}
FieldRequiredNotes
referenceYesYour idempotency key — resending the same reference is safe
operationNoDefaults to charge. Other ops return unsupported_operation until shipped
amountYes*Major units (*required for charge)
currencyYese.g. NGN, GHS, KES, USD
channelYescard | bank_transfer | mobile_money | ussd | bank_account
customer.emailYesRequired by all providers
flowNohosted (default, redirect) or direct (complete through the API only, see below)
redirectUrlNoWhere the PSP redirects after hosted checkout / 3DS
providerNoForce a PSP; omit to use routing rules
metadataNoPassed through to the provider when supported

cURL example

cURL
curl -X POST "https://xv9ni4gwk9.execute-api.us-east-1.amazonaws.com/dev/v1/collections" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "X-Tunnel-Origin: https://api.yourapp.com" \
  -d '{
    "reference": "ord_1001",
    "amount": 5000,
    "currency": "NGN",
    "channel": "card",
    "customer": { "email": "customer@example.com" },
    "redirectUrl": "https://yoursite.com/payment/callback"
  }'

Response

On success, data is a UnifiedCollectionResponse. Hosted checkout returns requires_action with a redirect URL — send the customer there. The raw PSP body is in raw.

HTTP 201 — requires_action (redirect)
{
  "success": true,
  "data": {
    "success": true,
    "transactionId": "txn_8f2a1c0b4e9d7a6c",
    "reference": "ord_1001",
    "providerReference": "txn_8f2a1c0b4e9d7a6c",
    "provider": "paystack",
    "status": "requires_action",
    "amount": 5000,
    "currency": "NGN",
    "channel": "card",
    "nextAction": {
      "type": "redirect",
      "redirectUrl": "https://checkout.paystack.com/0peioxfhpn"
    },
    "raw": {
      "status": true,
      "message": "Authorization URL created",
      "data": {
        "authorization_url": "https://checkout.paystack.com/0peioxfhpn",
        "access_code": "0peioxfhpn",
        "reference": "txn_8f2a1c0b4e9d7a6c"
      }
    },
    "createdAt": "2026-08-04T06:00:00.000Z"
  },
  "meta": {
    "requestId": "…",
    "timestamp": "…"
  }
}

nextAction types

When status is requires_action, nextAction.type tells you what to show the customer. Switch on type rather than assuming a redirect, so new providers and channels need no changes on your side. Today the connected hosted flow returns redirect; the direct flow below returns the other types. Any type may also carry a provider message that is safe to show the customer.

typeFieldsWhat to do
redirectredirectUrlSend the customer to the hosted checkout
otp, pin, avsfieldsRequiredCollect the listed fields and submit them
bank_transfer_instructionsbankTransferShow account number, bank, amount, narration and expiry
ussd_codeussdCode, messageShow the code for the customer to dial
qr_codeqrCode.image, messageShow the QR image (a data URI) for the customer to scan
await_customermessageTell the customer to approve the payment on their phone
mandate_consentmandateConsentRedirect or ask for a confirmation transfer to authorize the mandate

Collection statuses

statusMeaning
successfulFunds captured / settled
pendingProcessing — await webhook or verify
requires_actionYou must render nextAction (redirect, OTP, bank instructions, …)
failedDeclined, expired, or errored — terminal
cancelledCustomer abandoned — terminal

Direct (API-only) collections

Send "flow": "direct" to complete a collection through the API with no redirect and no hosted page. Tunnel creates the charge and returns what you show the customer: transfer account details, a USSD code, or a phone prompt. Each method has its own page with the request and response, next action types, flow, statuses and errors.

Start with the direct payments overview for the providers and currencies each method supports.

Look up a collection

GET/v1/collections/{reference}

Fetch by your merchant reference

Pass the same reference you sent on create. Tunnel transaction ids (txn_…) also work.

What to do next

  1. If status is requires_action, follow nextAction (usually redirect the customer).
  2. Do not treat redirect query params as final proof of payment.
  3. Confirm with verify or a webhook.

Idempotency

Replaying the same reference returns the original collection instead of creating a duplicate charge.

Next: Verify a payment →