Fondeka Payment API FAQ: Mobile Money, crypto and fees

For example, a customer places an order on your website. Your server asks Fondeka to collect the payment using a supported method. Fondeka processes the request and sends your server an update when the result is known. Your application can then update the order.

An API is the connection between your software and Fondeka. It does not replace your website, app or customer service.

• Students building projects, prototypes or their first products.
• Freelancers and independent developers adding payments to services or client applications.
• Small businesses that want to collect and send payments through their own software.
• Startups building an MVP or launching before all company registration and administrative documents are ready.

Established teams can also assess whether the service fits their needs. Our main purpose is to make payment integration more accessible at an early stage.

You still need an eligible Fondeka account and must complete the checks required for your situation. Identity verification, account restrictions and payment rules remain applicable, especially for real payouts. Starting without company paperwork does not mean using the service anonymously.

Read the payment API eligibility overview.

Working directly with an aggregator can still involve company documentation, technical setup, provider-specific rules, payment status handling and operational follow-up. Fondeka simplifies access to supported payment routes through its own API and portal.

You still build your application's checkout, order records, webhook receiver and business rules. The benefit is that your team works with Fondeka's documented payment flow instead of managing each underlying connection separately.

The API also provides payment lookup, wallet balances and tools for Sandbox testing.

Your own application decides what is being sold and what happens after payment. For example, a subscription app can track renewal dates itself and request each payment through a supported flow. Do not assume that accepting a payment automatically creates a recurring debit mandate or a complete subscription service.

Depending on the offer shown to your account, API access may be included in a Business Tools bundle or sold individually. The purchase screen explains which tools your payment unlocks.

A feature appearing in the app, or a method name appearing in a technical list, does not automatically mean that it is available through this payment API. Use the current API catalog and guides for your integration.

If you simply want a ready-to-use way to collect payments, explore Fondeka's Payment Links, Online Stores or POS tools. If you want payments inside your own product, the API is the relevant tool.

More countries and supported routes will be added as the service expands.

The table identifies country coverage and relevant local currencies. It is not a promise that every operator supports every currency, both payment directions or every settlement choice. Check the current route details in your API area before launching a particular flow.

Select the method for the customer's or recipient's actual country. Similar operator names do not make the routes interchangeable. Check the international phone number, country and currency together.

The Business portal's Available payment methods section provides the supported identifiers and relevant information. A collection route and a payout route can have different availability, limits and fees, even when they use the same operator.

Before promising a payment option to your customers, confirm the specific country, operator, currency and direction. For payouts, recipient eligibility and available funds also matter. Your integration must display a useful message if a previously available route becomes unavailable.

Check the actual route in the portal, then verify the relevant Live flow before offering it widely. For a cross-border business model, describe the countries and currencies you need when contacting support.

Do not select a currency only because it exists in a wallet list or in a code example. The applicable conversion, fees and route availability must be checked for your actual request. Keep the currency displayed clearly beside every amount shown to the customer.

The asset and network must match. A token supported on one network is not automatically supported on another. Show the exact returned network, address, token amount and any invoice expiry to the customer.

Build your interface to handle a route becoming unavailable. Confirm the latest method and fee information rather than treating a saved screenshot or an old list as a permanent promise.

If your project needs a country, operator, currency or crypto network that is not currently available, contact support with the details. A requested route should only be advertised to your customers after its availability has been confirmed.

Your access payment supports the integration environment and tools you use to connect, test, manage credentials, understand supported payment routes and operate your payment flow through Fondeka. Transaction processing is charged separately when you use payment operations.

• The access charge activates the API tool or the Business Tools offer shown to your account.
• Transaction fees apply to the payment operations you perform, according to the selected route and current pricing.

Paying for access does not make payment processing free. It also does not turn the access charge into a wallet deposit or a balance you can send to customers.

The offer can be for the full Business Tools bundle or for API access alone. Prices and available offers can change, so a price quoted by another user or shown in an old message may not be the offer available to you. The displayed payment total can also include the processing fees for the method used to pay for activation.

This FAQ does not replace the offer displayed to your account. Do not assume that every account has the same price, billing term or included tools. Ask support before paying if the term is unclear.

