Commandes API et ressources

La plupart des commandes appliquent les cinq mêmes verbes à onze ressources. Apprenez cette grammaire une fois pour piloter toute l'API sans ouvrir la référence.

wajub <resource> list
wajub <resource> retrieve <id>
wajub <resource> create -d field=value
wajub <resource> update <id> -d field=value
wajub <resource> delete <id>

payments, customers, refunds, transfers, beneficiaries, links, invoices, events, disputes, accounts et webhooks suivent cette structure, sans les verbes qui n'ont aucun sens pour eux. refunds update n'existe pas, car un remboursement ne peut pas être modifié. shield, identity et skills possèdent leur propre structure, présentée à la fin de cette page.

links et invoices ne fonctionnent qu'avec une clé live. Avec une clé sandbox, la CLI s'arrête avant d'envoyer quoi que ce soit et sort avec le code 1 : invoices is available in live mode only — use a live key (sk.).

Envoyer un corps de requête

Deux méthodes sont disponibles. Utilisez -d dans le cas courant et --data-raw pour un corps que vous avez déjà ou des types que vous voulez fixer vous-même. Elles se combinent : --data-raw est lu d'abord, puis chaque -d s'applique par-dessus, si bien qu'un champ -d l'emporte sur le même champ du JSON.

# Repeatable key=value. Dots build nested objects.
wajub payments create \
  -d amount=25000 \
  -d currency=XAF \
  -d channel=cm.mtn \
  -d [email protected] \
  -d customer.phone=+237670000000

# An array, written as inline JSON
wajub webhooks create   -d url=https://example.com/webhooks/wajub   -d 'events=["payment.succeeded","payment.failed"]'

# Or a body you already have
wajub webhooks create --data-raw '{
  "url": "https://example.com/webhooks/wajub",
  "events": ["payment.succeeded", "payment.failed"]
}'

Un champ nommé phone, se terminant par _phone (customer.phone, payout_phone), account_number ou reference part toujours en texte, tel que saisi, à n'importe quelle profondeur. -d lit toute autre valeur ainsi :

• true, false et null comme ces valeurs JSON ;
• une valeur qui commence par [ et finit par ], ou par { et }, comme du JSON en ligne, quand elle s'analyse ;
• un nombre quand elle n'a pas de zéro initial et au plus 15 chiffres : amount=25000 donne le nombre 25000, tandis que iban=00123 et un numéro de commande de 19 chiffres restent du texte ;
• tout le reste comme du texte.

Répertorier des ressources

Toutes les commandes list proposent les neuf mêmes options, mais quatre d'entre elles sont envoyées sous un nom que l'API ne lit pas.

Passez par -f pour ce que l'API lit réellement : per_page, de 1 à 100, et pour les paiements, les remboursements et les litiges, date_from et date_to.

wajub payments list -f per_page=5
wajub payments list --status failed -f date_from=2026-01-01
wajub payments list -q [email protected]
wajub transfers list --all --limit 500 --json > transfers.json

date_from et date_to représentent des journées entières. L'API filtre selon la date civile. Vous ne pouvez pas demander uniquement les deux dernières heures. Pour une période plus courte, répertoriez la journée et filtrez vous-même le JSON.

Requêtes brutes

Lorsqu'une route ne possède aucune commande dédiée, ou si vous voulez voir la réponse exacte de l'API, trois commandes acceptent n'importe quel chemin.

wajub get /balance
wajub get "/payments?per_page=5&status=succeeded"
wajub get /tax/settings

wajub post /customers -d [email protected] -d name="Amina Nkem"
wajub post /transfers --data-raw '{"amount":100000,"currency":"XAF","beneficiary":"ben_…"}'

wajub delete /payments/trx_CSUGajfv9xh0XQ5wu2lx

Le chemin est relatif à la base de l'API et la clé provient de votre profil. Vous n'avez donc aucun en-tête à retenir et aucune clé dans votre historique. Placez entre guillemets tout chemin contenant &, sinon votre shell l'interprétera.

Deux options qui changent le sens de la requête

