Skip to main content

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 1.9 · Last updated 14 avril 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:

HeaderTypeRequiredDescription
Chari-Api-KeystringRequiredAPI key for authentication. Provided by Chari for each environment (sandbox / production).
C-Request-IdstringOptionalUnique 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).

O

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

TypeOwnerDescriptionOperations
Consumer (Particulier)IndividualsPersonal 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 providerBusiness wallet linked to a merchant account or store.Receive payments, transfer to bank, refund customer, other payment services.
Agent RetailAuthorized agent network/partnerUsed by distribution agents to facilitate cash-in/out for users.Load/unload customer wallets.
Agent PrincipalPartner / EDPDedicated wallet for enterprises with higher limits and integration solutions.Mass payouts, salary disbursements, collections, multiple other operations.

Account Levels

LevelKYC RequirementBalance Limit
Level 1Name + valid phone + CIN number1 000 MAD
Level 2Full KYC (CIN + selfie or document scan)4 000 MAD
Level 3Verified ID (KYC), Interview, Digital customer record20 000 MAD
Level 4Full KYC, Interview, Digital customer record, Proof of income, Proof of address100 000 MAD
MerchantFull KYB + Business registration (IF/RC)Negotiated
G

Glossary

TermDefinition
M-WalletA regulated electronic money account linked to a mobile number, allowing users to perform financial transactions such as transfers, payments, and cash operations.
WalletA user account within the system that stores electronic money and is associated with a unique identifier (MSISDN).
MSISDNMobile 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 LevelRegulatory level assigned to a wallet based on verification status, defining transaction and balance limits.
OperationA high-level business action initiated by a user or partner (e.g., cash-in, transfer, payment).
TransactionA financial movement (debit, credit, fees, adjustment) generated as part of an operation.
Operation TypeCategory of business action (e.g., CASHIN, TRANSFER, PAYMENT).
Transaction TypeType of financial movement associated with an operation (e.g., debit, credit, fees).
Operation StatusCurrent lifecycle state of an operation (e.g., OPEN, COMPLETED, FAILED).
Transaction StatusProcessing state of a transaction (e.g., COMPLETED, FAILED).
ReferenceA unique identifier generated for a pending operation (e.g., cash-in/out), used to complete the transaction through an external network.
Agent / NetworkAuthorized third-party entity or distribution channel used to execute cash-in and cash-out operations.
API KeySecure token used to authenticate partner requests to the BAAS API.
WebhookAutomated HTTP callback sent by the system to notify partners about operation or transaction updates.
C

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredThe 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.

ParameterTypeInRequiredDescription
phoneNumberstringqueryRequiredThe 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.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
firstNamestringbodyRequiredMinimum 2 letters (latin characters only)
lastNamestringbodyRequiredMinimum 2 letters (latin characters only)
cinstringbodyRequiredMinimum 5 characters
walletTypestringbodyRequired"P": Particular (Particulier) / "C": Merchant (Commerçant)
closeLoopOnlybooleanbodyOptionalIf 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.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
codestringbodyRequiredThe received OTP code with format: xxx-xxx
walletTypestringbodyRequired2 accepted types: "P": Particular (Particulier), "C": Merchant (Commerçant).
autoActivatebooleanbodyOptionalDefault 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.

ParameterTypeInRequiredDescription
phoneNumberstringqueryRequiredThe customer's phone number. Format: +212*********
POST{host}/api/customers/login

Login with PIN

Authenticate an existing customer using their PIN.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
pinstringbodyRequiredPIN 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.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
pinstringbodyRequiredPIN of the customer. (4 numbers required)
PATCH{host}/api/customers/pin

Update PIN

Change an existing PIN for security or user preference.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
oldPinstringbodyRequiredExisting PIN of the customer.
newPinstringbodyRequiredNew 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.

ParameterTypeInRequiredDescription
phoneNumberstringqueryRequiredThe customer's phone number. Format: +212*********
GET{host}/api/customers/info