Selecting the API can show API-specific benefits while the payment is still for the full bundle. Read both the benefits and the coverage explanation. The price and plan shown on the purchase screen identify the actual offer.

1. Your Business identity and ID, used to identify your integration.
2. API credential management, including separate Sandbox and Live credentials, subject to the applicable account rules.
3. A separate webhook signing secret, so your server can verify notifications from Fondeka.
4. Guides for the four payment flows, plus explanations of amounts, payment states and errors.
5. The available payment-method and crypto-network catalog, with the relevant identifiers and current fee information.
6. Sandbox tools, including virtual wallet funding, virtual balances, history and supported test scenarios.
7. Dedicated API wallet and transaction views, with the selected environment kept visible.
8. Credential controls, such as updating a webhook URL and revoking a key.

Actual Live payment acceptance remains subject to Live availability and the checks for your account and payment route. Your purchase does not automatically provide payout funds, customer orders, a finished website or guaranteed transaction approval.

Save both the API key and the webhook signing secret when they are shown. Complete secrets are displayed only at generation time. A masked key shown later is an identifier, not a replacement for the complete secret.

Read the public guides and ask questions before buying if your project depends on a particular country, operator, feature or Live launch date. Access should be purchased with a clear understanding of the service you intend to use.

Sandbox has its own virtual funding tools for testing. Virtual funds cannot be withdrawn or turned into Live money. For real payouts, fund the appropriate real wallet through the supported Fondeka account flow.

Review the access amount, payment-processing fees and final total before confirming. Follow the exact instructions for the selected method. The methods used to purchase access are separate from the methods your own application can use through the payment API.

Some payment methods complete asynchronously. A payment being submitted, or money leaving an external account, does not by itself confirm that access has been granted. Do not immediately make another purchase. If the payment appears completed but the tool remains locked, contact support with the purchase reference and the account email you used.

When you return, check the pending payment before starting another one. If you have already sent a bank transfer or crypto payment, avoid sending it a second time merely because the screen still shows a pending status.

Use the instructions associated with that purchase and check its status. If you need to change an unpaid payment method, only use the option offered by the portal. Do not assume an old reference can be reused with new instructions or a different amount.

Access to POS or Online Stores alone does not automatically mean API access is included. Check the coverage of your actual grant. Contact support if your previous payment or access appears to be missing.

Your project must fit the supported payment flows. If you expect substantial volumes or have a specialized activity, discuss it with Fondeka before relying on a particular operational setup.

The average explanation is:

These are averages, not a fixed tariff for every payment. Actual fees can differ from one operator to another and between payment routes, collections, payouts, currencies and amount ranges. The current detailed fee information becomes available in your API area after access is active.

For a simple illustration using a 100 USD fee base, 3 USD for the aggregator plus 2 USD for Fondeka equals 5 USD in total. Fondeka presents the operation's combined fee. The merchant payment response exposes one fee, rather than a separate breakdown of the underlying components.

A fee per payment operation does not mean a new payment-processing fee each time you look up that same payment or receive another copy of its notification. Those actions do not create a new collection or payout.

That example explains the average pricing model. It is not a quote for a particular operator. The actual fee can depend on the amount sent for processing, fee mode, minimum charges, tiers, conversion and rounding. Use the returned fee and payment amounts for the real operation.

For that reason, applying a hard-coded 5% to every request would be misleading. The average helps explain the model; the current route-specific information and the server-calculated amounts determine the actual operation.

A catalog or fee range helps you understand pricing. The actual amount and destination can affect routing and the final calculation. Use the current server-calculated amounts for the payment rather than estimating a final charge from the FAQ or an old catalog screenshot.

The activation screen shows the processing fees and total for your access purchase. Your API area's payment-method information explains operation pricing. Do not treat a fee paid during activation as a prepaid allowance for future API transactions.

• EXCLUSIVE — fees added: you want to receive 100 USD. Add the 5 USD fee: the customer pays 105 USD and you receive 100 USD.
• INCLUSIVE — fees included: the customer pays 100 USD in total. Take the 5 USD fee out of that amount: you receive 95 USD.

