API Documentation

Complete reference for Chari Money's Banking-as-a-Service API. Integrate financial services into your applications with our robust and secure endpoints.

Getting Started

Version 2.1 · Last updated June 19, 2026

Welcome to the official documentation for Chari Money's Banking-as-a-Service (BAAS) API. This RESTful API empowers fintechs, platforms, and developers to integrate a complete financial infrastructure into their applications: account opening with KYC verification, wallet-to-wallet transactions, card deposits (3D Secure), bank wire transfers via RIB, multi-channel merchant payments (phone, QR Code, card), beneficiary management, retail agents, and real-time webhooks. All endpoints follow a preview/execute model with asynchronous webhook confirmation.

Authentication Headers

Include the following headers with all API requests:

Header	Type	Required	Description
`Chari-Api-Key`	string	Required	API key for authentication. Provided by Chari for each environment (sandbox / production).
`C-Request-Id`	string	Optional	Unique ID per request for tracing. Echoed back in the response. Recommended format: UUID v4. Ex: 69906411-0aa24a89-ab2005ca-9d18dc15

Test Credit Card (Sandbox)

PAN

4918914107195005

CVV

123

Expiry

08/26 (or any future date)

3DS Code

555

New

LLM & AI Pack

Complete pack optimized for LLMs and AI assistants: Markdown documentation, JSON Schemas, Mermaid diagrams, OpenAPI 3.0 spec, cURL examples and validation rules. Ideal for RAG, code generation and integration with Cursor, Copilot or Claude.

OpenAPI 3.0JSON SchemaMermaidMarkdowncURL

Download .zip

Postman Collection

Download the full Postman collection to test all API endpoints.

Download

Changelog

v1.8

2025-11-05

Initial documentation. Full API v1.8 coverage.

v1.8.1

2025-12-01

Added merchant-kyc-upload endpoint. Enriched reference tables (docTypes, customerStatuses, accountLevels). Detailed error codes with endpoint mapping. autoActivate parameter on confirm. Fixed confirm route.

v1.9

2026-04-14

Added Simulation (Sandbox) section. New Operation Types: 10=RECHARGE, 25=BILL_PAYMENT; renamed 5→MOBILE_PAYMENT, 24→CARD_PAYMENT. Transaction Status standardized: OPEN/COMPLETED/FAILED/CANCELED. Webhooks simplified: added payment.received, removed operation.created/operation.updated/customer.kyc/bank-transfer.failed. CashIn/CashOut reference format is now numeric (e.g. 1122334455).

v2.0

2026-06-04

Upgraded to v2.0 documentation (Preliminary Release). Added the "Card Management" section (beta): programs, applications, cards, card actions, usage control, transactions and card enums. The card section is preliminary and will be enriched with the missing endpoints — it may contain errors.

v2.1

2026-06-19

Added three new modules: Telco Top-up (catalog + recharge), Vouchers (catalog, brands, purchase preview/confirm) and Bill Payment (Fatourati network: creditors, receivables, dynamic form, unpaid items, confirmation, + webhooks). Added the dedicated Fatourati CashIn endpoint and operation type 23 = VOUCHER.

v2.2

2026-06-24

Documented the KYB documents required to create a merchant wallet, by professional client type (legal entity, individual professional, foundation / association) — added as notes on the "Merchant KYC Upload" endpoint.

Overview — M-Wallet in Morocco

What is an M-Wallet?

An M-Wallet (Mobile Wallet) is a regulated electronic money account that allows individuals and merchants to perform financial transactions using a mobile number as an identifier. It is part of the Bank Al-Maghrib (BAM) national framework for financial inclusion and digital payments. Each wallet is linked to a verified user identity (KYC) and stored under our Payment Institution license (CHARI MONEY) supervised by Bank Al-Maghrib.

Core Principles

Unique Wallet ID

The user's MSISDN (Mobile Number) serves as the wallet identifier.

Interoperable Network

All M-Wallets can exchange money between different providers through the national switch.

KYC Levels

Account permissions and limits depend on the user's verification (CIN, selfie, proof of address, etc.).

Real-Time Operations

Transfers, cash-in/out, merchant payments, and bill payments are executed instantly with confirmation.

Account Types

Type	Owner	Description	Operations
Consumer (Particulier)	Individuals	Personal wallet linked to one mobile number and national ID.	Cash-in/out, P2P transfers, merchant payments, other payment services.
Merchant (Commerçant)	Small business, shop, or service provider	Business wallet linked to a merchant account or store.	Receive payments, transfer to bank, refund customer, other payment services.
Agent Retail	Authorized agent network/partner	Used by distribution agents to facilitate cash-in/out for users.	Load/unload customer wallets.
Agent Principal	Partner / EDP	Dedicated wallet for enterprises with higher limits and integration solutions.	Mass payouts, salary disbursements, collections, multiple other operations.

Account Levels

Level	KYC Requirement	Balance Limit
Level 1	Name + valid phone + CIN number	1,000 MAD
Level 2	Full KYC (CIN + selfie or document scan)	4,000 MAD
Level 3	Verified ID (KYC), Interview, Digital customer record	20,000 MAD
Level 4	Full KYC, Interview, Digital customer record, Proof of income, Proof of address	100,000 MAD
Merchant	Full KYB + Business registration (IF/RC)	Negotiated

Glossary

Term	Definition
M-Wallet	A regulated electronic money account linked to a mobile number, allowing users to perform financial transactions such as transfers, payments, and cash operations.
Wallet	A user account within the system that stores electronic money and is associated with a unique identifier (MSISDN).
MSISDN	Mobile phone number used as the primary identifier of a wallet.
KYC (Know Your Customer)	Verification process used to identify and validate a user's identity according to regulatory requirements.
KYC Level	Regulatory level assigned to a wallet based on verification status, defining transaction and balance limits.
Operation	A high-level business action initiated by a user or partner (e.g., cash-in, transfer, payment).
Transaction	A financial movement (debit, credit, fees, adjustment) generated as part of an operation.
Operation Type	Category of business action (e.g., CASHIN, TRANSFER, PAYMENT).
Transaction Type	Type of financial movement associated with an operation (e.g., debit, credit, fees).
Operation Status	Current lifecycle state of an operation (e.g., OPEN, COMPLETED, FAILED).
Transaction Status	Processing state of a transaction (e.g., COMPLETED, FAILED).
Reference	A unique identifier generated for a pending operation (e.g., cash-in/out), used to complete the transaction through an external network.
Agent / Network	Authorized third-party entity or distribution channel used to execute cash-in and cash-out operations.
API Key	Secure token used to authenticate partner requests to the BAAS API.
Webhook	Automated HTTP callback sent by the system to notify partners about operation or transaction updates.

Customer Registration

Full customer lifecycle management: status check, registration, OTP confirmation, PIN management, balance and info retrieval, and unregistration.

GET{host}/api/customers/status

Check Status with Chari

Retrieve the current registration status of a customer with Chari only.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

Notes

•0 : Not exists — The number does not exist with ChariMoney.
•1 : Not confirmed — The number exists with ChariMoney but is not yet enrolled with Switch (OTP not entered).
•2 : Confirmed — The number exists and is registered with Switch.
•3 : Active — Registered with Switch and active with ChariMoney (PIN created).
•4 : Locked temporary — The number is temporarily blocked (max attempts exceeded).
•5 : Locked — The number is blocked.

GET{host}/api/customers/default

Check Status with Switch

Retrieve whether Chari is the default wallet for the customer.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

Notes

•true : Chari is the default wallet for the customer.
•false : Chari is NOT the default wallet for the customer.

POST{host}/api/customers/register202

Register

Initiate a new customer registration process. An OTP will be sent via SMS.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`firstName`	string	body	Required	Minimum 2 letters (latin characters only)
`lastName`	string	body	Required	Minimum 2 letters (latin characters only)
`cin`	string	body	Required	Minimum 5 characters
`walletType`	string	body	Required	"P": Particular (Particulier) / "C": Merchant (Commerçant)
`closeLoopOnly`	boolean	body	Optional	If true, enroll the customer in CloseLoop mode only. In that case, the OTP is sent directly by CHARI.