Get Customer Info

Retrieve detailed profile data for a registered customer.

ParameterTypeInRequiredDescription
phoneNumberstringqueryRequiredThe 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.

ParameterTypeInRequiredDescription
PhoneNumberstringbodyRequiredThe customer's phone number. Format: +212*********
ReasonintbodyRequiredClosure 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
K

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

  1. 1Your app calls "/kyc/shareid/auth" to obtain a short-lived KYC token.
  2. 2The app opens the ShareID SDK with that token.
  3. 3The user scans their ID and completes a guided selfie.
  4. 4ShareID runs the checks.
  5. 5Your app calls "/kyc/session/complete" to signal the flow has finished on-device.
  6. 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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredThe 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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredThe customer's phone number. Format: +212*********
AccountLevelintqueryRequiredThe 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).

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredMerchant phone number. Format: +212*********
KycDocumentsmultipart formbodyRequiredArray 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].DocTypeintbodyRequiredDocument type (see Document Types table).
KycDocuments[n].DocFrontfilebodyRequiredFront image of the document. Accepted formats: PNG, JPG/JPEG, PDF.
KycDocuments[n].DocBackfilebodyOptionalBack image (required for IdentityCard, DrivingLicense, ResidencePermit).
O

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client. Format : +212*********
AmountdecimalbodyRequiredMontant à déposer. Doit être un nombre positif.
POST{host}/api/operations/cashin/card

Execute (by Phone)

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

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
FirstNamestringbodyRequiredPrénom du titulaire de la carte.
LastNamestringbodyRequiredNom du titulaire de la carte.
CvvstringbodyRequiredCode de sécurité à 3 chiffres (CVV).
AmountdecimalbodyRequiredMontant à déposer.
CurrencystringbodyOptionalCode devise ISO 3 lettres (ex : MAD).
PanstringbodyRequiredNuméro complet de la carte (PAN).
ExpiryDatestringbodyRequiredDate d'expiration au format YYMM.
KeepAliveboolbodyRequiredtrue : sauvegarder la carte pour usage futur / false : usage unique.
CardNamestringbodyOptionalNom choisi par l'utilisateur pour sauvegarder la carte.

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
CardIdintrouteRequiredIdentifiant de la carte sauvegardée.
CvvstringbodyRequiredCode de sécurité à 3 chiffres.
AmountdecimalbodyRequiredMontant à déposer.

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.

ParameterTypeInRequiredDescription
codestringqueryRequiredCode de l'agent.
AmountdecimalbodyRequiredMontant à déposer.
POST{host}/api/operations/cashin/card/agent

Execute (by Agent)

Add funds to a customer's wallet via agent.

ParameterTypeInRequiredDescription
agentstringqueryRequiredCode de l'agent.
FirstNamestringbodyRequiredPrénom du titulaire de la carte.
LastNamestringbodyRequiredNom du titulaire de la carte.
CvvstringbodyRequiredCode de sécurité à 3 chiffres.
AmountdecimalbodyRequiredMontant à déposer.
PanstringbodyRequiredNuméro complet de la carte.
ExpiryDatestringbodyRequiredDate d'expiration au format YYMM.
KeepAliveboolbodyRequiredSauvegarder la carte pour usage futur.
CurrencystringbodyOptionalThe 3-letter ISO currency code (e.g., MAD).
CardNamestringbodyOptionalName 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.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro de l'émetteur. Format : +212*********
AmountdecimalbodyRequiredMontant à transférer.
ReasonstringbodyRequiredMotif du transfert.
RecipientPhoneNumberstringbodyRequiredNuméro du bénéficiaire. Format : +212*********
BeneficiaryIdintbodyOptionalRéférence à un bénéficiaire existant (optionnel).
POST{host}/api/operations/transfer

Execute

