Testing direct collection APIs

Use this guide when your application calls a collection endpoint directly and owns the payment-method UI. These sandbox values never contact a live payment provider.

Mobile money

Scenario	Phone number	Expected result
Success	`254712345678`	Transaction becomes `successful`
Failure	`254787654321`	Transaction becomes `failed`

Mobile money success

{
  "externalReference": "direct-momo-success-001",
  "amount": 300,
  "currency": "KES",
  "phoneNumber": "254712345678"
}

For request fields, operator requirements, and post-charge OTP or redirect handling, see Mobile money charge.

Bank transfer

Scenario	Email	Expected result
Success	`success@mail.com`	Returns a sandbox account and becomes `successful`
Failure	`failure@mail.com`	Transaction becomes `failed`

Bank transfer success

{
  "externalReference": "direct-bank-success-001",
  "amount": 300,
  "currency": "NGN",
  "email": "success@mail.com"
}

Full request contract in Bank transfer.

Card charge

The card number selects the scenario. CVV and expiry can be any valid values.

Scenario	Card number	Expected direct API behaviour
Success	`4242424242424242`	Transaction becomes `successful`
Failure	`4000056655665556`	Transaction becomes `failed`
3DS	`5555555555554444`	Returns `stepRequired: redirect` and a `redirectUrl`
OTP	`4562543755474674`	Returns `stepRequired: otp`
PIN	`2223003122003222`	Returns `stepRequired: pin`
Address verification	`5200828282828210`	Returns `stepRequired: address_verification`

Card success

{
  "externalReference": "direct-card-success-001",
  "amount": 300,
  "currency": "NGN",
  "email": "test@example.com",
  "firstName": "Test",
  "lastName": "User",
  "ipAddress": "127.0.0.1",
  "cardDetails": {
    "number": "4242424242424242",
    "cvv": "123",
    "expMonth": "12",
    "expYear": "30"
  }
}

3-D Secure surfaces as stepRequired: redirect — send the customer to the returned redirectUrl, then wait for the final webhook.

Complete any returned challenge through the direct card authorisation flow — see Card charge for authorisation payloads.

OPay

Direct sandbox OPay is redirect-first. Every initiation response includes stepRequired: redirect and a redirectUrl; opening that URL completes the simulated transaction with the outcome selected by the amount.

Amount	Scenario	Expected result
`111`	Success	Returns the redirect response, then becomes `successful`
`999`	Failure	Returns the redirect response, then becomes `failed`

Any amount other than 111 follows the failed redirect outcome. Use 999 as the documented failure fixture so your tests read clearly.

Full request contract in OPay charge.

Verify the final status

Direct collection initiation responses can be pending or require customer action. Always confirm the final state through a transaction webhook or Get Transaction.

Fulfil the order only when chargeStatus is successful.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Testing direct collection APIs

Mobile money

Bank transfer

Card charge

OPay

Verify the final status

​Mobile money

​Bank transfer

​Card charge

​OPay

​Verify the final status

Mobile money

Bank transfer

Card charge

OPay

Verify the final status