POST{host}/api/customers/confirm200

Confirm

Confirm a registration using OTP as a verification method.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`code`	string	body	Required	The received OTP code with format: xxx-xxx
`walletType`	string	body	Required	2 accepted types: "P": Particular (Particulier), "C": Merchant (Commerçant).
`autoActivate`	boolean	body	Optional	Default value: false. Indicates whether the wallet should be activated automatically after OTP validation. If false, the user must complete activation by setting or entering a PIN. If true, the wallet is activated automatically, without requiring a PIN.

POST{host}/api/customers/confirm/resend-otp

Resend OTP

Resend the One-Time Password for registration or confirmation.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

POST{host}/api/customers/login

Login with PIN

Authenticate an existing customer using their PIN.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`pin`	string	body	Required	PIN of the customer.

Notes

•logged : true if authentication succeeded, false otherwise.
•remainingAttempts : number of remaining attempts before account lockout.

POST{host}/api/customers/pin

Create PIN

Set up a secure PIN for a registered customer.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`pin`	string	body	Required	PIN of the customer. (4 numbers required)

PATCH{host}/api/customers/pin

Update PIN

Change an existing PIN for security or user preference.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`oldPin`	string	body	Required	Existing PIN of the customer.
`newPin`	string	body	Required	New PIN of the customer.

POST{host}/api/customers/pin/resetComing Soon

Reset PIN

Reset customer PIN. To be delivered in the next version.

No parameters required.

GET{host}/api/customers/balance

Get Customer Balance

Retrieve the balance of a registered customer.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

GET{host}/api/customers/info

Get Customer Info

Retrieve detailed profile data for a registered customer.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

Notes

•accountLevel : account level (1 = basic, 2-4 = higher KYC levels).
•customerStatus : customer status (see "Check Status with Chari" endpoint).
•rib : Bank Account Identifier (RIB) associated with the wallet.

PUT{host}/api/customers/unregister

Unregister

Deactivate or remove a customer from the platform.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	The customer's phone number. Format: +212*********
`Reason`	int	body	Required	Closure reason code (see notes).

Notes

•1 : Closure at the initiative of the EDP — Unspecified reason
•2 : Closure at the initiative of the EDP — Suspicion of fraud
•3 : Closure at the initiative of the client — Contract closure
•4 : Closure at the initiative of the client — Lost or stolen phone
•5 : Closure at the initiative of the client — Unspecified reason

KYC

Mobile KYC flow (iOS/Android) powered by ShareID. Your app launches the ShareID SDK for document scan and selfie capture; ShareID performs quality, authenticity, and face-to-document matching.

Integration Flow

1Your app calls "/kyc/shareid/auth" to obtain a short-lived KYC token.
2The app opens the ShareID SDK with that token.
3The user scans their ID and completes a guided selfie.
4ShareID runs the checks.
5Your app calls "/kyc/session/complete" to signal the flow has finished on-device.
6A callback is sent to our API with status and documents.

GET{host}/api/kyc/shareid/auth

Authentication

Obtain a short-lived KYC token to launch ShareID SDK.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********

Notes

•baseUrl : Base URL of the ShareID SDK to use.
•applicant_id : unique identifier of the KYC request.
•token : temporary JWT token for SDK-side authentication.

POST{host}/api/customers/upgrade/request

Confirmation

Signal the KYC flow has finished on-device and request account upgrade.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`AccountLevel`	int	query	Required	The account level to upgrade to (2, 3, or 4).

POST{host}/api/merchant/kyc/request

Merchant KYC Upload

Upload merchant KYC documents to request an account upgrade (multipart/form-data).

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Merchant phone number. Format: +212*********
`KycDocuments`	multipart form	body	Required	Array of KYC document objects. Multiple documents can be sent in a single request by repeating the indexed fields (e.g. kycDocuments[0], kycDocuments[1], ...).
`KycDocuments[n].DocType`	int	body	Required	Document type (see Document Types table).
`KycDocuments[n].DocFront`	file	body	Required	Front image of the document. Accepted formats: PNG, JPG/JPEG, PDF.
`KycDocuments[n].DocBack`	file	body	Optional	Back image (required for IdentityCard, DrivingLicense, ResidencePermit).

Notes

•KYB — the documents required to create a merchant (professional) wallet depend on the client's legal status. In all three cases the contract signatory's national ID or passport (DocType 1 or 3) and a bank-account proof — RIB / bank-account certificate, or a void cheque / cheque specimen — are required. Upload each document with its matching DocType from the Document Types table.
•Legal entity (company / organization): signatory's national ID / passport; company articles of association / statutes; minutes of the latest General Assembly confirming signing authority (required only if the manager / legal representative is not listed as the sole signatory in the statutes); Commercial Register certificate (DocType 8) less than 90 days old; Professional Tax registration certificate (Patente); bank-account proof (RIB or void cheque).
•Individual professional (auto-entrepreneur / freelancer / sole proprietor): signatory's national ID / passport; auto-entrepreneur card / professional registration document; Professional Tax registration certificate (Patente); bank-account proof (RIB or void cheque); Commercial Register certificate (DocType 8) less than 90 days old and company statutes, if applicable.
•Foundation / association: signatory's national ID / passport; minutes of the latest General Assembly confirming signing authority (required only if the authorized representative is not clearly named in the statutes); list of authorized representatives / board members; association / foundation statute; bank-account proof (RIB or void cheque).

Operations

All financial operations: card deposits, wallet-to-wallet transfers, bank transfers, merchant payments, chargebacks, refunds, and reference-based requests.

CashIn Card

Test Credit Card

Valid credit card numbers to add funds in sandbox environment.

PAN

4918914107195005

CVV

123

Expiry

08/26 (or any future date)

3DS Code

555

POST{host}/api/operations/cashin/card/preview

Preview (by Phone)

Check feasibility of depositing funds into a customer's wallet from a card.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Amount`	decimal	body	Required	Amount to deposit. Must be a positive number.

POST{host}/api/operations/cashin/card

Execute (by Phone)

Add funds to a customer's wallet from a payment card. Triggers 3D Secure authentication.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`FirstName`	string	body	Required	Cardholder's first name.
`LastName`	string	body	Required	Cardholder's last name.
`Cvv`	string	body	Required	3-digit security code (CVV).
`Amount`	decimal	body	Required	Amount to deposit.
`Currency`	string	body	Optional	3-letter ISO currency code (e.g. MAD).
`Pan`	string	body	Required	Full card number (PAN).
`ExpiryDate`	string	body	Required	Expiry date in YYMM format.
`KeepAlive`	bool	body	Required	true: save the card for future use / false: single use.
`CardName`	string	body	Optional	Name chosen by the user for the saved card.

Notes

•After 3D Secure authentication, the user is redirected to acceptURL or declineURL.
•RESPONSE_CODE in the redirect URL: 0 = success, any other value = failure.
•REASON_CODE : human-readable reason for the result (e.g., SUCCESS, DECLINED).
•Validate RESPONSE_CODE and REASON_CODE to determine the next action in your application.

POST{host}/api/operations/cashin/card/{cardId}

Execute with Saved Card

Add funds from a saved tokenized card.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`CardId`	int	route	Required	Identifier of the saved card.
`Cvv`	string	body	Required	3-digit security code.
`Amount`	decimal	body	Required	Amount to deposit.

Notes

•After 3D Secure authentication, the user is redirected to acceptURL or declineURL depending on the outcome.
•The redirect URL includes parameters: RESPONSE_CODE (0 = success, any other = failure), REASON_CODE (human-readable reason: SUCCESS, DECLINED…) and OPERATION (operation type, e.g. PAYMENT).
•Validate RESPONSE_CODE and REASON_CODE upon receiving the redirect to determine the next action in your application.