Move funds between customers' wallets internally.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro de l'émetteur.
AmountdecimalbodyRequiredMontant à transférer.
ReasonstringbodyRequiredMotif du transfert.
RecipientPhoneNumberstringbodyRequiredNuméro du bénéficiaire.
BeneficiaryIdintbodyOptionalReference 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.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyOptionalRequired if AgentCode is empty. Mutually exclusive with AgentCode (one OR the other).
AgentCodestringbodyOptionalRequired if CustomerPhoneNumber is empty. Agent Code (Principal or Retail). Mutually exclusive with CustomerPhoneNumber.
AmountdecimalbodyRequiredAmount to transfer.
ReasonstringbodyRequiredTransfer reason (latin characters only, max 35 chars).
BeneficiaryIdintbodyOptionalOptional if rib + beneficiaryName are provided.
BeneficiaryNamestringbodyOptionalOptional if beneficiaryId is provided.
RibstringbodyOptionalRIB: 24-digit numeric string. Optional if beneficiaryId is provided.

Notes

  • Au moins un identifiant parmi beneficiaryId ou (rib + beneficiaryName) doit être fourni.
POST{host}/api/operations/bank-transfer

Execute

Send money from a wallet to an external bank account.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyOptionalRequired if AgentCode is empty. Mutually exclusive with AgentCode (one OR the other).
AgentCodestringbodyOptionalRequired if CustomerPhoneNumber is empty. Mutually exclusive with CustomerPhoneNumber.
AmountdecimalbodyRequiredAmount to transfer.
ReasonstringbodyOptionalTransfer reason (optional at execute step).
BeneficiaryIdintbodyOptionalOptional if rib + beneficiaryName are provided.
BeneficiaryNamestringbodyOptionalOptional if beneficiaryId is provided.
RibstringbodyOptionalRIB: 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.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro du client payeur.
AmountdecimalbodyRequiredMontant du paiement.
ReasonstringbodyRequiredMotif du paiement.
RecipientPhoneNumberstringbodyRequiredNuméro du marchand.
BeneficiaryIdintbodyOptionalReference to an existing beneficiary (optional).
POST{host}/api/operations/merchant/payment/push/manual

By Phone — Execute

Pay Merchant by PhoneNumber.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro du client payeur.
AmountdecimalbodyRequiredMontant du paiement.
ReasonstringbodyRequiredMotif du paiement.
RecipientPhoneNumberstringbodyRequiredNuméro du marchand.
BeneficiaryIdintbodyOptionalReference to an existing beneficiary (optional).
POST{host}/api/operations/merchant/payment/push/qrcode/preview

By QR Code — Preview

Check Pay Merchant by QR Code.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro du client payeur.
QrCodeContentstringbodyRequiredContenu du QR Code scanné.
AmountdecimalbodyRequiredMontant du paiement.
POST{host}/api/operations/merchant/payment/push/qrcode

By QR Code — Execute

Pay Merchant by QR Code.

ParameterTypeInRequiredDescription
CustomerPhoneNumberstringbodyRequiredNuméro du client payeur.
QrCodeContentstringbodyRequiredContenu du QR Code.
AmountdecimalbodyRequiredMontant du paiement.
POST{host}/api/operations/merchant/payment/push/card/preview

By Card — Preview

Check Pay Merchant by card (Card to Wallet).

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro du marchand.
AmountdecimalbodyRequiredMontant du paiement.
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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro du marchand. Format : +212*********
FirstNamestringbodyRequiredPrénom du titulaire.
LastNamestringbodyRequiredNom du titulaire.
CvvstringbodyRequiredCVV (3 chiffres).
AmountdecimalbodyRequiredMontant du paiement.
PanstringbodyRequiredNuméro de carte (PAN).
ExpiryDatestringbodyRequiredDate d'expiration au format `YYMM`. Ex : `2608`.
KeepAliveboolbodyRequiredTokenizer la carte pour réutilisation via l'endpoint Tokenized Card.
CurrencystringbodyOptionalDevise. Par défaut : MAD.
3dSecureboolbodyOptionalActiver 3D Secure. Par défaut : true.
FeesPercentdecimalbodyOptionalPourcentage de frais appliqués au payeur.
AllowInternationalCardsboolbodyOptionalAccepter les cartes internationales.
InternationalFeesPercentdecimalbodyOptionalFrais % spécifiques aux cartes internationales.
AutoCaptureboolbodyOptionalCapture automatique du paiement.
NotificationUrlstringbodyOptionalURL notifiée après fin de transaction (succès/échec).
AcceptUrlstringbodyOptionalURL de redirection en cas de succès 3DS.
CardNamestringbodyOptionalLibellé de la carte (pour tokenisation).
ExternalReferencestringbodyOptionalRéférence externe du marchand.

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.

