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.8 · Last updated 5 novembre 2025

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/25 (or any future date)

3DS Code

555

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 register-with-docs, merchant-kyc-upload, add-tokenized-card endpoints. Enriched reference tables (docTypes, customerStatuses, accountLevels). Detailed error codes with endpoint mapping. autoActivate parameter on confirm. Fixed confirm route.

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)

POST{host}/api/customers/register200

Register with Documents

Register a merchant with KYC documents in a single step (multipart/form-data). Same route as basic register, but with file attachments.

Parameter	Type	In	Required	Description
`phoneNumber`	string	body	Required	Phone number. Format: +212*********
`firstName`	string	body	Required	First name (min. 2 latin chars).
`lastName`	string	body	Required	Last name (min. 2 latin chars).
`cin`	string	body	Required	National ID number (min. 5 chars).
`rcNumber`	string	body	Required	Commercial register number.
`walletType`	string	body	Required	"C" (Merchant).
`kycDocuments[n].docType`	int	body	Required	Document type ID (see "Document Types" table).
`kycDocuments[n].docFront`	file	body	Required	Front image of the document.
`kycDocuments[n].docBack`	file	body	Optional	Back image of the document (if applicable).

Notes

•Content-Type must be multipart/form-data (not application/json).
•Accepted files are images (JPEG, PNG) and PDF.
•See the "Document Types" table for valid docType values.

POST{host}/api/customers/register/confirm

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
`autoActivate`	boolean	body	Optional	If true, directly activates the customer without requiring the Set PIN step. Useful if you don't plan to use ChariMoney's PIN system.

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/customers/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[n].docType`	int	body	Required	Document type ID (see "Document Types" table).
`kycDocuments[n].docFront`	file	body	Required	Front image of the document.
`kycDocuments[n].docBack`	file	body	Optional	Back image (if applicable).

Operations

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

CashIn Card

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	Numéro de téléphone du client. Format : +212*********
`Amount`	decimal	body	Required	Montant à 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.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro de téléphone du client.
`FirstName`	string	body	Required	Prénom du titulaire de la carte.
`LastName`	string	body	Required	Nom du titulaire de la carte.
`Cvv`	string	body	Required	Code de sécurité à 3 chiffres (CVV).
`Amount`	decimal	body	Required	Montant à déposer.
`Currency`	string	body	Optional	Code devise ISO 3 lettres (ex : MAD).
`Pan`	string	body	Required	Numéro complet de la carte (PAN).
`ExpiryDate`	string	body	Required	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	Required	true : sauvegarder la carte pour usage futur / false : usage unique.
`CardName`	string	body	Optional	Nom 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.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro de téléphone du client.
`CardId`	int	route	Required	Identifiant de la carte sauvegardée.
`Cvv`	string	body	Required	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	Required	Montant à déposer.

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	Code de l'agent.
`Amount`	decimal	body	Required	Montant à déposer.

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	Code de l'agent.
`FirstName`	string	body	Required	Prénom du titulaire de la carte.
`LastName`	string	body	Required	Nom du titulaire de la carte.
`Cvv`	string	body	Required	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	Required	Montant à déposer.
`Pan`	string	body	Required	Numéro complet de la carte.
`ExpiryDate`	string	body	Required	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	Required	Sauvegarder la carte pour usage futur.
`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.

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	Numéro de l'émetteur. Format : +212*********
`Amount`	decimal	body	Required	Montant à transférer.
`Reason`	string	body	Required	Motif du transfert.
`RecipientPhoneNumber`	string	body	Required	Numéro du bénéficiaire. Format : +212*********
`BeneficiaryId`	int	body	Optional	Référence à un bénéficiaire existant (optionnel).

POST{host}/api/operations/transfer

Execute