POST{host}/api/operations/cashin/card/agent/preview

Preview (by Agent)

Check feasibility of depositing funds via agent code.

Parameter	Type	In	Required	Description
`code`	string	query	Required	Agent code.
`Amount`	decimal	body	Required	Amount to deposit.

POST{host}/api/operations/cashin/card/agent

Execute (by Agent)

Add funds to a customer's wallet via agent.

Parameter	Type	In	Required	Description
`agent`	string	query	Required	Agent code.
`FirstName`	string	body	Required	Cardholder's first name.
`LastName`	string	body	Required	Cardholder's last name.
`Cvv`	string	body	Required	3-digit security code.
`Amount`	decimal	body	Required	Amount to deposit.
`Pan`	string	body	Required	Full card number.
`ExpiryDate`	string	body	Required	Expiry date in YYMM format.
`KeepAlive`	bool	body	Required	Save the card for future use.
`Currency`	string	body	Optional	The 3-letter ISO currency code (e.g., MAD).
`CardName`	string	body	Optional	Name chosen by the user to save the card.

Notes

•After 3D Secure authentication, the user is redirected to acceptURL or declineURL depending on the outcome.
•The redirect URL includes parameters: RESPONSE_CODE (0 = success, any other = failure), REASON_CODE (human-readable reason: SUCCESS, DECLINED…) and OPERATION (operation type, e.g. PAYMENT).
•Validate RESPONSE_CODE and REASON_CODE upon receiving the redirect to determine the next action in your application.

Transfer

POST{host}/api/operations/transfer/preview

Preview

Check feasibility of moving funds between customers' wallets internally.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Sender's phone number. Format: +212*********
`Amount`	decimal	body	Required	Amount to transfer.
`Reason`	string	body	Required	Transfer reason.
`RecipientPhoneNumber`	string	body	Required	Beneficiary's phone number. Format: +212*********
`BeneficiaryId`	int	body	Optional	Reference to an existing beneficiary (optional).

POST{host}/api/operations/transfer

Execute

Move funds between customers' wallets internally.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Sender's phone number.
`Amount`	decimal	body	Required	Amount to transfer.
`Reason`	string	body	Required	Transfer reason.
`RecipientPhoneNumber`	string	body	Required	Beneficiary's phone number.
`BeneficiaryId`	int	body	Optional	Reference to an existing beneficiary (optional).

Bank Transfer

POST{host}/api/operations/bank-transfer/preview

Preview

Check feasibility of sending money from a wallet to an external bank account.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Optional	Required if AgentCode is empty. Mutually exclusive with AgentCode (one OR the other).
`AgentCode`	string	body	Optional	Required if CustomerPhoneNumber is empty. Agent Code (Principal or Retail). Mutually exclusive with CustomerPhoneNumber.
`Amount`	decimal	body	Required	Amount to transfer.
`Reason`	string	body	Required	Transfer reason (latin characters only, max 35 chars).
`BeneficiaryId`	int	body	Optional	Optional if rib + beneficiaryName are provided.
`BeneficiaryName`	string	body	Optional	Optional if beneficiaryId is provided.
`Rib`	string	body	Optional	RIB: 24-digit numeric string. Optional if beneficiaryId is provided.

Notes

•At least one identifier among beneficiaryId or (rib + beneficiaryName) must be provided.

POST{host}/api/operations/bank-transfer

Execute

Send money from a wallet to an external bank account.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Optional	Required if AgentCode is empty. Mutually exclusive with AgentCode (one OR the other).
`AgentCode`	string	body	Optional	Required if CustomerPhoneNumber is empty. Mutually exclusive with CustomerPhoneNumber.
`Amount`	decimal	body	Required	Amount to transfer.
`Reason`	string	body	Optional	Transfer reason (optional at execute step).
`BeneficiaryId`	int	body	Optional	Optional if rib + beneficiaryName are provided.
`BeneficiaryName`	string	body	Optional	Optional if beneficiaryId is provided.
`Rib`	string	body	Optional	RIB: 24 digits. Required if no beneficiaryId.

Merchant Payment

POST{host}/api/operations/merchant/payment/push/manual/preview

By Phone — Preview

Check Pay Merchant by PhoneNumber.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Paying customer's phone number.
`Amount`	decimal	body	Required	Payment amount.
`Reason`	string	body	Required	Payment reason.
`RecipientPhoneNumber`	string	body	Required	The merchant's phone number.
`BeneficiaryId`	int	body	Optional	Reference to an existing beneficiary (optional).

POST{host}/api/operations/merchant/payment/push/manual

By Phone — Execute

Pay Merchant by PhoneNumber.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Paying customer's phone number.
`Amount`	decimal	body	Required	Payment amount.
`Reason`	string	body	Required	Payment reason.
`RecipientPhoneNumber`	string	body	Required	The merchant's phone number.
`BeneficiaryId`	int	body	Optional	Reference to an existing beneficiary (optional).

POST{host}/api/operations/merchant/payment/push/qrcode/preview

By QR Code — Preview

Check Pay Merchant by QR Code.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Paying customer's phone number.
`QrCodeContent`	string	body	Required	Content of the scanned QR Code.
`Amount`	decimal	body	Required	Payment amount.

POST{host}/api/operations/merchant/payment/push/qrcode

By QR Code — Execute

Pay Merchant by QR Code.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Paying customer's phone number.
`QrCodeContent`	string	body	Required	QR Code content.
`Amount`	decimal	body	Required	Payment amount.

POST{host}/api/operations/merchant/payment/push/card/preview

By Card — Preview

Check Pay Merchant by card (Card to Wallet).

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The merchant's phone number.
`Amount`	decimal	body	Required	Payment amount.

POST{host}/api/operations/merchant/payment/card

By Card — Execute

Pay Merchant by card (Card to Wallet). 3DS flow: the response provides `redirectionURL` to open.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The merchant's phone number. Format: +212*********
`FirstName`	string	body	Required	Cardholder's first name.
`LastName`	string	body	Required	Cardholder's last name.
`Cvv`	string	body	Required	CVV (3 digits).
`Amount`	decimal	body	Required	Payment amount.
`Pan`	string	body	Required	Card number (PAN).
`ExpiryDate`	string	body	Required	Expiry date in `YYMM` format. Ex: `2608`.
`KeepAlive`	bool	body	Required	Tokenize the card for reuse via the Tokenized Card endpoint.
`Currency`	string	body	Optional	Currency. Default: MAD.
`3dSecure`	bool	body	Optional	Enable 3D Secure. Default: true.
`FeesPercent`	decimal	body	Optional	Fee percentage applied to the payer.
`AllowInternationalCards`	bool	body	Optional	Accept international cards.
`InternationalFeesPercent`	decimal	body	Optional	Fee % specific to international cards.
`AutoCapture`	bool	body	Optional	Automatic payment capture.
`NotificationUrl`	string	body	Optional	URL notified when the transaction ends (success/failure).
`AcceptUrl`	string	body	Optional	Redirect URL on 3DS success.
`CardName`	string	body	Optional	Card label (for tokenization).
`ExternalReference`	string	body	Optional	Merchant external reference.

Notes

•After 3D Secure authentication, the user is redirected to acceptURL or declineURL depending on the outcome.
•The redirect URL includes parameters: RESPONSE_CODE (0 = success, any other = failure), REASON_CODE (human-readable reason: SUCCESS, DECLINED…) and OPERATION (operation type, e.g. PAYMENT).
•Validate RESPONSE_CODE and REASON_CODE upon receiving the redirect to determine the next action in your application.

POST{host}/api/operations/merchant/payment/tokenized/card/{cardId}

By Tokenized Card — Execute

Pay Merchant via a previously tokenized card (`KeepAlive = true`). Only the CVV is required.

Parameter	Type	In	Required	Description
`cardId`	int	path	Required	Tokenized card ID.
`PhoneNumber`	string	query	Required	The merchant's phone number. Format: +212*********
`Cvv`	string	body	Required	CVV (3 digits).
`Amount`	decimal	body	Required	Payment amount.