--idempotency-key définit l'en-tête Idempotency-Key. Elle existe sur payments create, payments process, transfers create, refunds create et wajub post, les appels que l'API rend idempotents. Sur les quatre premiers, la CLI en génère déjà une nouvelle à chaque appel : indiquez-la seulement pour que deux exécutions soient traitées comme une même tentative. Les autres commandes create n'en envoient aucune.

--sync définit l'en-tête X-Sync et exécute l'appel au nom d'un compte connecté. Elle est disponible sur chaque create et update, sur les commandes d'action comme payments process, et sur wajub post. list, retrieve et delete ne la prennent pas.

# Run this twice: the second call returns the first result, it does not charge twice
wajub payments create -d amount=25000 -d currency=XAF --idempotency-key order-4172

# Create the payment on a connected merchant's account
wajub payments create -d amount=25000 -d currency=XAF --sync acc_7Yh2MpL4tRb3nP8sZcXv

Sortie

La sortie destinée aux humains est un tableau. --json affiche l'enveloppe de réponse de l'API sans modification. Les listes se trouvent donc sous items et le solde sous balance. Utilisez cette sortie dans vos pipelines. Une liste fait exception : wajub events list --json range les événements sous events, comme GET /events, et le filtre est donc jq '.events[]'.

wajub payments list --status failed --json \
  | jq -r '.items[] | [.id, .amount, .failure_reason] | @tsv'

wajub balance --json | jq '.balance.available'

# Every failed payout of the month, as CSV
wajub transfers list --status failed --all --json \
  | jq -r '.items[] | [.id, .amount, .currency, .failure_reason] | @csv'

Commandes qui demandent une confirmation

Une commande qui déplace de l'argent demande une confirmation quand elle s'exécute avec une clé live ; avec une clé sandbox, elle s'exécute aussitôt. Une commande qui détruit ou remplace quelque chose demande toujours. --yes, -y ou son alias --force ignore cette demande. Utilisez cette option dans un script et nulle part ailleurs.

Commandes en lecture seule

Quatre commandes sans argument répondent à des questions que vous devriez autrement rechercher.

wajub balance      # your balance, per currency
wajub channels     # every channel slug Wajub supports
wajub countries    # supported countries
wajub currencies   # supported currencies

Utilisez wajub channels lorsqu'un paiement échoue à cause d'un canal inconnu. La commande présente tous les slugs pris en charge par Wajub, le même catalogue pour chaque compte. Ce que votre propre compte peut utiliser dépend de ses prestataires, et c'est wajub get /providers qui y répond.

Dans la sandbox, wajub balance renvoie un objet simplifié où available est égal à total et les autres valeurs sont nulles. Le détail complet existe uniquement en live.

Identity et Shield

Deux thèmes ne suivent pas la grammaire CRUD, car les produits sous-jacents ne la suivent pas.

# Which operator a number belongs to (sandbox key only)
wajub identity resolve -d account_number=+237670000000 -d channel=cm.mtn -d country=CM -d type=mobile
# Whether an IBAN is well formed
wajub identity validate -d iban=FR7630006000011234567890189

# Shield (live key only)
wajub shield stats
wajub shield settings
wajub shield update-settings --enabled --block-threshold 70 --review-threshold 40
wajub shield blocklist
wajub shield block +237670000000 --type phone --reason "chargeback ring"
# The id is the entry's, a UUID, as `wajub shield blocklist` shows it
wajub shield unblock 9b1f6c2e-4a7d-4f0b-8c3e-2d5a7b9e1f40

Les deux commandes identity demandent le plan Growth, Scale ou Enterprise. identity resolve ne répond qu'à partir des données de la sandbox : avec une clé live, elle renvoie 501. identity validate vérifie le format et la clé de contrôle d'un IBAN, pas l'identité de son titulaire.

Toutes les commandes shield demandent une clé live. Avec une clé sandbox, la CLI s'arrête avant d'envoyer quoi que ce soit, sort avec le code 1 et indique Shield is available in live mode only — use a live key (sk.). --type accepte email, phone, ip, country et card_bin. update-settings accepte --[no-]enabled, --review-threshold et --block-threshold sur tous les plans, ainsi que --[no-]auto-3ds et --[no-]blocklist, qui demandent Shield Advanced.