ParameterTypeInRequiredDescription
cardIdintpathRequiredID de la carte tokenisée.
PhoneNumberstringqueryRequiredNuméro du marchand. Format : +212*********
CvvstringbodyRequiredCVV (3 chiffres).
AmountdecimalbodyRequiredMontant du paiement.

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro du marchand.
MaskedNumberboolqueryOptionalMasquer le numéro du marchand dans le contenu QR. 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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro du marchand.
MaskedNumberboolqueryOptionalMasquer le numéro du marchand.
AmountdecimalbodyRequiredMontant fixe du QR Code.

Notes

  • QR statique (GET) : aucun montant intégré, le client saisit le montant au paiement.
  • QR dynamique (POST) : montant fixe intégré, référence unique `qrCodeReference`.

ChargeBack

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

Preview

Check the feasibility of performing a chargeback.

ParameterTypeInRequiredDescription
SourcePhoneNumberstringbodyRequiredNuméro du client à l'origine. Format : +212*********
AmountdecimalbodyRequiredMontant du chargeback.
DescriptionstringbodyRequiredMotif du chargeback.
DestinationPhoneNumberstringbodyRequiredNuméro du destinataire. Format : +212*********
OriginalOperationIdintbodyRequiredID de l'opération d'origine qui a déclenché le chargeback.
POST{host}/api/operations/chargeback

Execute

Execute a chargeback operation.

ParameterTypeInRequiredDescription
SourcePhoneNumberstringbodyRequiredNuméro du client à l'origine.
AmountdecimalbodyRequiredMontant du chargeback.
DescriptionstringbodyRequiredMotif du chargeback.
DestinationPhoneNumberstringbodyRequiredNuméro du destinataire.
OriginalOperationIdintbodyRequiredID de l'opération d'origine.

Request Operations

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

Request CashIn

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

ParameterTypeInRequiredDescription
PhoneNumberstringbodyRequiredNuméro de téléphone du client.
AmountdecimalbodyRequiredMontant du CashIn.

Notes

  • operationType : 1 = CashIn, 2 = CashOut
  • operationStatus : 1 = open, 2 = completed, 3 = failed, 4 = canceled
POST{host}/api/operations/cashout/request

Request CashOut

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

ParameterTypeInRequiredDescription
PhoneNumberstringbodyRequiredNuméro de téléphone du client.
AmountdecimalbodyRequiredMontant du CashOut.

Get Operations

GET{host}/api/operations

By Customer

Get a list of operations for a specific customer.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
PageSizeintqueryOptionalRésultats par page. Par défaut : 10
PageNumberintqueryOptionalNuméro de page. Par défaut : 1
OperationTypelist intqueryOptional1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=MOBILE_PAYMENT, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 10=RECHARGE, 12=CHARGEBACK, 24=CARD_PAYMENT, 25=BILL_PAYMENT
TransactionStatusintqueryOptional1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED
SensintqueryOptional1=CREDIT, 2=DEBIT
FromdatetimequeryOptionalDate/heure de début du filtre.
TodatetimequeryOptionalDate/heure de fin du filtre.

Notes

  • collection : liste paginée des opérations.
  • count : nombre total d'opérations correspondant aux filtres.
  • accountNumber : peut être un numéro de téléphone, un RIB ou un accountId.