Notes

•Same response structure as "Merchant Payment By Card — Execute".
•After 3D Secure authentication, the user is redirected to acceptURL or declineURL depending on the outcome.
•The redirect URL includes parameters: RESPONSE_CODE (0 = success, any other = failure), REASON_CODE (human-readable reason) and OPERATION.

GET{host}/api/operations/merchant/qrcode/static

Static QR Generation

Generate a static QR Code for a merchant (no amount embedded). The customer enters the amount at payment time.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The merchant's phone number.
`MaskedNumber`	bool	query	Optional	Mask the merchant's number in the QR content. Ex: +2126######74

POST{host}/api/operations/merchant/qrcode

Dynamic QR Generation

Generate a dynamic QR Code with a fixed amount and a unique reference.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The merchant's phone number.
`MaskedNumber`	bool	query	Optional	Mask the merchant's number.
`Amount`	decimal	body	Required	Fixed amount of the QR Code.

Notes

•Static QR (GET): no embedded amount, the customer enters the amount at payment time.
•Dynamic QR (POST): fixed embedded amount, unique `qrCodeReference` reference.

ChargeBack

POST{host}/api/operations/chargeback/preview

Preview

Check the feasibility of performing a chargeback.

Parameter	Type	In	Required	Description
`SourcePhoneNumber`	string	body	Required	Originating customer's phone number. Format: +212*********
`Amount`	decimal	body	Required	Chargeback amount.
`Description`	string	body	Required	Chargeback reason.
`DestinationPhoneNumber`	string	body	Required	Recipient's phone number. Format: +212*********
`OriginalOperationId`	int	body	Required	ID of the original operation that triggered the chargeback.

POST{host}/api/operations/chargeback

Execute

Execute a chargeback operation.

Parameter	Type	In	Required	Description
`SourcePhoneNumber`	string	body	Required	Originating customer's phone number.
`Amount`	decimal	body	Required	Chargeback amount.
`Description`	string	body	Required	Chargeback reason.
`DestinationPhoneNumber`	string	body	Required	Recipient's phone number.
`OriginalOperationId`	int	body	Required	Original operation ID.

Request Operations

POST{host}/api/operations/cashin/request

Request CashIn

Request a CashIn operation. Generates a unique reference that expires over time.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	The customer's phone number.
`Amount`	decimal	body	Required	CashIn amount.

Notes

•operationType: 1 = CashIn, 2 = CashOut
•operationStatus: 1 = open, 2 = completed, 3 = failed, 4 = canceled

POST{host}/api/operations/fatourati/cashin/request

Request CashIn (Fatourati)

Initiate a CashIn operation via the Fatourati provider. Dedicated endpoint — Fatourati is a special provider with its own reference generation flow (FATREF- prefix). Use this dedicated route instead of the standard cashin endpoint; reference generation behavior and expiry rules may differ.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	The customer's phone number. For a principal agent, replace phoneNumber by the Agent Code (PhoneNumber => Code).
`Amount`	decimal	body	Required	The amount to cash in. Should be a positive numeric value.
`Description`	string	body	Optional	A free-text field describing the purpose of the operation.
`FeesPercent`	decimal	body	Optional	Fee percentage applied (shown in the documentation example).

Notes

•Dedicated endpoint: Fatourati has its own reference generation flow (FATREF- prefix), distinct from the standard CashIn flow.
•type (operationType): 1 = CashIn, 2 = CashOut
•status (operationStatus): 1 = open, 2 = completed, 3 = failed

POST{host}/api/operations/cashout/request

Request CashOut

Request a CashOut operation. Generates a unique reference that expires over time.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	The customer's phone number.
`Amount`	decimal	body	Required	CashOut amount.

Get Operations

GET{host}/api/operations

By Customer

Get a list of operations for a specific customer.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`PageSize`	int	query	Optional	Results per page. Default: 10.
`PageNumber`	int	query	Optional	Page number. Default: 1.
`OperationType`	list int	query	Optional	1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=MOBILE_PAYMENT, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 10=RECHARGE, 12=CHARGEBACK, 24=CARD_PAYMENT, 25=BILL_PAYMENT
`TransactionStatus`	int	query	Optional	1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED
`Sens`	int	query	Optional	1=CREDIT, 2=DEBIT
`From`	datetime	query	Optional	Filter start date/time.
`To`	datetime	query	Optional	Filter end date/time.

Notes

•collection: paginated list of operations.
•count: total number of operations matching the filters.
•accountNumber: can be a phone number, a RIB or an accountId.

GET{host}/api/operations/{id}

By ID

Get a specific operation by its ID.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`Id`	int	route	Required	Operation ID.

Notes

•operationId: identifier of the overall operation.
•transactionId: identifier of the main transaction (one operation can generate several transactions: sender debit, recipient credit, fees, etc.).
•transactionReference: reference of the main transaction.
•amount: initial amount.
•totalAmount: amount after fees and commissions are applied.

GET{host}/api/operations/all

All (by Partner)

Get a list of all operations by partner.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`PageSize`	int	query	Optional	Results per page. Default: 10.
`PageNumber`	int	query	Optional	Page number (starts at 1). Default: 1.
`OperationType`	list int	query	Optional	Filter by operation type.
`TransactionStatus`	int	query	Optional	Filter by transaction status.
`Sens`	int	query	Optional	1 = CREDIT, 2 = DEBIT.
`From`	datetime	query	Optional	Operations from datetime.
`To`	datetime	query	Optional	Operations until datetime.

GET{host}/api/operations/c-request-idComing Soon

Get Operation By C-Request-Id

Get an operation by its C-Request-Id. To be delivered in the next version.

No parameters required.

Refund

POST{host}/api/operations/refund/preview

Preview

Check refund feasibility after merchant payment.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	Phone number of the customer to refund.
`OperationId`	int	body	Required	ID of the operation to refund.
`RefundAmount`	decimal	body	Required	Refund amount.
`OrderId`	string	body	Required	Original paymentGateway OrderId.
`TransactionTrackId`	string	body	Required	Original paymentGateway TransactionTrackId.

POST{host}/api/operations/refund

Execute

Refund customers after merchant payment.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	The customer's phone number.
`OperationId`	int	body	Required	ID of the operation to refund.
`RefundAmount`	decimal	body	Required	Refund amount.
`OrderId`	string	body	Required	Original OrderId.
`TransactionTrackId`	string	body	Required	Original TransactionTrackId.

Beneficiary

Manage a customer's beneficiaries: list, add, update, and delete. Beneficiaries can be identified by phone number and/or RIB.

GET{host}/api/customer/beneficiaries

Get Beneficiaries

Get a list of beneficiaries for a customer.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`PageSize`	int	query	Optional	Results per page. Default: 10.
`PageNumber`	int	query	Optional	Page number. Default: 1.
`Search`	string	query	Optional	Filter by keyword.
`From`	datetime	query	Optional	Creation date — start.
`To`	datetime	query	Optional	Creation date — end.

POST{host}/api/customer/beneficiaries

Add Beneficiary

Add a new beneficiary. At least PhoneNumber or RIB must be provided.

Parameter	Type	In	Required	Description
`PhoneNumber (query)`	string	query	Required	Customer (owner) phone number.
`Name`	string	body	Required	Beneficiary name. Minimum 2 letters.
`PhoneNumber`	string	body	Optional	Beneficiary's phone number. Format: +212*********
`Rib`	string	body	Optional	Beneficiary RIB. 24 digits.
`Email`	string	body	Optional	Beneficiary email.

Notes

•PhoneNumber or RIB: at least one of the two must be provided.

PUT{host}/api/customer/beneficiaries/{id}

Update Beneficiary

Update an existing beneficiary.

