Direct payments

OPay

Send the customer to OPay to approve the payment from their OPay wallet. Nothing is typed into your page: you redirect, they approve, and Tunnel tells you when the money arrives.
POST/v1/collections

Send channel "opay" with flow "direct". No redirect and no hosted page.

Where it works

Providers and currencies
ProviderCurrenciesNotes
FlutterwaveNGNNigeria only.
PaystackNoneThe Charge API has no OPay option. OPay appears only inside Paystack’s hosted checkout, under Pay with Bank.
FincraNoneFincra 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

Request fields
FieldTypeRequiredNotes
referencestringRequiredYour own id for this payment. Sending the same reference again returns the original collection.
flow"direct"RequiredCompletes the payment through the API with no redirect to a hosted page.
amountnumberRequiredIn the major unit of the currency: 5000 is ₦5,000.00.
currencystringRequiredISO code. It must be one this method supports (see above).
customer.emailstringRequiredEvery provider needs it.
channel"opay"RequiredSelects this method. It is only available with flow "direct".
customer.namestringOptionalShown on the provider’s receipt where supported.
customer.phonestringOptionalContact number.
providerstringOptionalForce one provider. Leave it out to let your routing rules choose.
metadataobjectOptionalYour own key and value pairs, passed to the provider where supported.
Example body
{
  "reference": "ord_1005",
  "flow": "direct",
  "amount": 8000,
  "currency": "NGN",
  "channel": "opay",
  "customer": { "email": "ada@example.com", "name": "Ada Obi" }
}
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" \
  -d '{
    "reference": "ord_1005",
    "flow": "direct",
    "amount": 8000,
    "currency": "NGN",
    "channel": "opay",
    "customer": { "email": "ada@example.com" }
  }'

Response

HTTP 201, requires_action (redirect to OPay)
{
  "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.

Next action types
typeWhat it carriesWhat you do
redirectredirectUrl 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

  1. 01Create. POST /v1/collections with channel: "opay" and flow: "direct". You get requires_action and a redirect next action.
  2. 02Redirect. Open redirectUrl for the customer. It takes them into OPay.
  3. 03The customer approves in OPay with their wallet PIN, then returns to your site.
  4. 04Tunnel checks and tells you. Tunnel asks the provider about the payment, and your webhook receives the final status.

Statuses to expect

Statuses
statusMeaning
requires_actionThe OPay link is issued and waiting for the customer.
pendingThe customer has started and OPay is processing.
successfulOPay debited the wallet. Final.
failedDeclined, 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

Errors
WhenCodeMeaningWhat to do
Create400 VALIDATION_ERRORA required field is missing or malformed.Nothing was charged. Fix the request and resend it with the same reference.
Create400 UNSUPPORTED_CHANNELNo connected provider supports this channel and currency for direct payments.Connect a provider that does, or use the hosted flow.
Create400 NO_PROVIDERSNo provider is enabled for this mode (test or live).Connect and enable a provider in the dashboard.
Create422The provider declined the charge.Use a new reference to try again.
Create503 PROVIDER_UNAVAILABLEA temporary problem at the provider.Retry with the same reference.
Create400 VALIDATION_ERROROPay was requested without flow "direct".Send flow: "direct". OPay has no hosted version.

Every error uses the shape on the errors page.