GET{host}/api/operations/{id}

By ID

Get a specific operation by its ID.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
IdintrouteRequiredID de l'opération.

Notes

  • operationId : identifiant de l'opération globale.
  • transactionId : identifiant de la transaction principale (une opération peut générer plusieurs transactions : débit émetteur, crédit destinataire, frais, etc.).
  • transactionReference : référence de la transaction principale.
  • amount : montant initial.
  • totalAmount : montant après application des frais et commissions.
GET{host}/api/operations/all

All (by Partner)

Get a list of all operations by partner.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredThe customer's phone number. Format: +212*********
PageSizeintqueryOptionalResults per page. Default: 10.
PageNumberintqueryOptionalPage number (starts at 1). Default: 1.
OperationTypelist intqueryOptionalFilter by operation type.
TransactionStatusintqueryOptionalFilter by transaction status.
SensintqueryOptional1 = CREDIT, 2 = DEBIT.
FromdatetimequeryOptionalOperations from datetime.
TodatetimequeryOptionalOperations 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.

ParameterTypeInRequiredDescription
PhoneNumberstringbodyRequiredNuméro du client à rembourser.
OperationIdintbodyRequiredID de l'opération à rembourser.
RefundAmountdecimalbodyRequiredMontant du remboursement.
OrderIdstringbodyRequiredOrderId original du paymentGateway.
TransactionTrackIdstringbodyRequiredTransactionTrackId original du paymentGateway.
POST{host}/api/operations/refund

Execute

Refund customers after merchant payment.

ParameterTypeInRequiredDescription
phoneNumberstringbodyRequiredNuméro du client.
OperationIdintbodyRequiredID de l'opération à rembourser.
RefundAmountdecimalbodyRequiredMontant du remboursement.
OrderIdstringbodyRequiredOrderId original.
TransactionTrackIdstringbodyRequiredTransactionTrackId original.
B

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
PageSizeintqueryOptionalRésultats par page. Par défaut : 10
PageNumberintqueryOptionalNuméro de page. Par défaut : 1
SearchstringqueryOptionalFiltrer par mot-clé.
FromdatetimequeryOptionalDate de création — début.
TodatetimequeryOptionalDate de création — fin.
POST{host}/api/customer/beneficiaries

Add Beneficiary

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

ParameterTypeInRequiredDescription
PhoneNumber (query)stringqueryRequiredNuméro de téléphone du client (propriétaire).
NamestringbodyRequiredNom du bénéficiaire. Minimum 2 lettres.
PhoneNumberstringbodyOptionalNuméro du bénéficiaire. Format : +212*********
RibstringbodyOptionalRIB du bénéficiaire. 24 chiffres.
EmailstringbodyOptionalEmail du bénéficiaire.

Notes

  • PhoneNumber ou RIB : au moins l'un des deux doit être fourni.
PUT{host}/api/customer/beneficiaries/{id}

Update Beneficiary

Update an existing beneficiary.

ParameterTypeInRequiredDescription
PhoneNumber (query)stringqueryRequiredCustomer (owner) phone number.
IdintrouteRequiredBeneficiary ID to update.
NamestringbodyRequiredBeneficiary name. Minimum 2 letters.
PhoneNumber (body)stringbodyOptionalBeneficiary phone number.
RibstringbodyOptionalBeneficiary RIB. 24 digits.
EmailstringbodyOptionalBeneficiary email.
DELETE{host}/api/customer/beneficiaries/{Id}

Delete Beneficiary

Delete an existing beneficiary.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
IdintrouteRequiredID du bénéficiaire à supprimer.
T

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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
PageSizeintqueryOptionalRésultats par page. Par défaut : 10
PageNumberintqueryOptionalNuméro de page. Par défaut : 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.

ParameterTypeInRequiredDescription
PhoneNumberstringqueryRequiredNuméro de téléphone du client.
IdintrouteRequiredID de la carte.
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.

