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.
Validate → route → charge PSP → return unified response
Also available as POST /v1/transactions
/collections for new integrations.Request
Amount units
5000. Tunnel adapters convert to minor units only where a PSP requires it (e.g. Paystack).{
"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"
}
}| Field | Required | Notes |
|---|---|---|
| reference | Yes | Your idempotency key — resending the same reference is safe |
| operation | No | Defaults to charge. Other ops return unsupported_operation until shipped |
| amount | Yes* | Major units (*required for charge) |
| currency | Yes | e.g. NGN, GHS, KES, USD |
| channel | Yes | card | bank_transfer | mobile_money | ussd | bank_account |
| customer.email | Yes | Required by all providers |
| flow | No | hosted (default, redirect) or direct (complete through the API only, see below) |
| redirectUrl | No | Where the PSP redirects after hosted checkout / 3DS |
| provider | No | Force a PSP; omit to use routing rules |
| metadata | No | Passed through to the provider when supported |
cURL example
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.
{
"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.
| type | Fields | What to do |
|---|---|---|
| redirect | redirectUrl | Send the customer to the hosted checkout |
| otp, pin, avs | fieldsRequired | Collect the listed fields and submit them |
| bank_transfer_instructions | bankTransfer | Show account number, bank, amount, narration and expiry |
| ussd_code | ussdCode, message | Show the code for the customer to dial |
| qr_code | qrCode.image, message | Show the QR image (a data URI) for the customer to scan |
| await_customer | message | Tell the customer to approve the payment on their phone |
| mandate_consent | mandateConsent | Redirect or ask for a confirmation transfer to authorize the mandate |
Collection statuses
| status | Meaning |
|---|---|
| successful | Funds captured / settled |
| pending | Processing — await webhook or verify |
| requires_action | You must render nextAction (redirect, OTP, bank instructions, …) |
| failed | Declined, expired, or errored — terminal |
| cancelled | Customer 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.
- Bank transferIncludes underpayment and overpayment
- USSDA code the customer dials
- Mobile moneyPrompt, code or approval page
- Bank account debitBirthday and code steps
- OPayApprove in the OPay wallet
- NQR (QR code)Scan with any bank app
Start with the direct payments overview for the providers and currencies each method supports.
Look up a collection
Fetch by your merchant reference
Pass the same reference you sent on create. Tunnel transaction ids (txn_…) also work.
What to do next
Idempotency
reference returns the original collection instead of creating a duplicate charge.Next: Verify a payment →