The 5 USD fee is only an illustration; actual fees depend on the operation. Always show the customer their total before they approve payment. If you omit the mode, the payment route’s default policy applies.

These examples assume the stated fee has already been calculated. They do not imply that every 100 USD request produces a 5 USD fee. For crypto, the actual token amount comes from the returned conversion instructions.

• amount is the net fiat amount. For a completed collection, it represents the reconciled wallet credit.
• fee is the consolidated operation fee.
• grossAmount is the net amount plus the fee.
• currency tells you which fiat currency those numbers use.

For a payout, the gross amount is the amount reserved or debited from the wallet. Read these fields together. A number without its currency or fee mode can give the wrong impression of what the customer pays or what the business receives.

Request amounts use normal currency units: 10 with currency: "USD" means 10 USD, not 10 cents. Monetary requests allow at most two decimal places. Your developer should handle money with decimal arithmetic and should not automatically multiply every amount by 100.

Read the payment amounts and fee-mode guide.

Use the amounts and currencies returned for the actual payment. For crypto, use the returned token quantity, asset and network. Do not assume that 100 USD means 100 tokens, that a rate is always 1:1, or that a test rate is a real market rate.

Review the total presented for the Fondeka payment and any separate charges disclosed by the external operator or wallet for its own services. Ask support about a particular route if the relationship between those charges is unclear.

Do not assume that paying a collection fee makes the later payout free, or that the approximate 5% average describes the total cost of an entire workflow containing several payments. Estimate your business model using the actual operations it requires.

A failure status alone does not establish that money or fees have been returned. Refund handling depends on the operation and applicable policy. Check the relevant wallet records and contact support if the result is unclear. Do not automatically send another payout to compensate for a failed or unresolved one.

You can test submitting payments, following their status, receiving signed webhooks, handling failures and checking virtual wallet effects. Sandbox does not call the real payment providers or move real money. It is where you should build confidence in your integration before using customer funds.

Read the Sandbox testing guide.

Live requires the appropriate credential, access and account eligibility, a supported route, and Fondeka's availability for new Live API payments. A working Sandbox integration is preparation for Live; it is not authorization to process real payments by itself.

Opening a demo workspace is not the same as testing your own server with a Sandbox API key. Keep the selected environment visible when developing and reviewing transactions.

The stored credential determines the environment. Changing a label in your interface, editing a prefix or adding “sandbox” to an unrelated URL does not change what a key can do. Older valid key formats can remain supported; follow the environment recorded for the credential.

Keep your environment configuration explicit on your server. For example, store the Sandbox and Live credentials separately and check the returned environment when processing a payment or webhook.

These funds have no cash value. They do not increase your real account balance, cannot pay for actual purchases and cannot be withdrawn. Use only the Sandbox tools for virtual funding; never send real money or real crypto to a Sandbox payment instruction.

Sandbox conversion is for learning how your integration handles amounts, balances and history. It does not establish the real exchange rate, actual Live fee or availability of a production conversion route.

Developers can use the documented Sandbox simulation header, X-Simulate-Error-Code, with a supported value. Some simulations reject the request immediately; others accept the payment and produce a later outcome. Your application should handle both situations correctly.

This is useful for checking that your app does not deliver goods, release funds or send a duplicate payout while the result is unresolved. A simulated pending payment does not become a success merely because your own waiting timer ends.

Those figures are test fixtures, not a commercial offer. Use the actual Live fee information when planning your margins or explaining charges to customers. The average 3% aggregator plus 2% Fondeka explanation concerns real-operation pricing, not a requirement that every Sandbox example use 5%.

Before launch, confirm the actual route, account eligibility, limits, fees and Live availability. Then verify the relevant Live flow with an appropriate small real operation when the service is enabled.

If you receive BUSINESS_API_LIVE_PAYMENTS_DISABLED, continue development in Sandbox and check availability with Fondeka. Do not keep retrying new Live payments in the hope of bypassing the restriction. Previously accepted payments retain their normal status tracking and processing.