Parameter	Type	In	Required	Description
`PhoneNumber (query)`	string	query	Required	Customer (owner) phone number.
`Id`	int	route	Required	Beneficiary ID to update.
`Name`	string	body	Required	Beneficiary name. Minimum 2 letters.
`PhoneNumber (body)`	string	body	Optional	Beneficiary phone number.
`Rib`	string	body	Optional	Beneficiary RIB. 24 digits.
`Email`	string	body	Optional	Beneficiary email.

DELETE{host}/api/customer/beneficiaries/{Id}

Delete Beneficiary

Delete an existing beneficiary.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`Id`	int	route	Required	ID of the beneficiary to delete.

Tokenized Cards

View and manage saved (tokenized) bank cards of a customer.

GET{host}/api/customers/tokenized/cards

Get Cards by Customer

Retrieve all tokenized cards for a customer.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`PageSize`	int	query	Optional	Results per page. Default: 10.
`PageNumber`	int	query	Optional	Page number. Default: 1.

Notes

•customerBankCardId: unique identifier for the saved card.
•maskedPan: masked card number (last 4 digits).
•issuer: name of the issuing bank.
•scheme: card network (Visa, Mastercard, etc.).
•cardName: optional label chosen by the customer at tokenization.

GET{host}/api/customers/tokenized/cards/{id}

Get Card by ID

Retrieve a specific tokenized card by its ID.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number.
`Id`	int	route	Required	Card ID.

DELETE{host}/api/customers/tokenized/cards/{id}Coming Soon

Delete Tokenized Card

Delete a tokenized card. To be delivered in the next version.

No parameters required.

Retail Agents

Manage retail agents: list, add, and execute CashIn/CashOut operations by reference.

GET{host}/api/agents/retail

Get Retail Agents

List all retail agents.

Parameter	Type	In	Required	Description
`Code`	string	query	Required	Agent code.
`PageSize`	int	query	Optional	Results per page. Default: 10.
`PageNumber`	int	query	Optional	Page number. Default: 1.
`From`	datetime	query	Optional	Agent creation — start date.
`To`	datetime	query	Optional	Agent creation — end date.

GET{host}/api/agents/retail/{code}

Get Agent by Code

Get a specific retail agent by code.

Parameter	Type	In	Required	Description
`Code`	string	route	Required	Agent code.

POST{host}/api/agents/retail

Add Retail Agent

Add a new retail agent.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	The agent's phone number. Format: +212*********
`Name`	string	body	Required	Agent's trade name.
`FirstName`	string	body	Required	First name. Minimum 2 letters.
`LastName`	string	body	Required	Last name. Minimum 2 letters.
`Cin`	string	body	Required	ID document number.
`Address`	string	body	Optional	Agent's address.
`Email`	string	body	Optional	Agent's email.

PUT{host}/api/agents/retail/{code}Coming Soon

Update Retail Agent

Update a retail agent. To be delivered in the next version.

No parameters required.

GET{host}/api/operations/cashin/request

Get CashIn by Reference

Retrieve requested operation details using a unique reference ID.

Parameter	Type	In	Required	Description
`Reference`	string	query	Required	Unique reference of the operation.

Notes

•type: 1 = CashIn, 2 = CashOut
•status: 1 = open, 2 = completed, 3 = failed

POST{host}/api/operations/cashin/agent

Execute CashIn by Reference

Execute a CashIn operation by the agent.

Parameter	Type	In	Required	Description
`Code`	string	body	Required	The code of the Agent performing the operation.
`Reference`	string	body	Required	The reference ID of the operation to retrieve.

GET{host}/api/operations/cashout/request

Get CashOut by Reference

Retrieve CashOut operation details by reference.

Parameter	Type	In	Required	Description
`Reference`	string	query	Required	Unique reference of the operation.

POST{host}/api/operations/cashout/agent

Execute CashOut by Reference

Execute a CashOut operation by the agent.

Parameter	Type	In	Required	Description
`Code`	string	body	Required	The code of the Agent performing the operation.
`Reference`	string	body	Required	The reference ID of the operation to retrieve.

Principal Agents

View information about a principal agent.

GET{host}/api/agents/principal

Get Principal Agent by Code

Get the account info of a principal agent.

Parameter	Type	In	Required	Description
`Code`	string	query	Required	The code of the principal agent.

Notes

•Response: Agent object + Account object (balance, RIB, level, etc.).

Card Management

Card issuing and management: card programs, applications, cards, usage control and transactions.

⚠️ Beta section. The bank card documentation is still preliminary: missing endpoints will be added and it may contain errors. If you run into any issue, contact Hedi ZaZ (VP of BaaS) on WhatsApp: wa.me/212600000010

GET{host}/api/cards/programs

Get Programs

Get a list of available programs for the partner.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	How many results are returned per page. Default value = 10.
`PageNumber`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default value = 1.

Notes

•collection : list of programs.
•count : count of programs.

GET{host}/api/cards/programs/{id}Coming Soon

Get Program By Id

To be delivered in the next version.

Parameter	Type	In	Required	Description
`Id`	int	route	Required	Card program identifier.

POST{host}/api/cards/applications

Add Application

Add a new card application.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`cardProgramId`	int	query	Required	Card program identifier.

Notes

•No body for now.

GET{host}/api/cards/applications

Get Applications

Get a list of applications by filters.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	How many results are returned per page. Default value = 10.
`PageNumber`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default value = 1.
`Status`	int	query	Optional	Filter by status: 1=Pending, 2=Validated, 3=Rejected.

Notes

•collection : list of applications.
•count : count of applications.
•CardApplicationStatus — 1: PENDING, 2: VALIDATED, 3: REJECTED.

GET{host}/api/cards/applications/customer

Get Application by Customer

Get a list of applications by customer.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	How many results are returned per page. Default value = 10.
`PageNumber`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default value = 1.

Notes

•collection : list of applications.
•count : count of applications.

PUT{host}/api/cards/applications/{id}/validate

Validate Application

Validate an existing application in progress.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Id`	int	route	Required	Application Id to validate.

Notes

•No body for now.

PUT{host}/api/cards/applications/{id}/reject

Reject Application

Reject an existing application in progress.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Id`	int	route	Required	Application Id to reject.

Notes

•No body for now.

GET{host}/api/cards

Get Cards

Get a list of cards by partner.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	How many results are returned per page. Default value = 10.
`PageNumber`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default value = 1.
`PhoneNumber`	string	query	Optional	The customer's phone number. Format: +212*********
`CardProgramId`	int	query	Optional	Card program id.
`DeliveryStatusId`	int	query	Optional	Delivery status id (see card enums).
`CardStatusId`	int	query	Optional	Card status id (see card enums).

Notes

•collection : list of cards.
•count : count of cards.
•CardType — 1: PHYSICAL, 2: VIRTUAL, 3: DIGITAL.
•DeliveryStatus — 1: PENDING, 2: SENT_TO_PERSONALIZATION, 3: READY_FOR_DELIVERY, 4: DELIVERED.
•CardStatus — 1: ISSUED, 2: ACTIVATED, 3: BLOCKED, 4: SUSPENDED, 5: EXPIRED, 6: CANCELLED.

GET{host}/api/cards/{id}

Get Card by Id

Get a specific card by id.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Id`	int	route	Required	Card Id.

PUT{host}/api/cards/{id}/{action}

Card actions

Run actions for the existing cards (activate, block, suspend, etc.).

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Id`	int	route	Required	Card Id to update.

Notes

•Available actions ({action}):
•/activate — Activate the card and make it ready for use.
•/block — Temporarily block the card from any transactions.
•/suspend — Suspend the card usage until further notice.
•/reactivate — Reactivate a previously suspended card.
•/cancel — Permanently cancel and deactivate the card.
•/unblock-pin — Unblock the card PIN after failed attempts.
•/reset-pin — Reset and generate a new card PIN.
•Response: true / false.

PUT{host}/api/cards/{id}/services

Card Usage Control

