Direct payments

USSD

Tunnel returns a short code for the customer’s bank. They dial it on the phone number linked to their account and approve the payment with their bank’s own prompts.
POST/v1/collections

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

Where it works

Providers and currencies
ProviderCurrenciesNotes
PaystackNGNSend paymentMethod.ussd.bankUssdCode: 737, 919, 822 or 966.
FlutterwaveNGNSend paymentMethod.ussd.bankCode, the bank code, for example 058.

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"ussd"RequiredSelects this method.
paymentMethod.ussd.bankUssdCodestringPaystack: requiredThe USSD shortcode of the customer’s bank: 737, 919, 822 or 966.
paymentMethod.ussd.bankCodestringFlutterwave: requiredThe customer’s bank code, for example 058.
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_1002",
  "flow": "direct",
  "amount": 5000,
  "currency": "NGN",
  "channel": "ussd",
  "customer": { "email": "ada@example.com" },
  "paymentMethod": { "ussd": { "bankUssdCode": "737" } }
}
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_1002",
    "flow": "direct",
    "amount": 5000,
    "currency": "NGN",
    "channel": "ussd",
    "customer": { "email": "ada@example.com" },
    "paymentMethod": { "ussd": { "bankUssdCode": "737" } }
  }'

Response

HTTP 201, requires_action
{
  "success": true,
  "data": {
    "transactionId": "txn_3c9d2e7a1b4f6085",
    "reference": "ord_1002",
    "provider": "paystack",
    "status": "requires_action",
    "amount": 5000,
    "currency": "NGN",
    "channel": "ussd",
    "nextAction": {
      "type": "ussd_code",
      "message": "Dial the code on the phone linked to your bank account",
      "ussdCode": "*737*000*4512#"
    }
  }
}

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
ussd_codeussdCode and a message that is safe to show.Show the code with a copy button, and a dial link on phones. Tell the customer to use the phone number linked to their bank.

The flow

  1. 01Ask for the bank. Let the customer pick their bank, then map it to the code your provider needs.
  2. 02Create. POST /v1/collections with channel: "ussd". You get requires_action and nextAction.ussdCode.
  3. 03The customer dials. They enter the code on their phone and follow the bank’s prompts.
  4. 04Tunnel checks and tells you. Same as bank transfer: Tunnel polls the provider, and your webhook receives the final status.

Statuses to expect

Statuses
statusMeaning
requires_actionThe code is issued and waiting to be dialled.
successfulThe customer approved and the bank settled it. Final.
failedThe customer cancelled, the code timed out, or the bank declined. Final.

Confirm the final status with verify or a webhook. Never treat the customer coming back to your site as proof of payment.

Amounts

A USSD payment is for the exact amount of the collection, so the customer cannot pay a different amount. 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_ERRORThe bank code for your provider is missing.Send bankUssdCode for Paystack or bankCode for Flutterwave.

Every error uses the shape on the errors page.