1. Confirm the relevant access, account verification and Live-payment availability.
2. Check the real methods, countries, currencies, networks, limits and fees your business needs.
3. Test successful, failed, duplicate and unresolved payments in Sandbox.
4. Deploy a public HTTPS webhook receiver that verifies notifications and handles duplicates.
5. Create and securely store separate Live credentials.
6. Fund the relevant real wallet before requesting payouts.
7. Make an appropriate small Live test and reconcile its final status, notification and wallet effect.

Keep Sandbox credentials and data separate so development cannot accidentally trigger a production payment.

Read the go-live checklist.

You also need a public HTTPS webhook destination before relying on automatic payment notifications. You can prepare your website and server while completing account setup. Review the supported route you intend to use before promising it to customers.

1. Create your Fondeka account through the supported account-registration flow, or use your existing account.
2. Sign in to the Business portal.
3. Open the API area and review the access offer if activation is required.
4. Once access is active, check your Business ID, payment methods and current fees.
5. Generate Sandbox credentials and save both secrets securely.
6. Use the portal's API Guides to test the payment flows you need and verify your webhooks.
7. Complete the Live-readiness steps before using real customer money.

It is different from an API secret and different from an individual payment reference. An API key belongs to a particular Business. You cannot make it operate another Business simply by changing the ID in the URL.

Credentials and payment references are Business-specific. However, Businesses belonging to the same account share that account's relevant wallet balances. Do not assume each profile automatically receives a financially separate wallet. If you need separate balances or a platform model for unrelated merchants, discuss the required structure with Fondeka.

Keep it on your server or in a secret manager. Do not place it in a public web page, a mobile-app bundle, a Git repository, a screenshot or a shared example. Your customers should interact with your application; they should not receive your secret key.

Use the API key to make requests. Use the webhook signing secret to verify incoming notifications. They are not interchangeable. The webhook guide explains the exact verification procedure, including preserving the original request-body bytes.

Save both values in a secure place at generation time. If you lose them, generate a replacement credential and update your server configuration. A masked key prefix does not contain enough information to reconstruct the original secret.

For an active key, you can edit its webhook destination in the portal without rotating the key or signing secret. Prepare the new receiver to verify the existing secret first. Keep the old receiver available during the change because an attempt already in flight can still use the previous destination.

For development, use a suitable public HTTPS tunnel or a deployed test receiver that forwards to your local development process. Test that it receives and verifies an actual Sandbox event before relying on it.

Revocation does not cancel already accepted payments. Their pending webhook events remain associated with the original credential and signing secret. Keep the necessary receiver and verification configuration for those payments until they have been reconciled.

The documentation also includes an OpenAPI reference and a Sandbox Postman collection. These are integration aids and examples; your production application still needs secure configuration, durable payment records, error handling and a verified webhook receiver.

Depending on the operator, the customer may need to approve the request on their phone. Your application follows the payment until it completes or fails. Deliver the product or service only after verified completion and the appropriate amount checks.

Read the Mobile Money collection guide.

For a Mobile Money collection, the payer uses the supported Mobile Money account associated with their phone number.

For a crypto collection, the customer follows the returned invoice instructions using a suitable external wallet or service. The payer must still meet the requirements of the payment method they are using.

Validate the phone number with the customer and match it to the selected country and operator. A phone number being well formatted does not by itself prove that the account exists, has enough money or can approve the requested operation.

Until the final outcome is established, do not automatically issue a replacement request. If the original payment is confirmed failed and the customer wants to try again, treat that as a deliberate new payment attempt with its own identity.

Once available, show the customer the returned asset, network, address, token quantity and expiry or invoice link. Your application must not invent an address, substitute a network or calculate its own token quantity from an assumed rate.

Read the crypto collection guide.

The fee mode, conversion and route can affect that quantity. Even when a token aims to track a fiat currency, your integration must display the quoted instructions rather than assuming a universal 1:1 relationship.

Your application needs a policy for differences: for example, holding an order for review instead of delivering automatically when the credited amount is insufficient. Do not invite payment to an expired invoice, and do not assume that sending money on another network will settle the original invoice.

A browser success page, customer screenshot, HTTP 202 response or unverified webhook is not sufficient evidence on its own. Keep your order-to-payment mapping and check the completed settlement before fulfilling.

