Testing the Universal Payment SDK

The sandbox Universal Payment SDK follows the production hosted-checkout journey without contacting a live payment provider. The phone number, email address, card number, or OPay amount entered in checkout selects the simulated outcome.

For the production integration contract, see the Universal Payment SDK guide.

1. Create a Sandbox Payment Session

Send the normal Payment SDK payload to the sandbox endpoint using a bearer token generated from your sandbox credentials:

curl --request POST \
  --url https://api-v2.honeycoin.app/api/sandbox/b2b/fiat/payment-sdk \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 300,
    "chargeCurrency": "KES",
    "walletCurrency": "KES",
    "country": "KE",
    "externalReference": "sandbox-sdk-order-001",
    "successRedirectUrl": "https://example.com/payment/success",
    "failureRedirectUrl": "https://example.com/payment/failed",
    "cancelRedirectUrl": "https://example.com/payment/cancelled"
  }'

Use a new externalReference for every attempt. You can also pass method to restrict checkout to momo, bank, card, or opay.

The response contains the sandbox transaction ID and hosted checkout URL:

{
  "success": true,
  "message": "Sandbox SDK transaction created successfully.",
  "data": {
    "transactionId": "sandbox_transaction_id",
    "paymentSdkLink": "https://checkout.honeycoin.app/sdk/transaction/sandbox/sandbox_transaction_id"
  }
}

2. Open the Hosted Checkout

Redirect the customer to the returned paymentSdkLink. Do not construct this URL yourself. Checkout displays the payment methods available for the transaction's currency and country.

3. Select a Scenario

Use the following values in the hosted checkout:

Method	Scenario	Sandbox value	Expected SDK behavior
Mobile money	Success	Phone number `254712345678`	Completes successfully
Mobile money	Failure	Phone number `254787654321`	Completes as failed
Mobile money	Redirect success	Phone number `25477777777`	Returns `stepRequired: redirect`; completes successfully after the redirect
Mobile money	OTP	Phone number `25455555555`	Returns `stepRequired: otp`
Bank transfer	Success	Email `[email protected]`	Returns a sandbox virtual account and completes successfully
Bank transfer	Failure	Email `[email protected]`	Completes as failed
Card	Success	Card number `4242424242424242`	Completes successfully
Card	Failure	Card number `4000056655665556`	Completes as failed
Card	3DS	Card number `5555555555554444`	Returns `stepRequired: three_ds` and a `redirectUrl`
Card	OTP	Card number `4562543755474674`	Returns `stepRequired: otp`
Card	PIN	Card number `2223003122003222`	Returns `stepRequired: pin`
Card	Address verification	Card number `5200828282828210`	Returns `stepRequired: address_verification`
OPay	Redirect success	Amount `111`	Returns `stepRequired: redirect`; completes successfully after the redirect
OPay	Failure	Amount `999`	Completes as failed without another step

For card scenarios, CVV, expiry, and other card fields can be any valid values. The card number selects the sandbox behavior.

4. Complete Challenge Steps

Use these exact values when checkout requests additional authorisation:

Step	Successful value	Failed value
OTP	`111111`	`000000`
PIN	`1111`	`0000`
Address verification `street1`	`success street`	`failure street`

An address-verification value must also contain state, zip, city, and a two-letter country. Only street1 selects the final sandbox outcome.

{
  "street1": "success street",
  "state": "Lagos",
  "zip": "100001",
  "city": "Lagos",
  "country": "NG"
}

For redirect and three_ds, open the returned redirectUrl and complete the hosted step. Do not treat the browser redirect alone as payment confirmation.

5. Verify the Final Status

Retrieve the latest sandbox SDK transaction state:

curl --request GET \
  --url https://api-v2.honeycoin.app/api/sandbox/b2b/fiat/payment-sdk/YOUR_TRANSACTION_ID \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN'

Fulfill the order only when the returned status is successful. A pending response means checkout is still waiting for a challenge or redirect to finish.

OPay Behavior

OPay uses the payment-session amount to select its hosted SDK scenario:

Amount 111 returns a redirect and completes successfully after that redirect.
Amount 999 completes as failed without an additional step.

This differs from the direct OPay sandbox, which returns a redirect-first response for every initiation. In the direct flow, only amount 111 succeeds; any other amount fails after the redirect.