Direct payments
USSD
Send channel "ussd" with flow "direct". No redirect and no hosted page.
Where it works
| Provider | Currencies | Notes |
|---|---|---|
| Paystack | NGN | Send paymentMethod.ussd.bankUssdCode: 737, 919, 822 or 966. |
| Flutterwave | NGN | Send 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
| 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 | "ussd" | Required | Selects this method. |
| paymentMethod.ussd.bankUssdCode | string | Paystack: required | The USSD shortcode of the customer’s bank: 737, 919, 822 or 966. |
| paymentMethod.ussd.bankCode | string | Flutterwave: required | The customer’s bank code, for example 058. |
| 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_1002",
"flow": "direct",
"amount": 5000,
"currency": "NGN",
"channel": "ussd",
"customer": { "email": "ada@example.com" },
"paymentMethod": { "ussd": { "bankUssdCode": "737" } }
}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
{
"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.
| type | What it carries | What you do |
|---|---|---|
| ussd_code | ussdCode 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
- 01Ask for the bank. Let the customer pick their bank, then map it to the code your provider needs.
- 02Create.
POST /v1/collectionswithchannel: "ussd". You getrequires_actionandnextAction.ussdCode. - 03The customer dials. They enter the code on their phone and follow the bank’s prompts.
- 04Tunnel checks and tells you. Same as bank transfer: Tunnel polls the provider, and your webhook receives the final status.
Statuses to expect
| status | Meaning |
|---|---|
| requires_action | The code is issued and waiting to be dialled. |
| successful | The customer approved and the bank settled it. Final. |
| failed | The 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
| 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 | The bank code for your provider is missing. | Send bankUssdCode for Paystack or bankCode for Flutterwave. |
Every error uses the shape on the errors page.