Passer au contenu principal
Utilisez cette approche quand vous avez besoin d’un contrôle total sur l’interface de paiement. Orqex résout les pays et méthodes disponibles pour votre projet, route la tentative vers la passerelle optimale et vous indique quelle action présenter au client. Quand utiliser ceci plutôt que le checkout hébergé
Checkout hébergéCheckout custom
Effort d’intégrationMinimal (redirection)Plus élevé (construire l’UI)
Contrôle de l’UIAucunTotal
Sélection pays / méthodeUI OrqexVotre propre UI
Recommandé pourIntégrations rapidesFlux avec votre marque ou intégrés

​
Étape 1 - Créer un intent de paiement

curl https://api.orqex.com/v1/payment/intents \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "description": "Commande #1024",
    "return_url": "https://shop.example.com/return",
    "webhook_url": "https://shop.example.com/webhooks/orqex",
    "customer": {
      "email": "[email protected]",
      "first_name": "Ama",
      "last_name": "Mensah"
    }
  }'
Conservez l’id retourné (ex. pi_a1b2c3d4e5f6). Chaque étape suivante est liée à cet intent.

​
Étape 2 - Lister les pays disponibles

Récupérez les pays que votre projet peut accepter pour cet intent. Les résultats sont classés par préférence du payeur en fonction de sa localisation, de ses paiements passés et des signaux de popularité. 
curl https://api.orqex.com/v1/payment/intents/pi_a1b2c3d4e5f6/countries \
  -H "Authorization: Bearer sk_live_xxx"
Réponse
{
  "data": [
    { "code": "CI", "name": "Cote d'Ivoire", "flag": "https://cdn.orqex.com/flags/CI.svg" },
    { "code": "SN", "name": "Senegal",        "flag": "https://cdn.orqex.com/flags/SN.svg" }
  ],
  "meta": { "total": 2, "supports_any_country": false }
}
Affichez cette liste et laissez le client sélectionner son pays. Utilisez la valeur code retournée à l’étape suivante.
supports_any_country: true signifie qu’au moins une règle de routage accepte n’importe quel pays. Vous pouvez quand même afficher la liste classée.

​
Étape 3 - Lister les méthodes de paiement pour le pays choisi

Récupérez les méthodes disponibles pour le pays sélectionné. Passez currency pour restreindre à une devise spécifique (utile si le projet supporte le DCC). 
curl "https://api.orqex.com/v1/payment/intents/pi_a1b2c3d4e5f6/countries/CI/methods?currency=XOF" \
  -H "Authorization: Bearer sk_live_xxx"
Réponse
{
  "data": [
    {
      "value": "momo_mtn",
      "label": "MTN Mobile Money",
      "description": "Payer avec MTN MoMo",
      "icon_url": "https://cdn.orqex.com/methods/momo_mtn.svg",
      "category": "mobile_money"
    },
    {
      "value": "wallet_wave",
      "label": "Wave",
      "description": "Payer avec Wave",
      "icon_url": "https://cdn.orqex.com/methods/wave.svg",
      "category": "wallet"
    }
  ]
}
Les résultats sont classés par préférence. Affichez la liste et laissez le client choisir.

​
Étape 4 - Créer une tentative de paiement

Soumettez la méthode, le pays et le numéro de téléphone choisis par le client. Orqex route vers la passerelle optimale et exécute la capture. 
curl https://api.orqex.com/v1/payment/intents/pi_a1b2c3d4e5f6/attempts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: idem_attempt_001" \
  -d '{
    "method_code": "momo_mtn",
    "country": "CI",
    "phone": { "number": "0700000000", "country": "CI" }
  }'

​
Corps de la requête

​
method_code
string
requis
Code de méthode de paiement issu de l’étape précédente (ex. momo_mtn).
​
country
string
requis
Code pays ISO 3166-1 alpha-2 sélectionné par le client.
​
phone
object
requis
Numéro de téléphone du payeur.
​
currency
string
Devise de remplacement (ISO 4217). Par défaut : devise de l’intent.

​
Réponse

La réponse est l’intent mis à jour avec la nouvelle active_attempt. Vérifiez active_attempt.next_action.type pour savoir quoi faire ensuite :
next_action.typeAction à effectuer
noneLe paiement est en cours. Attendez le webhook ou relancez une requête.
approve_on_phoneAffichez le code USSD pour que le client approuve sur son téléphone.
collect_otpDemandez l’OTP au client, puis passez à l’étape 5.
redirect_to_urlRedirigez le client vers next_action.url.
display_payment_instructionsAffichez next_action.instructions au client.

​
Étape 5 - Autoriser (OTP / 2FA), si nécessaire

Si active_attempt.next_action.type est collect_otp, soumettez l’OTP reçu par le client. Aucun id de tentative n’est nécessaire. 
curl https://api.orqex.com/v1/payment/intents/pi_a1b2c3d4e5f6/authorize \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: idem_auth_001" \
  -d '{
    "otp": "123456"
  }'
Retourne l’intent mis à jour. Si l’OTP est accepté, active_attempt.status passe à completed ou repasse à processing.

​
Étape 6 - Récupérer l’état final

Attendez l’événement webhook ou interrogez l’intent pour confirmer le résultat. 
curl https://api.orqex.com/v1/payment/intents/pi_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_live_xxx"
Un status à completed signifie que le paiement a réussi. Consultez le cycle de vie du paiement pour tous les états possibles.
Préférez les webhooks au polling. Définissez webhook_url sur l’intent et réagissez aux événements payment.completed ou payment.failed.