R

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.

ParameterTypeInRequiredDescription
CodestringqueryRequiredCode de l'agent.
PageSizeintqueryOptionalRésultats par page. Par défaut : 10
PageNumberintqueryOptionalNuméro de page. Par défaut : 1
FromdatetimequeryOptionalCréation de l'agent — date début.
TodatetimequeryOptionalCréation de l'agent — date fin.
GET{host}/api/agents/retail/{code}

Get Agent by Code

Get a specific retail agent by code.

ParameterTypeInRequiredDescription
CodestringrouteRequiredCode de l'agent.
POST{host}/api/agents/retail

Add Retail Agent

Add a new retail agent.

ParameterTypeInRequiredDescription
PhoneNumberstringbodyRequiredNuméro de téléphone de l'agent. Format : +212*********
NamestringbodyRequiredNom commercial de l'agent.
FirstNamestringbodyRequiredPrénom. Minimum 2 lettres.
LastNamestringbodyRequiredNom de famille. Minimum 2 lettres.
CinstringbodyRequiredNuméro de pièce d'identité.
AddressstringbodyOptionalAdresse de l'agent.
EmailstringbodyOptionalEmail de l'agent.
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.

ParameterTypeInRequiredDescription
ReferencestringqueryRequiredRéférence unique de l'opération.

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.

ParameterTypeInRequiredDescription
CodestringbodyRequiredThe code of the Agent performing the operation.
ReferencestringbodyRequiredThe reference ID of the operation to retrieve.
GET{host}/api/operations/cashout/request

Get CashOut by Reference

Retrieve CashOut operation details by reference.

ParameterTypeInRequiredDescription
ReferencestringqueryRequiredRéférence unique de l'opération.
POST{host}/api/operations/cashout/agent

Execute CashOut by Reference

Execute a CashOut operation by the agent.

ParameterTypeInRequiredDescription
CodestringbodyRequiredThe code of the Agent performing the operation.
ReferencestringbodyRequiredThe reference ID of the operation to retrieve.
P

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.

ParameterTypeInRequiredDescription
CodestringqueryRequiredThe code of the principal agent.

Notes

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

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.

ParameterTypeInRequiredDescription
referencestringbodyRequiredNumeric 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.

ParameterTypeInRequiredDescription
referencestringbodyRequiredNumeric reference returned when the CashOut request was created.
W

Webhooks

Webhooks let Chari BAAS 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

Vous pouvez fournir tout autre endpoint.

Headers

Content-Type: application/jsonUser-Agent: Chari-BAAS-Webhook/1.0C-Webhook-Id: xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxxX-Api-Key: xxxxxxxx
  • C-Webhook-Id : identifiant unique de la requête webhook, généré par Chari.
  • X-Api-Key : clé secrète pour l'authentification de votre système (vous devez nous fournir cette clé).

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

PropertyTypeRequiredDescription
WebhookIdstringRequiredIdentifiant du webhook.
EventIdstringRequiredType d'événement. Ex : bank-transfer.initiated
CRequestIdstringRequiredIdentifiant de traçage reçu du partenaire.
OperationIdintRequiredID de l'opération exécutée (peut être 0 si aucune opération créée).
TransactionIdintOptionalID de la transaction principale.
OperationTypeintRequiredCode du type d'opération (voir Types).
OperationStatusintRequired1 = Open, 2 = Completed, 3 = Failed, 4 = Canceled
CreatedAtdateRequiredDate de début du processus.
ExecutedAtdateRequiredDate d'exécution de l'opération.
AmountdecimalRequiredMontant de l'opération.
FeeAmountdecimalRequiredMontant des frais.
PrimaryAccountNumberstringRequiredNuméro de téléphone de l'émetteur.
SecondaryAccountNumberstringOptionalNuméro de téléphone du destinataire.
MethodstringOptionalMéthode : Card / Agent / Network

Cash-in Card specific