Move funds between customers' wallets internally.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Numéro de l'émetteur.
`Amount`	decimal	body	Required	Montant à transférer.
`Reason`	string	body	Required	Motif du transfert.
`RecipientPhoneNumber`	string	body	Required	Numéro du bénéficiaire.
`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	Required	Requis si AgentCode est vide.
`AgentCode`	string	body	Optional	Requis si CustomerPhoneNumber est vide. Code Agent (Principal ou Retail).
`Amount`	decimal	body	Required	Montant à virer.
`Reason`	string	body	Required	Motif du virement (caractères latins uniquement).
`BeneficiaryId`	int	body	Optional	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	Optional	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	Optional	RIB : chaîne numérique de 24 chiffres. Optionnel si beneficiaryId est fourni.

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.

Parameter	Type	In	Required	Description
`CustomerPhoneNumber`	string	body	Required	Requis si agentCode est vide.
`AgentCode`	string	body	Optional	Requis si CustomerPhoneNumber est vide.
`Amount`	decimal	body	Required	Montant à virer.
`Reason`	string	body	Optional	Motif du virement.
`BeneficiaryId`	int	body	Optional	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	Optional	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	Optional	RIB : 24 chiffres. Requis si pas de 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	Numéro du client payeur.
`Amount`	decimal	body	Required	Montant du paiement.
`Reason`	string	body	Required	Motif du paiement.
`RecipientPhoneNumber`	string	body	Required	Numéro du marchand.
`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	Numéro du client payeur.
`Amount`	decimal	body	Required	Montant du paiement.
`Reason`	string	body	Required	Motif du paiement.
`RecipientPhoneNumber`	string	body	Required	Numéro du marchand.
`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	Numéro du client payeur.
`QrCodeContent`	string	body	Required	Contenu du QR Code scanné.
`Amount`	decimal	body	Required	Montant du paiement.

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	Numéro du client payeur.
`QrCodeContent`	string	body	Required	Contenu du QR Code.
`Amount`	decimal	body	Required	Montant du paiement.

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	Numéro du marchand.
`Amount`	decimal	body	Required	Montant du paiement.

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

By Card — Execute

Pay Merchant by card (Card to Wallet).

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro du marchand.
`Amount`	decimal	body	Required	Montant du paiement.

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

Static QR Generation

Generate a static QR Code with a specific amount.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro du marchand.
`MaskedNumber`	bool	query	Optional	Masquer le numéro du marchand dans le contenu QR. Ex : +2126######74
`Amount`	decimal	body	Required	Montant fixe du QR Code.

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

Dynamic QR Generation

Generate a dynamic QR Code.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro du marchand.
`MaskedNumber`	bool	query	Optional	Masquer le numéro du marchand.

Notes

•QR statique : le montant est fixe et intégré dans le QR.
•QR dynamique : le client saisit le montant lors du paiement.
•qrCodeReference : référence unique attribuée aux QR dynamiques.

ChargeBack

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

Preview

Check the feasibility of performing a chargeback.

Parameter	Type	In	Required	Description
`SourcePhoneNumber`	string	body	Required	Numéro du client à l'origine. Format : +212*********
`Amount`	decimal	body	Required	Montant du chargeback.
`Description`	string	body	Required	Motif du chargeback.
`DestinationPhoneNumber`	string	body	Required	Numéro du destinataire. Format : +212*********
`OriginalOperationId`	int	body	Required	ID de l'opération d'origine qui a déclenché le chargeback.

POST{host}/api/operations/chargeback

Execute

Execute a chargeback operation.

Parameter	Type	In	Required	Description
`SourcePhoneNumber`	string	body	Required	Numéro du client à l'origine.
`Amount`	decimal	body	Required	Montant du chargeback.
`Description`	string	body	Required	Motif du chargeback.
`DestinationPhoneNumber`	string	body	Required	Numéro du destinataire.
`OriginalOperationId`	int	body	Required	ID 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.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	Numéro de téléphone du client.
`Amount`	decimal	body	Required	Montant du CashIn.

Notes

•operationType : 1 = CashIn, 2 = CashOut
•operationStatus : 1 = open (en attente), 2 = completed (exécutée), 3 = failed (échouée)

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	Numéro de téléphone du client.
`Amount`	decimal	body	Required	Montant du CashOut.

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	Numéro de téléphone du client.
`PageSize`	int	query	Optional	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optional	Numéro de page. Par défaut : 1
`OperationType`	list int	query	Optional	1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=PAYMENT_PUSH, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 12=CHARGEBACK, 24=PAYMENT_CARD
`TransactionStatus`	int	query	Optional	1=PENDING, 2=COMPLETED, 3=FAILED, 4=CANCELLED
`Sens`	int	query	Optional	1=CREDIT, 2=DEBIT
`From`	datetime	query	Optional	Date/heure de début du filtre.
`To`	datetime	query	Optional	Date/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.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro de téléphone du client.
`Id`	int	route	Required	ID 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.

Parameter	Type	In	Required	Description
`PageSize`	int	query	Optional	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optional	Numéro de page. Par défaut : 1
`OperationType`	list int	query	Optional	Filtrer par type d'opération.
`TransactionStatus`	int	query	Optional	Filtrer par statut.
`Sens`	int	query	Optional	1=CREDIT, 2=DEBIT
`From`	datetime	query	Optional	Date/heure de début.
`To`	datetime	query	Optional	Date/heure de fin.

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	Numéro du client à rembourser.
`OperationId`	int	body	Required	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	Required	Montant du remboursement.
`OrderId`	string	body	Required	OrderId original du paymentGateway.
`TransactionTrackId`	string	body	Required	TransactionTrackId original du paymentGateway.

POST{host}/api/operations/refund

Execute

Refund customers after merchant payment.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	Numéro du client.
`OperationId`	int	body	Required	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	Required	Montant du remboursement.
`OrderId`	string	body	Required	OrderId original.
`TransactionTrackId`	string	body	Required	TransactionTrackId original.

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	Numéro de téléphone du client.
`PageSize`	int	query	Optional	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optional	Numéro de page. Par défaut : 1
`Search`	string	query	Optional	Filtrer par mot-clé.
`From`	datetime	query	Optional	Date de création — début.
`To`	datetime	query	Optional	Date de création — fin.

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	Numéro de téléphone du client (propriétaire).
`Name`	string	body	Required	Nom du bénéficiaire. Minimum 2 lettres.
`PhoneNumber`	string	body	Optional	Numéro du bénéficiaire. Format : +212*********
`Rib`	string	body	Optional	RIB du bénéficiaire. 24 chiffres.
`Email`	string	body	Optional	Email 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.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro de téléphone du client (propriétaire).
`Id`	int	route	Required	ID du bénéficiaire à modifier.
`Name`	string	body	Required	Nom. Minimum 2 lettres.
`PhoneNumber`	string	body	Optional	Numéro du bénéficiaire.
`Rib`	string	body	Optional	RIB. 24 chiffres.
`Email`	string	body	Optional	Email du bénéficiaire.

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

Delete Beneficiary

Delete an existing beneficiary.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Numéro de téléphone du client.
`Id`	int	route	Required	ID du bénéficiaire à supprimer.

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	Numéro de téléphone du client.
`PageSize`	int	query	Optional	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optional	Numé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.).

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	Numéro de téléphone du client.
`Id`	int	route	Required	ID de la carte.

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

Add Tokenized Card

Save (tokenize) a new bank card for a customer.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	query	Required	Customer phone number.
`FirstName`	string	body	Required	Cardholder first name.
`LastName`	string	body	Required	Cardholder last name.
`Pan`	string	body	Required	Full card number (PAN).
`ExpiryDate`	string	body	Required	Expiry date in YYMM format (e.g. 3005).
`Cvv`	string	body	Required	Card verification code (CVV/CVC).
`CardName`	string	body	Optional	Custom card name (alias).

Notes

•The PAN (card number) will be securely stored and tokenized.
•Use the sandbox test card for testing (see the Test Card section).

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	Code de l'agent.
`PageSize`	int	query	Optional	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optional	Numéro de page. Par défaut : 1
`From`	datetime	query	Optional	Création de l'agent — date début.
`To`	datetime	query	Optional	Création de l'agent — date fin.

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	Code de l'agent.

POST{host}/api/agents/retail

Add Retail Agent

Add a new retail agent.

Parameter	Type	In	Required	Description
`PhoneNumber`	string	body	Required	Numéro de téléphone de l'agent. Format : +212*********
`Name`	string	body	Required	Nom commercial de l'agent.
`FirstName`	string	body	Required	Prénom. Minimum 2 lettres.
`LastName`	string	body	Required	Nom de famille. Minimum 2 lettres.
`Cin`	string	body	Required	Numéro de pièce d'identité.
`Address`	string	body	Optional	Adresse de l'agent.
`Email`	string	body	Optional	Email 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.

Parameter	Type	In	Required	Description
`Reference`	string	query	Required	Référence unique de l'opération.

Notes

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

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

Execute CashIn by Reference

Execute a CashIn operation by the agent.

Parameter	Type	In	Required	Description
`Code`	string	body	Required	Code de l'agent.
`Reference`	string	body	Required	Référence de l'opération.

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	Référence unique de l'opération.

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

Execute CashOut by Reference

Execute a CashOut operation by the agent.

Parameter	Type	In	Required	Description
`Code`	string	body	Required	Code de l'agent.
`Reference`	string	body	Required	Référence de l'opération.

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	Code de l'agent principal.

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

Headers

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

Réponse attendue : 200 OK sous 5 secondes (corps vide). Tout code non-2xx déclenche un retry.

Event Body Properties

Property	Type	Required	Description
`WebhookId`	string	Required	Identifiant du webhook.
`EventId`	string	Required	Type d'événement. Ex : bank-transfer.initiated
`CRequestId`	string	Required	Identifiant de traçage reçu du partenaire.
`OperationId`	int	Required	ID de l'opération exécutée (peut être 0 si aucune opération créée).
`TransactionId`	int	Optional	ID de la transaction principale.
`OperationType`	int	Required	Code du type d'opération (voir Types).
`OperationStatus`	int	Required	1 = Open, 2 = Completed, 3 = Failed
`CreatedAt`	date	Required	Date de début du processus.
`Amount`	decimal	Required	Montant de l'opération.
`FeeAmount`	decimal	Required	Montant des frais.
`PrimaryAccountNumber`	string	Required	Numéro de téléphone de l'émetteur.
`SecondaryAccountNumber`	string	Optional	Numéro de téléphone du destinataire.
`Method`	string	Optional	Méthode : Card / Agent / Network
`CustomData`	string	Optional	Données personnalisées du partenaire (max 128 caractères).
`GatewayTrackId`	string	Optional	Gateway Transaction Track Id.
`GatewayOrderId`	string	Optional	Gateway Transaction Order Id.
`GatewayReferenceId`	string	Optional	Gateway Transaction Reference Id.
`BankTransferBeneficiaryName`	string	Optional	Nom du bénéficiaire pour les virements bancaires.
`NetworkName`	string	Optional	Nom du réseau pour les opérations réseau.
`Reference`	string	Optional	Ré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 ID	Description
`customer.kyc`	KYC process started
`customer.level.updated`	Customer account level updated
`operation.created`	Operation is created (pending)
`operation.updated`	Operation status changes
`cashin.card.authorized`	CashIn by Card accepted
`payment.card.authorized`	Payment by Card accepted
`bank-transfer.initiated`	Bank transfer sent
`bank-transfer.completed`	Bank transfer settled
`bank-transfer.failed`	Bank transfer rejected/returned
`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

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"
  }
}

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.

