Initialiser un paiement

POST/v1/payments/initialize

Cree une nouvelle transaction de paiement. Si un operator est specifie, le paiement est traite immediatement. Sinon, une URL de checkout est retournee.

En-tetes

En-tete	Requis	Description
Authorization	Oui	Bearer zyn_test_... ou Bearer zyn_live_...
Content-Type	Oui	application/json
X-Idempotency-Key	Non	UUID v4 pour eviter les doublons

Parametres

Parametre	Type	Requis	Description
amount	number	Requis	Montant du paiement (minimum : 1, maximum : 10 000 000)
currency	string	Requis	Code devise ISO 4217 (ex: XOF, XAF, GHS)
description	string	Requis	Description du paiement (max 255 caracteres)
return_url	string	Requis	URL de redirection apres paiement (max 500 caracteres)
customer	object	Requis	Informations du client
customer.email	string	Requis	Adresse email du client (max 255)
customer.first_name	string	Requis	Prenom du client (max 100)
customer.last_name	string	Requis	Nom de famille du client (max 100)
customer.phone	string	Optionnel	Numero de telephone au format international (regex ^\+?[0-9]{8,15}$)
customer.country	string	Optionnel	Code pays ISO 3166-1 alpha-2
metadata	object	Optionnel	Donnees personnalisees (paires cle-valeur)
methods	array	Optionnel	Filtrer les methodes de paiement acceptees
operator	string	Optionnel	Code operateur (ex: mtn_bj). Si specifie, le paiement est traite immediatement.

Exemples

cURL

curl -X POST https://backend.zayono.com/api/v1/payments/initialize \
  -H "Authorization: Bearer zyn_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "description": "Abonnement Premium - Mars 2025",
    "return_url": "https://votre-site.com/paiement/retour",
    "customer": {
      "email": "jean.dupont@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "phone": "+22990123456"
    },
    "operator": "mtn_bj",
    "metadata": {
      "order_id": "ORD-2025-001",
      "plan": "premium"
    }
  }'

JavaScript

const response = await fetch('https://backend.zayono.com/api/v1/payments/initialize', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer zyn_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
  },
  body: JSON.stringify({
    amount: 5000,
    currency: 'XOF',
    description: 'Abonnement Premium - Mars 2025',
    return_url: 'https://votre-site.com/paiement/retour',
    customer: {
      email: 'jean.dupont@example.com',
      first_name: 'Jean',
      last_name: 'Dupont',
      phone: '+22990123456',
    },
    operator: 'mtn_bj',
    metadata: {
      order_id: 'ORD-2025-001',
      plan: 'premium',
    },
  }),
})

const data = await response.json()

PHP

$response = Http::withToken('zyn_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
    ->withHeaders(['X-Idempotency-Key' => '550e8400-e29b-41d4-a716-446655440000'])
    ->post('https://backend.zayono.com/api/v1/payments/initialize', [
        'amount' => 5000,
        'currency' => 'XOF',
        'description' => 'Abonnement Premium - Mars 2025',
        'return_url' => 'https://votre-site.com/paiement/retour',
        'customer' => [
            'email' => 'jean.dupont@example.com',
            'first_name' => 'Jean',
            'last_name' => 'Dupont',
            'phone' => '+22990123456',
        ],
        'operator' => 'mtn_bj',
        'metadata' => [
            'order_id' => 'ORD-2025-001',
            'plan' => 'premium',
        ],
    ]);

Reponses

201 — Paiement initialise

{
  "message": "Payment initialized successfully.",
  "data": {
    "id": "9e5f6a7b-8c9d-4e3f-a1b2-c3d4e5f6a7b8",
    "status": "initiated",
    "amount": 5000,
    "currency": "XOF",
    "checkout_url": null,
    "return_url": "https://votre-site.com/paiement/retour",
    "created_at": "2026-05-15T10:30:00+00:00"
  },
  "errors": null
}

Frais répercutés au client

Si la méthode choisie a un fee_percent configuré sur votre compte, le montant facturé au client est automatiquement augmenté. Vous pouvez consulter le détail (amount, amount_charged, fee_percent) en appelant GET /v1/payments/{id} après l'initialisation ou en écoutant le webhook payment.successful qui inclut ces champs.

A propos de checkout_url

Pour les paiements Mobile Money, checkout_url est toujours null — le flux se deroule par OTP sur le telephone du client, sans redirection web. Pour les paiements par carte ou certains operateurs qui exigent une page intermediaire (rare), checkout_url contient l'URL vers laquelle rediriger le client.

Si vous voulez systematiquement une page de paiement hebergee (avec selection de l'operateur cote client), utilisez plutot l'endpoint dedie POST /v1/checkout/initialize — sa reponse expose un checkout_url toujours peuple.

202 — Accepte mais traitement echoue

Le paiement a ete cree mais l'agregateur n'a pas pu le traiter. Un retry via fallback ou webhook sera tente.

{
  "message": "Payment initialized but processing failed. Will retry via fallback or webhook.",
  "data": {
    "transaction": {
      "id": "9e5f6a7b-8c9d-4e3f-a1b2-c3d4e5f6a7b8",
      "status": "initiated",
      "amount": 5000,
      "currency": "XOF",
      "checkout_url": null,
      "return_url": "https://votre-site.com/paiement/retour",
      "created_at": "2025-05-15T10:30:00+00:00"
    },
    "aggregator_error": "Timeout connecting to aggregator API"
  },
  "errors": null
}

422 — Erreur de validation

{
  "message": "Validation failed.",
  "data": null,
  "errors": {
    "amount": ["The amount field is required."],
    "customer.email": ["The customer.email field is required."]
  }
}

401 — Non authentifie

{
  "message": "Invalid or missing API key.",
  "data": null,
  "errors": null
}