PropertyTypeRequiredDescription
CustomDatastringOptionalDonnées personnalisées fournies par le partenaire (max 128 caractères).
GatewayTrackIdstringOptionalGateway Transaction Track Id.
GatewayOrderIdstringOptionalGateway Transaction Order Id.
GatewayReferenceIdstringOptionalGateway Transaction Reference Id.

Bank Transfer specific

PropertyTypeRequiredDescription
BankTransferBeneficiaryNamestringOptionalNom du bénéficiaire pour les virements bancaires.

Cash-in / Cash-out (network reference)

PropertyTypeRequiredDescription
NetworkNamestringOptionalNom du réseau pour les opérations réseau.
ReferencestringOptionalRéférence de l'opération par référence.

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 IDDescription
customer.level.updatedCustomer account level updated
cashin.card.authorizedCashIn by Card accepted
payment.card.authorizedPayment by Card accepted
payment.receivedPayment received by merchant
bank-transfer.initiatedBank transfer sent
bank-transfer.completedBank transfer finalized (settled, rejected, or returned — inspect OperationStatus)
bank-transfer.receivedBank transfer received
transfer.receivedTransfer received
cashin.network.executedCashIn by reference executed
cashout.network.executedCashOut 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"
  }
}
R

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.

T

Types & References

Operation Types

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

Transaction Types

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

Operation Statuses

IDCodeDescription
1OPENOpen (lifecycle in progress)
2COMPLETEDCompleted successfully
3FAILEDFailed
4CANCELEDCanceled

Transaction Statuses

IDCodeDescription
1OPENOpen (in progress)
2COMPLETEDCompleted
3FAILEDFailed
4CANCELEDCanceled

Transaction Direction (Sens)

IDCodeDescription
1CREDITCredit (incoming funds)
2DEBITDebit (outgoing funds)

Customer Statuses

IDCodeDescription
0NOT_EXISTSNumber does not exist at ChariMoney
1NOT_CONFIRMEDExists but not confirmed (OTP not entered)
2CONFIRMEDConfirmed and registered with Switch
3ACTIVERegistered, active, and PIN created
4LOCKED_TEMPORARYTemporarily locked (excessive attempts)
5LOCKEDLocked

Account Levels

IDCodeDescription
1LEVEL_1Level 1 — Name + valid phone + CIN number. Limit: 1,000 MAD.
2LEVEL_2Level 2 — Full KYC (CIN + selfie or document scan). Limit: 4,000 MAD.
3LEVEL_3Level 3 — Verified ID + interview + digital customer record. Limit: 20,000 MAD.
4LEVEL_4Level 4 — Full KYC + interview + proof of income + proof of address. Limit: 100,000 MAD.
5MERCHANTMerchant — Full KYB + IF/RC business registration. Limit: negotiated.

Document Types

IDCodeDescription
1IdentityCardNational identity card
2DrivingLicenseDriving license
3PassportPassport
4ResidencePermitResidence permit
5ProofOfIncomeProof of income
6ProofOfResidenceProof of residence
7SelfieSelfie / Face photo
8CommercialRegisterCommercial register
E

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

CodeMessageRelated Endpoints
10001Missing Parameters.

20xxxCustomer

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

26xxxPIN / Authentication

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

27xxxBeneficiary

CodeMessageRelated Endpoints
27000The Beneficiary already exists with the same phoneNumber.
27001The Beneficiary does not exist.

32xxxKYC / Upgrade

CodeMessageRelated Endpoints
32000An upgrade request is already under review for this account.
I

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

  1. 1Provide a list of public IP addresses or domains that will be used to access the API.
  2. 2Send this information to the support team before attempting API integration.
  3. 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. 1
    Request API keys

    Contact support to receive your dedicated sandbox and production keys.

  2. 2
    Submit IPs/domains

    Provide the list of public IPs or domains for whitelisting.

  3. 3
    Test in sandbox

    Run all your integration tests in the sandbox environment.

  4. 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 - ChariBaaS | ChariBaaS