Types & References

Operation Types

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
4	DEPOSIT
5	PAYMENT_PUSH
6	PAYMENT_PULL
7	PAYMENT_REFUND
8	ALIMENTATION_AGENT
9	BANK_TRANSFER
10	MOBILE_TOP_UP
12	CHARGEBACK
24	PAYMENT_CARD

Transaction Types

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
5	PAYMENT_PUSH
6	TRANSACTION_FEES
7	PAYMENT_REFUND
9	CHARGEBACK
10	CHARGEBACK_CANCELLATION
16	BANK_TRANSFER
18	CASHBACK

Transaction Statuses

ID	Code	Description
1	PENDING	Pending
2	COMPLETED	Completed
3	FAILED	Failed
4	CANCELLED	Cancelled

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	BASIC	Basic level — registration without KYC
2	KYC_LEVEL_2	Level 2 — ShareID verification (document + selfie)
3	KYC_LEVEL_3	Level 3 — advanced verification
4	KYC_LEVEL_4	Level 4 — full verification

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.

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.

API Documentation

Getting Started

Authentication Headers

Test Credit Card (Sandbox)

Postman Collection

Changelog

Customer Registration

Customer Registration Flow

Check Status with Chari

Check Status with Switch

Register

Register with Documents

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)

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

Static QR Generation

Dynamic QR Generation

ChargeBack

Chargeback Flow

Preview

Execute

Request Operations

CashIn/CashOut by Reference Flow

Request CashIn

Request CashOut

Get Operations

By Customer

By ID

All (by Partner)

Get Operation By C-Request-Id

Refund

Preview

Execute

Beneficiary

Beneficiary Management Flow

Get Beneficiaries

Add Beneficiary

Update Beneficiary

Delete Beneficiary

Tokenized Cards

Tokenized Cards Flow

Get Cards by Customer

Get Card by ID

Add Tokenized Card