Update card services for usage control.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	The customer's phone number. Format: +212*********
`Id`	int	route	Required	Card Id to update.
`allowAtm`	bool	body	Required	Enable or disable ATM withdrawals for the card.
`allowOnline`	bool	body	Required	Enable or disable online/e-commerce transactions.
`allowPos`	bool	body	Required	Enable or disable POS (Point of Sale) payments.
`contactlessEnabled`	bool	body	Required	Enable or disable contactless payments.

Notes

•Response: true / false.

GET{host}/api/cards/{id}/transactions

Get Card Transactions

Get card transactions.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	How many results are returned per page. Default value = 10.
`PageNumber`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default value = 1.
`PhoneNumber`	string	query	Optional	The customer's phone number. Format: +212*********
`From`	datetime	query	Optional	Filter from date.
`To`	datetime	query	Optional	Filter to date.
`Id`	int	route	Required	Card Id.

Notes

•collection : list of transactions.
•count : count of transactions.

Simulation (Sandbox)

Sandbox-only simulation endpoints to complete CashIn/CashOut reference operations without interacting with a real agent network. Combine with the test card below to run an end-to-end flow.

Test Credit Card

Use this test card data for card deposit testing in sandbox environment.

PAN

4918914107195005

CVV

123

Expiry

08/26 (or any future date)

3DS Code

555

POST{host}/api/simulate/network/operations/cashin200

Simulate Network CashIn

Simulates execution of a CashIn by reference (network agent step). Triggers the `cashin.network.executed` webhook.

Parameter	Type	In	Required	Description
`reference`	string	body	Required	Numeric reference returned when the CashIn request was created.

POST{host}/api/simulate/network/operations/cashout200

Simulate Network CashOut

Simulates execution of a CashOut by reference (network agent step). Triggers the `cashout.network.executed` webhook.

Parameter	Type	In	Required	Description
`reference`	string	body	Required	Numeric reference returned when the CashOut request was created.

Webhooks

Webhooks let ChariBaaS notify your system about events (operation completed, KYC updates, etc.) in near-real time. Your server exposes an HTTPS endpoint; we POST signed JSON events to it.

HTTP Request

POSThttps://{your-domain}/webhooks/chari

You can provide any other endpoint.

Headers

Content-Type: application/jsonUser-Agent: Chari-BAAS-Webhook/1.0C-Webhook-Id: xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxxX-Api-Key: xxxxxxxx

•C-Webhook-Id: unique identifier of the webhook request, generated by Chari.
•X-Api-Key: secret key used to authenticate against your system (you must provide us with this key).

Expected response: 200 OK within 5s (empty body). In case of a business error or breach of contract sent by us, please return a 400 error with a description of the problem. Any non-2xx triggers a retry.

Event Body Properties

Common properties

Property	Type	Required	Description
`WebhookId`	string	Required	Webhook identifier.
`EventId`	string	Required	Event type. Ex: bank-transfer.initiated
`CRequestId`	string	Required	Tracking identifier received from the partner.
`OperationId`	int	Required	ID of the executed operation (can be 0 if no operation was created).
`TransactionId`	int	Optional	Main transaction ID.
`OperationType`	int	Required	Operation type code (see Types).
`OperationStatus`	int	Required	1 = Open, 2 = Completed, 3 = Failed, 4 = Canceled
`CreatedAt`	date	Required	Process start date.
`ExecutedAt`	date	Required	Operation execution date.
`Amount`	decimal	Required	Operation amount.
`FeeAmount`	decimal	Required	Fee amount.
`PrimaryAccountNumber`	string	Required	Sender's phone number.
`SecondaryAccountNumber`	string	Optional	Recipient's phone number.
`Method`	string	Optional	Method: Card / Agent / Network

Cash-in Card specific

Property	Type	Required	Description
`CustomData`	string	Optional	Custom data provided by the partner (max 128 characters).
`GatewayTrackId`	string	Optional	Gateway Transaction Track Id.
`GatewayOrderId`	string	Optional	Gateway Transaction Order Id.
`GatewayReferenceId`	string	Optional	Gateway Transaction Reference Id.

Bank Transfer specific

Property	Type	Required	Description
`BankTransferBeneficiaryName`	string	Optional	Beneficiary name for bank transfers.

Cash-in / Cash-out (network reference)

Property	Type	Required	Description
`NetworkName`	string	Optional	Network name for network operations.
`Reference`	string	Optional	Reference of the by-reference operation.

Retry Policy

Backoff:1m, 5m, 30m, 60m, then every 6h up to 72h total.

Stop:On first 200.

Dead letter:After 72h marked as undeliverable.

Events

Event ID	Description
`customer.level.updated`	Customer account level updated
`cashin.card.authorized`	CashIn by Card accepted
`payment.card.authorized`	Payment by Card accepted
`payment.received`	Payment received by merchant
`bank-transfer.initiated`	Bank transfer sent
`bank-transfer.completed`	Bank transfer finalized (settled, rejected, or returned — inspect OperationStatus)
`bank-transfer.received`	Bank transfer received
`transfer.received`	Transfer received
`cashin.network.executed`	CashIn by reference executed
`cashout.network.executed`	CashOut by reference executed

Example Event Body

Bank Transfer

json

{
  "data": {
    "WebhookId": 12345,
    "CRequestId": "a4d1e0b5-9f6a-4c1d-bc7b-2d0a7f4b9b12",
    "OperationId": 924381,
    "OperationType": 5,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T10:12:00Z",
    "ExecutedAt": "2025-11-05T10:12:22Z",
    "Amount": 25000.00,
    "FeeAmount": 350.00,
    "CustomData": "{\"note\":\"Salary for October\"}",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": "BankTransfer",
    "Reference": "BANK-REF-9FJ2X7",
    "BankTransferBeneficiaryName": "Aminata Diop"
  }
}

CashIn Card

json

{
  "data": {
    "WebhookId": 12346,
    "CRequestId": "7b8c9f1a-15da-4e1c-8c3b-3a2bd0ed5e6f",
    "OperationId": 563210,
    "OperationType": 1,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T09:41:00Z",
    "ExecutedAt": "2025-11-05T09:41:18Z",
    "Amount": 10000.00,
    "FeeAmount": 150.00,
    "CustomData": "ref12345",
    "PrimaryAccountNumber": "+212711111111",
    "Method": "Card",
    "GatewayTrackId": "83c1d1c7",
    "GatewayOrderId": "20251105_00045",
    "GatewayReferenceId": "6f92b0aa"
  }
}

Response Format

All API responses are wrapped in a `data` object. The C-Request-Id header you send is echoed back in the response.

C-Request-Id Header

Our API supports the C-Request-Id header to allow networks to track requests efficiently. You can include a unique C-Request-Id in the request headers, which will be echoed back in the response.

Telco Top-up

The Telco API provides a unified, secure interface for prepaid mobile top-up services. It exposes two services: retrieve the catalog of available recharge products, and trigger a top-up for a given phone number and selected offer, with real-time validation. Supported operators in Morocco: Maroc Telecom (IAM), Orange and Inwi.

POST{host}/api/services/telco/catalog/b2b

Retrieve Catalog

Get the list of available recharge products and offers for a given phone number and operator.

Parameter	Type	In	Required	Description
`RecipientPhoneNumber`	string	body	Required	The customer's phone number, in the required format: +212*********.
`Amount`	int	body	Required	The monetary value to be transacted. Should be a positive numeric value.
`Operator`	int	body	Required	Operator: 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.

Notes

•The data array contains the list of products available for the requested operator.
•Use productCode in the recharge endpoint to select the offer.

POST{host}/api/services/telco/recharge/b2b

Request Top-up

Initiate a mobile top-up for a given phone number and selected offer, with real-time validation and transaction tracking.

Parameter	Type	In	Required	Description
`RecipientPhoneNumber`	string	body	Required	The customer's phone number, in the required format: +212*********.
`Amount`	int	body	Required	The monetary value to be transacted. Should be a positive numeric value.
`Operator`	int	body	Required	Operator: 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
`ProductCode`	int	body	Required	The available product code, given by the catalog endpoint.
`Code`	string	body	Required	The principal agent code — the account that will be debited. Provided by Chari after activation of your Partner Account.
`RechargeType`	int	body	Required	Recharge type: 0 = Classic, 1 = Product.

