Testing Direct Collection APIs

Use this guide when your application calls a collection endpoint directly and owns the payment-method UI. No real money is charged in sandbox. Use a currency and payment method supported by your sandbox account, and include all required fields. Test values do not bypass amount limits or account restrictions.

If Honeycoin hosts your checkout, use Testing the Universal Payment SDK instead because hosted challenge and redirect responses differ.

Use sandbox credentials and a new externalReference for each request on your account. Use the same request fields as the corresponding production endpoint. Errors such as PROVIDER_NOT_FOUND, CURRENCY_NOT_ENABLED, METHOD_NOT_ENABLED, and VALIDATION_FAILED mean the request was not accepted for testing. Follow the returned error message before retrying.

Mobile Money

Use the mobile money test-number rule for any supported collection country: its calling code followed by the scenario digits below.

Request Template

Send the request to POST https://api-v2.honeycoin.app/api/sandbox/b2b/fiat/deposit/momo with your sandbox bearer token.

Replace <CURRENCY> with the collection currency, <CALLING_CODE> with the country's numeric calling code, and <OPERATOR_ID> with an operator from Mobile Money Operators for that country. These values must describe the same supported collection market. Replace the illustrative amount with one within your account's limits and use a new externalReference for every attempt. Do not send the placeholders literally.

{
  "externalReference": "direct-momo-success-001",
  "amount": 300,
  "currency": "<CURRENCY>",
  "phoneNumber": "<CALLING_CODE>712345678",
  "momoOperatorId": "<OPERATOR_ID>"
}

To simulate failure, keep the calling code, currency, and operator unchanged, replace the scenario digits 712345678 with 787654321, and use a new externalReference. Confirm the final status through the webhook or transaction lookup.

If You Receive PROVIDER_NOT_FOUND

This is a request rejection, not the simulated failed transaction outcome. Check:

1. The phone prefix is the calling code for the collection country you selected.
2. The collection currency and momoOperatorId match that country and operator. Changing only the phone prefix does not change these fields.
3. The currency, country, operator, and amount are available for your sandbox account. A correct test number does not guarantee availability.

If these details are correct and the error persists, contact support with the sandbox endpoint, request time and timezone, externalReference, currency, operator, and returned error code/message. Exclude API keys and bearer tokens.

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

Bank Transfer

{
  "externalReference": "direct-bank-success-001",
  "amount": 300,
  "currency": "NGN",
  "email": "[email protected]"
}

For the complete request contract, see Bank Transfer.

Card Charge

For an accepted request, the card number determines the test outcome. CVV and expiry can be any valid values. Include ipAddress; pass successRedirectUrl and failureRedirectUrl when required for your payment method. These are request fields; redirectUrl is a response field.

{
  "externalReference": "direct-card-success-001",
  "amount": 300,
  "currency": "NGN",
  "email": "[email protected]",
  "firstName": "Test",
  "lastName": "User",
  "ipAddress": "127.0.0.1",
  "cardDetails": {
    "number": "4242424242424242",
    "cvv": "123",
    "expMonth": "12",
    "expYear": "30"
  }
}

The initial card response contains data.transactionId. Read subsequent status/webhook updates for the challenge. Complete a required challenge using the direct card authorisation flow with the same sandbox account and a type matching stepRequired. three_ds is supported when it is the current required step. The 3DS test card above completes automatically. Successful or failed transactions cannot be authorized again. For request and authorisation payloads, see Card Charges.

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.

Any amount other than 111 follows the failed redirect outcome. Use 999 as the documented failure fixture.

For the complete request contract and redirect guidance, see OPay Charge.

Refund a Sandbox Mobile Money Deposit

Refunds must reference a successful MoMo deposit belonging to the same sandbox account. A production transaction ID cannot be used. Send a new refund externalReference and a refundReason of 10–255 characters to POST /api/sandbox/b2b/fiat/deposit/{originalTransactionId}/refund.

{
  "externalReference": "sandbox-refund-001",
  "refundReason": "Customer requested a full refund"
}

The response contains data.refundTransactionId and data.originalTransactionId. Use the refund ID or its external reference to check its status. For example, refunding a successful KES test deposit made with 254712345678 simulates a successful refund. A pending or successful refund prevents another refund of that deposit. No real money is refunded.

Verify Final Status

Direct collection initiation responses can be pending or require customer action. Always confirm the final state through a transaction webhook or the get transaction endpoint. Fulfill the order only when chargeStatus is successful.