Funding a wallet by card: the 3-D Secure deposit explained to integrators
In short
- The card deposit credits a user's wallet from their bank card. It is one of the ways to fund a balance, alongside cash-in at an agent.
- The journey: fee preview, execution, 3-D Secure authentication, card deposit authorized webhook, operation check.
- The golden rule: the balance updates on the confirmation (webhook and operation read), never on the redirect alone.
- Not to be confused with a merchant collecting a purchase, which belongs to a payment platform.
Why offer card deposits
A wallet with no simple way to fund it stays empty. In Morocco, two entry points complement each other: cash, deposited with an agent of the network using a reference, and the bank card, from the phone, at any time. Our guide to the e-wallet in Morocco places these uses in context, and the m-wallet in Morocco page describes Chari Money's white-label offer.
Card deposit is for apps that give their users a balance: a super app, a delivery app paying out its couriers' earnings, a services platform. It is not about collecting a purchase, but about turning money on a card into a wallet balance.
Prerequisites
- An active sandbox API key, requested from the API documentation.
- A registered customer: the deposit credits the wallet linked to their phone number. The "customer wallet" guide in the documentation describes sign-up, code confirmation and activation.
- To receive notifications: an HTTPS endpoint and the webhook key you provide to Chari Money, sent back in the
X-Api-Keyheader of each notification.
In the sandbox, a documented test card and its 3-D Secure code let you run the whole journey with no real money. See also our partner API sandbox page.
The journey step by step
1. Preview the deposit
Before any debit, the preview call checks that the deposit is feasible and returns the fees. The customer's phone number goes in a query parameter, the amount in the body. Show the user the amount, the fees and the total before they confirm.
2. Execute the deposit
The execution call carries the card details: number, CVV, expiry date in a four-digit year-month format. An option lets you keep the card as a token for later deposits. 3-D Secure is enabled by default, and the response indicates whether a redirect is needed, with the address of the authentication page.
3. Have the 3-D Secure authentication completed
If a redirect is requested, open the address provided in a browser. The cardholder authenticates with their bank, then is redirected to your success or failure address. The return address carries a response code, zero on success, and a readable reason code. Check both to decide the next screen.
4. Receive the card deposit authorized webhook
When the card deposit is accepted, Chari Money notifies your endpoint with the card deposit authorized event, as a JSON POST. The body carries your tracing identifier, the operation type (deposit), its status (completed), the method (card) and the transaction identifiers on the gateway side. Answer 200 OK within five seconds with an empty body.
5. Verify the operation
With the operation identifier received, read the operation detail: deposit type, completed status. The total amount returned is the amount after fees and commissions. Only after this check should the balance displayed to the user change.
Two useful variants
| Variant | What it is for | What changes |
|---|---|---|
| Deposit to an agent's wallet | Funding the balance of an agent in your network | The agent's code replaces the phone number; the 3-D Secure flow is the same |
| Deposit with a saved card | Topping up without re-entering the card | You fetch the saved card's identifier, then replay the deposit with the CVV and the amount only |
The agent variant matters to partners operating a cash-in and cash-out network: their agents can rebuild their balance without traveling.
Card and cash: combining ways to add money
Card deposit is not the only entry point to a wallet, and it should not be. Some of your users have no card, or prefer to pay in cash. For them, cash-in by reference through the agent network does the same job: your app creates a deposit request that generates a reference with a limited validity, the customer presents it to an agent, and the agent executes the operation.
Both journeys lead to the same result, a balance credited and confirmed by webhook. Offer them side by side on the "Add money" screen, with the fees of each shown before confirmation.
Also think about your customer's account level. The profile returned by the API shows a KYC level from 1 to 4, and a wallet's limits depend on that level: check it before offering a large deposit, and guide the user to the additional verification when needed, rather than letting the operation fail.
Good practices
- Confirm on the operation, not on the redirect. The browser return can be interrupted, replayed or tampered with; the webhook and the operation read prevail.
- Make processing idempotent. Without a 2xx answer, retries follow one another: after 1, 5, 30 and 60 minutes, then every six hours up to 72 hours in total. The same notification may therefore arrive several times.
- Trace every request. Send a unique
C-Request-Id: it comes back in the response and in the notification, and eases exchanges with support. - Protect card data. It passes through your server on its way to the API: never log it, and review your card data security obligations with your advisor.
- Explain failures. A refusal by the bank, an abandoned authentication or wrong details do not call for the same message; the reason code helps you tell them apart.
What not to confuse
The card deposit credits your user's wallet. A merchant that wants to collect a customer's purchase uses another tool: a hosted payment page, where the customer enters their card and authenticates with 3-D Secure without the merchant ever seeing the card number. That is the role of ChariPay, the payment platform operated by Chari Money; its guide 3-D Secure and success rates details what authentication changes for a merchant, and its guide to online payment in Morocco explains how to get paid.
Going further
Once card deposit is in place, the wallet balance can be used for everyday services: our guide to telecom top-ups and vouchers through the API shows how to add them, and the one on integrating bill payment completes the offer.
Next step
Request your sandbox access from the API documentation, have the card gateway enabled for your partner account and run the journey with the test card. A production launch remains subject to Bank Al-Maghrib's approval, through the granting of principal agent status, and any new use case requires the prior approval of the Banking Supervision Directorate.
Frequently Asked Questions
- How do you fund a wallet by card?
- With Chari Money's API, in four stages: preview the deposit to get the fees, execute it with the card details, have the cardholder complete 3-D Secure authentication, then confirm the credit when the webhook arrives and by reading the operation. The wallet credited is the one linked to the customer's phone number.
- Is 3-D Secure mandatory?
- In this journey, 3-D Secure is enabled by default. The execution response indicates whether a redirect is needed and provides the address of the authentication page. After authentication, the cardholder returns to your success or failure address, with a result code to check.
- Can the deposit be considered successful when the redirect returns?
- No. The redirect tells you the authentication result, but the wallet credit is confirmed when the card deposit authorized webhook arrives and by reading the operation: deposit type, completed status. That confirmation is what must update the displayed balance.
- Can the customer's card be saved?
- Yes. If you ask for the card to be kept at execution, it is saved as a token. Later deposits are replayed with the saved card's identifier, the CVV and the amount, without sending the card number again.
- What happens if my server does not answer the webhook?
- Answer 200 OK within five seconds. Any non-2xx code triggers a retry after 1, 5, 30 and 60 minutes, then every six hours up to 72 hours in total. Your processing must be idempotent, because a notification may arrive several times.
- I want to collect purchases by card: is it the same journey?
- No. The card deposit credits a user's wallet. To collect your customers' purchases as a merchant, Chari Money operates ChariPay: the customer pays on a hosted page with 3-D Secure and you never see a card number.