Notes

•All three operators are supported: 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
•Code is the principal agent code (the debited account), provided by Chari after partner account activation.
•operationType: value 10 (see the "Types & References" table).

Vouchers

The Voucher API provides a standardized, secure interface to issue, manage and redeem digital vouchers within the BaaS ecosystem: value distribution and prepaid services (gift cards, game top-ups, etc.). The purchase flow follows a preview/confirm model.

GET{host}/api/vouchers/articles

Retrieve Catalog (articles)

Retrieve the current catalog: the list of voucher articles for a given brand.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number, in the format +212*********.
`brandId`	int	query	Required	Brand identifier. Should be a positive numeric value.
`page`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default: 1.
`take`	int	query	Optional	How many results are returned per page. Default: 10.

GET{host}/api/vouchers/brands

Retrieve Brands

Retrieve the current list of available voucher brands.

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	The customer's phone number, in the format +212*********.
`brandId`	int	query	Required	Brand identifier. Should be a positive numeric value.
`page`	int	query	Optional	Which page of results to retrieve. Starts at 1. Default: 1.
`take`	int	query	Optional	How many results are returned per page. Default: 10.

GET{host}/api/vouchers/brands/{id}

Get Brand by Id

Get a specific brand by its Id.

Parameter	Type	In	Required	Description
`id`	int	path	Required	Brand Id.
`phoneNumber`	string	query	Required	The customer's phone number, in the format +212*********.

GET{host}/api/vouchers/{id}/articles

Get Vouchers by Brand Id

Get the list of vouchers associated with a brand, by brand Id.

Parameter	Type	In	Required	Description
`id`	int	path	Required	Brand Id.
`phoneNumber`	string	query	Required	The customer's phone number, in the format +212*********.

Notes

•The response mirrors a Brand object, as defined in the source documentation.

POST{host}/api/operations/voucher/preview

Purchase Voucher — Preview

Check the feasibility of the voucher purchase operation (amount, fees) before confirmation.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	The customer phone number, in the format +212*********.
`DestinationPhoneNumber`	string	body	Required	The recipient's phone number, in the format +212*********.
`BeneficiaryName`	string	body	Required	A free-text field describing the beneficiary name.
`ProviderSkuId`	string	body	Required	The article identifier.
`ProviderId`	string	body	Required	The Id of the provider that supplies the voucher.

Notes

•type: value 23 (see the "Types & References" table).
•feesAmount is the fees; totalAmount is the total amount incl. tax.

POST{host}/api/operations/voucher/confirm

Purchase Voucher — Confirm

Execute the voucher purchase operation. Returns the voucher code and its details.

Parameter	Type	In	Required	Description
`customerPhoneNumber`	string	body	Required	The customer phone number, in the format +212*********.
`destinationPhoneNumber`	string	body	Required	The recipient's phone number, in the format +212*********.
`beneficiaryName`	string	body	Required	A free-text field describing the beneficiary name.
`providerSkuId`	string	body	Required	The article identifier.
`providerId`	string	body	Required	The Id of the provider that supplies the voucher.

Notes

•type / operation.operationType: value 23 (see the "Types & References" table).
•operation.code holds the voucher code to share with the beneficiary.
•cashBack: optional cashback amount.

Bill Payment

The Bill Payment module lets end users settle bills with creditors connected to the Fatourati network in Morocco (RADEEMA, LYDEC, IAM, TGR, AMENDIS, REDAL, and other Fatourati billers). The flow follows 5 steps: list creditors, list a creditor's receivables, fetch the dynamic identification form, retrieve unpaid items, then confirm payment. Single-creditor model (no multi-biller cart); partial payment supported. Sandbox base: https://sandbox.charimoney.com.

GET{host}/api/fatourati/creanciers

List Creditors

