Charges

Une charge est une demande de paiement. Vous la créez, Switag renvoie une checkout_url, le client paie, vous êtes notifié.

Créer une charge#

POST/v1/biz/chargesClé API

Champ	Type	Détail
`amount`	entier	Requis. Plus petite unité (XOF sans décimale).
`currency`	string	Optionnel — défaut = devise du compte.
`reference`	string	Votre identifiant de commande.
`description`	string	Affichée au client.
`customer_tag`	string	Réserve le paiement à un `@tag` précis.
`redirect_url`	string	Retour après paiement (HTTPS).
`webhook_url`	string	Surcharge ponctuelle de votre webhook.
`environment`	string	Optionnel. `test` ou `live` selon la clé utilisée.

Terminal

curl -X POST https://api-switag.pluxce.com/v1/biz/charges \
  -H "X-Api-Key: pk_test_…" -H "X-Api-Secret: sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"reference":"ORDER-123","customer_tag":"@awa"}'

Réponse `201`#

JSON

{
  "id": "5f1c2e8a-…",
  "token": "AbC123dEf456",
  "amount": 5000,
  "currency": "XOF",
  "state": "pending",
  "reference": "ORDER-123",
  "checkout_url": "https://pay.pluxce.com/c/AbC123dEf456",
  "redirect_url": "",
  "customer_tag": "awa",
  "expires_at": "2026-06-01T18:15:00Z"
}

Champ	Type	Détail
`id`	uuid	Identifiant interne de la charge.
`token`	string	Handle public (présent dans `checkout_url` et le statut).
`state`	enum	Toujours `pending` à la création (voir Cycle de vie).
`checkout_url`	url	La seule URL à présenter au client.
`customer_tag`	string	Tag ciblé normalisé (sans `@`), vide si ouvert.
`expires_at`	date-time	Échéance — la charge expire après 30 min.

Suivre / réconcilier#

GET/v1/biz/checkout/{token}/status

GET/v1/biz/charges/{token}Session ou clé API

GET/v1/biz/chargesSession ou clé API

JSON

{ "state": "paid" }

state prend l'une des valeurs du cycle de vie ci-dessous. Public (le token fait office de capacité) — pratique si vous avez manqué le webhook.

Cycle de vie#

`state`	Signification
`pending`	En attente de paiement.
`paid`	Payée et encaissée.
`expired`	Échéance dépassée (final).
`cancelled`	Annulée avant paiement (final).
`refunded`	Payée puis remboursée (final).

Annuler / rembourser#

POST/v1/biz/charges/{token}/cancelClé API

POST/v1/biz/charges/{token}/refundClé API

Le remboursement total n'est possible que sur une charge payée et non encore reversée (les fonds sont encore dans votre solde).

Cibler un client#

Avec customer_tag, seul ce @tag peut payer ; la page de paiement pré-remplit et verrouille son identifiant. Un autre payeur reçoit 403 wrong_customer.

Comment le client peut payer#

Une même checkout_url ouvre plusieurs parcours:

app Switag avec QR rotatif et confirmation mobile
fallback web avec identifiant Switag, OTP puis PIN
redirection navigateur vers votre redirect_url une fois le paiement fait

Le webhook charge.succeeded reste la source de vérité métier. Le retour navigateur est un confort UX, pas une preuve de paiement.