The wallet must have enough available funds to cover the gross debit, including fees. When the request is accepted, the relevant amount is reserved or debited, and the payment is then processed. Confirm the final status before telling the recipient it is completed.

Read the Mobile Money payout guide.

The recipient receives the quoted token quantity on the selected network. Check the address and network carefully. A transfer to the wrong address or network may be unrecoverable, so do not infer compatibility from similar-looking address formats.

Read the crypto payout guide.

For an EXCLUSIVE payout of 100 USD with a returned 5 USD fee, the wallet needs 105 USD. Use the actual returned pricing for your operation. Sandbox needs virtual funds; Live needs real funds. A pending incoming collection is not available payout money before it has completed and been credited.

Some routes can depend on recipient or prior-funding eligibility. Treat the catalog as a way to choose supported identifiers and understand pricing, not as approval of every possible recipient or payout request.

Keep the original payment reference and retry identifier. If you submit a new logical payment because a previous one appears slow, you may create a separate payout. Prevent duplicate submissions and reconcile the original operation first.

Check the relevant wallet records and payment reference. If the refund is unclear, contact support. An unresolved payment can remain in processing with funds still reserved; sending another payout at that point can create an unwanted duplicate.

Contact support with the payment reference when you need help with an accepted operation. Whether funds can be recovered depends on the payment's state, the method and the actual financial outcome. Do not send a compensating payout automatically.

The collection does not become available money merely because it was submitted. Check completion, the settled currency and the actual net amount. If your application has several businesses or orders, keep your own records of which collection belongs to which activity.

Moving funds onward is a separate action using a supported account or payout flow, with its own availability, fees and requirements. If your business needs a particular bank-settlement arrangement, confirm it with Fondeka before designing your operations around it.

• The fiat request/wallet currency identifies the money value used by the API request, such as USD or KES.
• The payment method identifies the operator or crypto asset used for payment.
• The crypto network and token amount, when applicable, identify the actual blockchain instructions.

Keep those values separate in your application. For example, choosing a USDT method does not mean you should replace a USD fiat request currency with USDT.

API payments have their own dedicated history. Do not assume that the mobile app's general transaction list contains every API payment. Likewise, a Live wallet or transaction view should not be used to look for Sandbox virtual activity.

Within one environment, the relevant balances belong to the owning account. Multiple Businesses under that account can therefore share them, even though credentials, payment references and Business records are separate. Plan your internal accounting accordingly.

Minimums, maximums, verification requirements and available-balance rules also depend on the route and account. Check current information for your use case. A request accepted for processing can still have an unresolved outcome; do not turn a user-interface timeout into a claim that the payment failed.

“Pending” is a useful description for customers, but PENDING is not an additional status in this merchant response contract.

Read the payment-state reference.

The actual operation can complete or fail later. Do not mark an order as paid, release goods or tell a recipient that a payout is finished just because the submission returned 202.

orderReference is your own optional reference for the order, invoice or business event. Store a reliable link between your record and the Fondeka payment. Your order reference is not a replacement for the separate idempotency key used to prevent duplicate submissions.

The payment events cover completed and failed collections and payouts. Payments still accepted or processing do not produce a final-outcome event merely because time has passed. You can also check the payment through the lookup endpoint.

Delivery can repeat, for example when an acknowledgment is lost. Store verified event IDs and make order fulfillment safe to run more than once for the same payment reference. Receiving the same event twice should not deliver a digital product twice or send another payout.

Read the webhook signature and duplicate-delivery guide.

Your application should also be able to look up the stored payment reference and reconcile the result. Fix the receiver rather than submitting a new payment. Updating a webhook URL does not automatically replay every previously delivered or exhausted event.

Use a different key for a genuinely new payment. Store the original key and request durably on your server. Reusing a key with different payment information causes a conflict rather than safely changing the original operation.

Read the idempotency and safe-retry guide.

Do not automatically generate a new key and start another collection or payout. A network timeout says that your application did not obtain an answer; it does not establish that no payment was accepted. Investigate long-running payments with support while keeping their references intact.

