Direct payments
OPay
Send channel "opay" with flow "direct". No redirect and no hosted page.
Where it works
| Provider | Currencies | Notes |
|---|---|---|
| Flutterwave | NGN | Nigeria only. |
| Paystack | None | The Charge API has no OPay option. OPay appears only inside Paystack’s hosted checkout, under Pay with Bank. |
| Fincra | None | Fincra lists no OPay option for NGN. |
Tunnel only uses a connected provider that supports the channel and currency. If none does, the call returns 400 UNSUPPORTED_CHANNEL.
Request
| Field | Type | Required | Notes |
|---|---|---|---|
| reference | string | Required | Your own id for this payment. Sending the same reference again returns the original collection. |
| flow | "direct" | Required | Completes the payment through the API with no redirect to a hosted page. |
| amount | number | Required | In the major unit of the currency: 5000 is ₦5,000.00. |
| currency | string | Required | ISO code. It must be one this method supports (see above). |
| customer.email | string | Required | Every provider needs it. |
| channel | "opay" | Required | Selects this method. It is only available with flow "direct". |
| customer.name | string | Optional | Shown on the provider’s receipt where supported. |
| customer.phone | string | Optional | Contact number. |
| provider | string | Optional | Force one provider. Leave it out to let your routing rules choose. |
| metadata | object | Optional | Your own key and value pairs, passed to the provider where supported. |
{
"reference": "ord_1005",
"flow": "direct",
"amount": 8000,
"currency": "NGN",
"channel": "opay",
"customer": { "email": "ada@example.com", "name": "Ada Obi" }
}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" \
-d '{
"reference": "ord_1005",
"flow": "direct",
"amount": 8000,
"currency": "NGN",
"channel": "opay",
"customer": { "email": "ada@example.com" }
}'Response
{
"success": true,
"data": {
"transactionId": "txn_5d0c7e1a9b2f4386",
"reference": "ord_1005",
"provider": "flutterwave",
"status": "requires_action",
"amount": 8000,
"currency": "NGN",
"channel": "opay",
"nextAction": {
"type": "redirect",
"message": "Continue in OPay to approve the payment",
"redirectUrl": "https://…/opay_page?transactionIdentifier=…"
}
}
}A charge can also settle inside the create call. Then status is successful and there is no nextAction.
Next action types
When status is requires_action, switch on nextAction.type. These are the types you can get for this method.
| type | What it carries | What you do |
|---|---|---|
| redirect | redirectUrl and a message that is safe to show. | Send the customer to redirectUrl. When they return, show a waiting state: coming back is not proof of payment. |
The flow
- 01Create.
POST /v1/collectionswithchannel: "opay"andflow: "direct". You getrequires_actionand aredirectnext action. - 02Redirect. Open
redirectUrlfor the customer. It takes them into OPay. - 03The customer approves in OPay with their wallet PIN, then returns to your site.
- 04Tunnel checks and tells you. Tunnel asks the provider about the payment, and your webhook receives the final status.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | The OPay link is issued and waiting for the customer. |
| pending | The customer has started and OPay is processing. |
| successful | OPay debited the wallet. Final. |
| failed | Declined, abandoned or timed out. Final. |
Confirm the final status with verify or a webhook. Never treat the customer coming back to your site as proof of payment.
Amounts
OPay charges the exact amount of the collection. If a provider ever reports less than the collection amount as paid, Tunnel records it as failed with amount_mismatch, the same as for bank transfer.
Errors to expect
| When | Code | Meaning | What to do |
|---|---|---|---|
| Create | 400 VALIDATION_ERROR | A required field is missing or malformed. | Nothing was charged. Fix the request and resend it with the same reference. |
| Create | 400 UNSUPPORTED_CHANNEL | No connected provider supports this channel and currency for direct payments. | Connect a provider that does, or use the hosted flow. |
| Create | 400 NO_PROVIDERS | No provider is enabled for this mode (test or live). | Connect and enable a provider in the dashboard. |
| Create | 422 | The provider declined the charge. | Use a new reference to try again. |
| Create | 503 PROVIDER_UNAVAILABLE | A temporary problem at the provider. | Retry with the same reference. |
| Create | 400 VALIDATION_ERROR | OPay was requested without flow "direct". | Send flow: "direct". OPay has no hosted version. |
Every error uses the shape on the errors page.