Returns the list of active creditors accessible to the partner via ChariBaaS (filtered by the partner's contract and Fatourati configuration). Since the response is relatively stable, caching for several hours on the partner side is acceptable.

No parameters required.

Notes

•codeRetour: 000 = ACCEPTE (success), 908 = Fatourati technical error.
•The response is relatively stable: caching for a few hours on the partner side is acceptable.

GET{host}/api/fatourati/creances?creancierId={creancierId}

List a Creditor's Receivables

Returns the list of active receivables exposed by a given creditor (a receivable corresponds to a service type: bill, top-up, tax…). A single creditor may expose several receivables.

Parameter	Type	In	Required	Description
`creancierId`	string	query	Required	Creditor identifier obtained via GET /creanciers (4 digits).

Notes

•codeRetour: 000 = ACCEPTE, 104 = creditor non-existent or inactive, 908 = technical error.

GET{host}/api/fatourati/form?creancierId={creancierId}&creanceId={creanceId}

Get Identification Form

Returns the schema of the dynamic customer-identification form for the (creditor, receivable) pair: fields to display (label, type, format, size, constraints). The partner MUST build their input screen from this response (no hardcoded form) to stay compatible with new creditors added to the Fatourati network.

Parameter	Type	In	Required	Description
`creancierId`	string	query	Required	Creditor identifier (4 digits).
`creanceId`	string	query	Required	Receivable identifier, always 2 positions (e.g., 01).

Notes

•typeChamp: text, select, password, libelle. A libelle field is static text (not editable) and must NEVER be sent in CreancierVals.
•formatChamp: 1 = string, 2 = integer, 3 = real. contrainte: 0 = optional, 1 = required.
•refTxFatourati: 1 = call /impayes (default value), 2 = sendRecharge (potentially obsolete).
•Return codes: 000 = ACCEPTE (success), 103 = receivable/service inactive for the chosen creditor, 104 = creditor non-existent, 908 = Fatourati technical error.

POST{host}/api/fatourati/impayes?creancierId={creancierId}&creanceId={creanceId}

Retrieve Unpaid Items

Submits the customer identification (entered via /form) and retrieves the customer's unpaid items with the creditor. This call opens the transaction (EN_ATTENTE state) and returns a refTxFatourati to use for /confirm. The association is valid for 7 calendar days (Fatourati timeout).

Parameter	Type	In	Required	Description
`creancierId`	string	query	Required	Creditor identifier (4 digits).
`creanceId`	string	query	Required	Receivable identifier (2 positions).
`CreancierVals`	array	body	Required	Array of user-entered values: { nomChamp, valeurChamp } objects (excluding typeChamp=libelle fields).

Notes

•The transaction moves to EN_ATTENTE; keep refTxFatourati for /confirm. Valid for 7 calendar days.
•codeDevise: 504 = MAD.
•typeFrais: forfait, commission, forfait_facture. valeurFrais = percentage × 100 (e.g., 1% → 100).
•typeArticle: 0 = receivable, 1 = fee, 2 = mandatory, 3 = stamp fee.
•globalParams: technical parameters with empty libelle (contrPaiement, isConfTO, isAnnul, rejoue, colAffiche) must never be shown to the customer.
•Key return codes: 000 = success (EN_ATTENTE), 103 = receivable inactive, 104 = creditor non-existent, 107 = no bill to pay, 109 = required field missing, 902/908/909/910/911 = technical/connection errors.
•Offline mode: a payment can also be initiated via a static 13-digit Fatourati reference (4 creditor + 2 receivable + 6 bill + 1 checksum), passed in CreancierVals.

POST{host}/api/fatourati/confirm?phoneNumber={phoneNumber}

Confirm Payment

Confirms payment of the article selection made by the end user. A 000 return code indicates effective settlement on the creditor's side. The end user is identified by their Chari Money phone number (phoneNumber query parameter).

Parameter	Type	In	Required	Description
`phoneNumber`	string	query	Required	End user's Chari Money phone number, international format (e.g., +212670770743). Must match an existing Chari Money user, otherwise the transaction is rejected before any call to Fatourati.
`creancierId`	string	body	Required	Creditor identifier (same values as /impayes).
`creanceId`	string	body	Required	Receivable identifier.
`refTxFatourati`	string	body	Required	Reference returned by /impayes. Links the call to the open transaction.
`CreancierVals`	array	body	Required	Enriched repeat of the identification fields (libelle + nomChamp + valeurChamp).
`ListeArticleSelectionnes`	array	body	Required	Subset of impayesParams selected by the user (idArticle, prixTTC, typeArticle, …).

Notes

•codeRetour 000 = CONFIRME (effective settlement). 301 = already processed (treat as success, show the receipt).
•Asynchronous behavior (digital channel): codes 908/909/910 are NOT definitive failures — the transaction stays in AUTORISE state and its final resolution (CONFIRME/ANNULE) is notified by webhook.
•refReglement must appear on the receipt. numCRC / texteCRC (params): display on the receipt if present.
•Module webhooks: payment.confirmed, payment.cancelled, payment.refunded, payment.failed — emitted to notify the final resolution (CONFIRME / ANNULE / REMBOURSE / FAILED states).

Types & References

Operation Types

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
5	MOBILE_PAYMENT
7	PAYMENT_REFUND
9	BANK_TRANSFER
10	RECHARGE
12	CHARGEBACK
23	VOUCHER
24	CARD_PAYMENT
25	BILL_PAYMENT

Transaction Types

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
5	MOBILE_PAYMENT
6	TRANSACTION_FEES
7	PAYMENT_REFUND
9	CHARGEBACK
10	CHARGEBACK_CANCELLATION
16	BANK_TRANSFER
17	RECHARGE
18	CASHBACK
24	CARD_PAYMENT
25	BILL_PAYMENT

Operation Statuses

ID	Code	Description
1	OPEN	Open (lifecycle in progress)
2	COMPLETED	Completed successfully
3	FAILED	Failed
4	CANCELED	Canceled

Transaction Statuses

ID	Code	Description
1	OPEN	Open (in progress)
2	COMPLETED	Completed
3	FAILED	Failed
4	CANCELED	Canceled

Transaction Direction (Sens)

ID	Code	Description
1	CREDIT	Credit (incoming funds)
2	DEBIT	Debit (outgoing funds)

Customer Statuses

ID	Code	Description
0	NOT_EXISTS	Number does not exist at ChariMoney
1	NOT_CONFIRMED	Exists but not confirmed (OTP not entered)
2	CONFIRMED	Confirmed and registered with Switch
3	ACTIVE	Registered, active, and PIN created
4	LOCKED_TEMPORARY	Temporarily locked (excessive attempts)
5	LOCKED	Locked

Account Levels

ID	Code	Description
1	LEVEL_1	Level 1 — Name + valid phone + CIN number. Limit: 1,000 MAD.
2	LEVEL_2	Level 2 — Full KYC (CIN + selfie or document scan). Limit: 4,000 MAD.
3	LEVEL_3	Level 3 — Verified ID + interview + digital customer record. Limit: 20,000 MAD.
4	LEVEL_4	Level 4 — Full KYC + interview + proof of income + proof of address. Limit: 100,000 MAD.
5	MERCHANT	Merchant — Full KYB + IF/RC business registration. Limit: negotiated.

Document Types

ID	Code	Description
1	IdentityCard	National identity card
2	DrivingLicense	Driving license
3	Passport	Passport
4	ResidencePermit	Residence permit
5	ProofOfIncome	Proof of income
6	ProofOfResidence	Proof of residence
7	Selfie	Selfie / Face photo
8	CommercialRegister	Commercial register

Error Codes

HTTP Status Codes

401 UnauthorizedAuthentication credentials (API KEY) not authorized.

422 UnprocessableThe server is unable to process the request.

423 LockedThe access is locked for the given customer.

400 Bad RequestCase-specific error with Chari error code.

Error Response Format

json

{
  "errorCode": 20005,
  "errorDescription": "The specified user could not be found."
}

Chari Error Codes

10xxxGeneral

Code	Message	Related Endpoints
10001	Missing Parameters.

20xxxCustomer

Code	Message	Related Endpoints
20000	The phone number format is invalid.
20005	The specified user could not be found.
20006	The initial parameters provided are incorrect or invalid.
20007	The Merchant Category Code (MCC) provided is incorrect or not recognized.
20008	Registration is temporarily locked due to security or policy restrictions.
20009	The request is pending confirmation. Please wait for further processing.
20017	There is no pending request associated with the provided Phone Number.

26xxxPIN / Authentication

Code	Message	Related Endpoints
26001	The entered PIN is incorrect.
26004	A PIN has already been set for this wallet.
26005	The provided PIN does not meet the required format (must be a 4-digit number).

27xxxBeneficiary

Code	Message	Related Endpoints
27000	The Beneficiary already exists with the same phoneNumber.
27001	The Beneficiary does not exist.

32xxxKYC / Upgrade

Code	Message	Related Endpoints
32000	An upgrade request is already under review for this account.

Infrastructure & Security

Environments

Sandbox

https://sandbox.charimoney.com

Development and testing. Transactions are simulated.

Production

Communiqué sur demande

Live transactions. Requires prior approval.

API Key Management

You will be assigned a dedicated API key for each environment (sandbox and production). Keys must be included in the Chari-Api-Key header of every request.

IP & Domain Whitelisting

You must share the IP addresses and/or domains that will be used to consume our API. Only whitelisted IPs/domains will be allowed to access the API. If your infrastructure changes, update your IP/domain list with the support team.

How to submit IPs / domains

1Provide a list of public IP addresses or domains that will be used to access the API.
2Send this information to the support team before attempting API integration.
3Any changes must be communicated at least 72 hours in advance so we can update our security rules.

Security & Compliance

•API authentication is handled using API Keys.
•Requests from non-whitelisted IPs/domains will be rejected.
•If an API key is compromised, it must be rotated immediately.
•Rate limiting may apply to prevent abuse.
•The production environment requires prior approval and testing in sandbox.

Next Steps for Integration

1
Request API keys
Contact support to receive your dedicated sandbox and production keys.
2
Submit IPs/domains
Provide the list of public IPs or domains for whitelisting.
3
Test in sandbox
Run all your integration tests in the sandbox environment.
4
Go to production
Once approved, switch to production with your live API key.

You will receive a form to fill out with the necessary elements.

API Documentation

Getting Started

Authentication Headers

Test Credit Card (Sandbox)

LLM & AI Pack

Postman Collection

Changelog

Overview — M-Wallet in Morocco

What is an M-Wallet?

Core Principles

Account Types

Account Levels

Glossary

Customer Registration

Customer Registration Flow

Check Status with Chari

Check Status with Switch

Register

Confirm

Resend OTP

Login with PIN

Create PIN

Update PIN

Reset PIN

Get Customer Balance

Get Customer Info

Unregister

KYC

KYC Flow (ShareID)

Integration Flow

Authentication

Confirmation

Merchant KYC Upload

Operations

CashIn Card

CashIn Card Flow (3D Secure)

Test Credit Card

Preview (by Phone)

Execute (by Phone)

Execute with Saved Card

Preview (by Agent)

Execute (by Agent)

Transfer

Wallet-to-Wallet Transfer Flow

Preview

Execute

Bank Transfer

Bank Transfer Flow

Preview

Execute

Merchant Payment

Merchant Payment Flow

By Phone — Preview

By Phone — Execute

By QR Code — Preview

By QR Code — Execute

By Card — Preview

By Card — Execute

By Tokenized Card — Execute

Static QR Generation

Dynamic QR Generation

ChargeBack

Chargeback Flow

Preview

Execute

Request Operations

CashIn/CashOut by Reference Flow

Request CashIn

Request CashIn (Fatourati)

Request CashOut

Get Operations

By Customer

By ID

All (by Partner)

Get Operation By C-Request-Id

Refund

Preview

Execute

Beneficiary

Beneficiary Management Flow