You may be asked to provide information needed for account verification or review of your activity. Specific operations, especially payouts, can have additional eligibility requirements. Discuss your situation with support if you are unsure which requirements apply before going Live.

If your business model involves collecting for other merchants, holding money for third parties or another specialized flow, explain it to Fondeka before launch. A standard payment integration should not be assumed to include a separate platform, escrow or merchant-onboarding service.

You are also responsible for your customer communication and your own application. Fondeka provides the payment connection and related tools; it does not automatically resolve disputes about the goods or services your business sells.

Support can investigate using the Business ID, environment, Fondeka reference, request ID, approximate time and a description of the problem. Share sensitive customer information only through the appropriate support channel and only when it is needed for the investigation.

Your application should also prevent accidental double-click submissions and make fulfillment idempotent. These controls complement the API's own request validation and retry protection; they are part of operating a dependable payment feature.

Keep your Business information up to date and be ready to explain the activity behind your transactions when needed. Monitoring continues as your business develops; access is not a substitute for an accurate business profile.

Fondeka is intended to help you get started and build a working business. As you grow, direct integration may better fit your pricing, operational and account-management needs. We will discuss the appropriate next step with you rather than presenting Fondeka's average fee as the only long-term option.

A recommendation is not a guarantee that the aggregator will accept the business or offer a particular price. The aggregator makes its own onboarding decision and can request company documents, verification and other information. Your preparation and operating history will still matter.

Maintain clear business information, progress on your administrative documents, reliable payment records and a technical team able to manage the next integration. If you move to a direct provider, plan the transition so existing Fondeka payments, balances and webhook obligations can be reconciled correctly.

Check whether your offer includes the API and whether activation has completed. If you already paid or previously had access, refresh the current state and contact support with the relevant reference rather than making another payment immediately.

Read the returned error. If it is BUSINESS_API_LIVE_PAYMENTS_DISABLED, use Sandbox and confirm Live availability with Fondeka. If it relates to another requirement, correct that issue before retrying.

Check the exact error code and request ID. Use the correct authentication for the endpoint: merchant payment calls use the Business API key, while portal-management calls use the signed-in owner's session. Do not substitute one for the other.

A method appearing in a technical enum or a previous example does not make every route available. Show the returned error and offer another supported option only when appropriate; do not silently change the payment route or network.

For example, 100 USD available is not enough for an EXCLUSIVE 100 USD payout when the actual total debit is 105 USD. A Sandbox balance also cannot cover a Live payment.

Recover and reconcile the original operation before deciding to create a new one. Do not automatically respond to a conflict by generating another key, particularly for payouts. That could turn a recovery issue into an unwanted second payment.

Different endpoints can have different quotas. The current Sandbox funding rules allow up to 1,000,000 virtual currency units per top-up and 100 new top-ups per account/currency wallet per UTC day. Replaying the same successful top-up does not consume another slot. These are test-funding limits, not a statement of Live transaction capacity. Discuss expected production volumes with Fondeka.

Check the Business and selected environment. Sandbox records remain separate from Live records. If the payment is still missing from the correct view, provide its reference and request ID to support.

• The problem you are trying to solve and the expected result.
• Your Business ID and whether the issue is in Sandbox or Live.
• The operation: collection, payout, access activation, credential management or another action.
• The Fondeka payment or purchase reference, when one exists.
• The request ID, error code and approximate date/time.
• The country, operator or crypto network, currency and amount involved, when relevant.
• A description of what you have already checked, with secrets removed from any screenshot or sample.

This helps support distinguish a payment still processing from an access, configuration, integration or provider issue.

Contact us before paying if your decision depends on a particular operator, country/currency pair, Live launch date, document requirement, fee arrangement or high-volume business model. Explain your project and the payment flow you need. We can then help you assess the relevant access and integration steps.

You pay for API or bundle access, then pay the applicable fees for the operations you use. The average fee model combines approximately 3% aggregator fees and 2% Fondeka fees into one approximately 5% charge per operation, with actual operator-specific pricing available after access. Test with virtual money in Sandbox, confirm Live readiness separately, and keep payment confirmation and security built into your application. As your business grows, Fondeka can guide and recommend you toward direct aggregator integration.