Créer un payout

Un seul appel POST /v1/payouts crée et soumet un payout. Fournissez l’en-tête X-Idempotency-Key pour que les nouvelles tentatives réseau ne créent pas de virements en double.

Requête

curl https://api.orqex.com/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: PO-2026-0001" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "method": "momo_mtn",
    "description": "Salary payout",
    "reference": "PO-2026-0001",
    "customer": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "instrument": {
      "type": "phone",
      "phone_number": "+22990000000",
      "country": "BJ"
    },
    "metadata": { "department": "engineering" }
  }'

Corps de la requête

amount

integer

requis

Montant à envoyer, en unités majeures (ex. 50 pour 50,00 de la devise). Minimum 1.

currency

string

requis

Code devise ISO 4217 à trois lettres, majuscule (ex. XOF).

method

string

requis

Code de méthode de payout. Voir Méthodes & instruments.

description

string

requis

Courte description de l’objet du payout (ex. "Salary payout").

customer

object

requis

Identité du destinataire. Orqex résout cela en un client de projet ; le nom du client est utilisé comme nom du bénéficiaire sur le virement.

Afficher customer

string

requis

Adresse e-mail du destinataire.

first_name

string

requis

Prénom du destinataire.

last_name

string

requis

Nom du destinataire.

address

string

Adresse postale (optionnel).

city

string

Ville (optionnel).

state

string

État ou région (optionnel).

country

string

Code pays ISO 3166-1 alpha-2 (optionnel).

zip

string

Code postal (optionnel).

instrument

object

requis

Destination typée. Les sous-champs requis dépendent de instrument.type. Voir Types d’instrument ci-dessous.

reference

string

Votre propre identifiant unique pour ce payout, limité à votre projet. Réutiliser une référence existante renvoie 409 Conflict.

metadata

object

Jusqu’à 10 paires clé/valeur arbitraires, conservées sur le payout et renvoyées telles quelles.

Types d’instrument

phone
bank_account
crypto_address

Virement mobile-money ou wallet vers un numéro de téléphone.

{
  "type": "phone",
  "phone_number": "+22990000000",
  "country": "BJ"
}

Champ	Requis	Description
`phone_number`	Oui	Numéro de téléphone au format E.164.
`country`	Oui	Code pays ISO 3166-1 alpha-2.

Virement bancaire vers un compte nommé.

{
  "type": "bank_account",
  "account_name": "Awa Diallo",
  "account_number": "CI93CI0080111301134291200589",
  "bank_code": "CI008",
  "country": "CI",
  "swift_bic": "BICICIAB"
}

Champ	Requis	Description
`account_name`	Oui	Nom du titulaire du compte.
`account_number`	Oui	Numéro de compte ou IBAN.
`bank_code`	Oui	Code bancaire local.
`country`	Oui	Code pays ISO 3166-1 alpha-2.
`swift_bic`	Non	Code BIC/SWIFT.

Virement crypto vers une adresse blockchain.

{
  "type": "crypto_address",
  "address": "TQ5xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "network": "TRON",
  "memo_tag": "12345"
}

Champ	Requis	Description
`address`	Oui	Adresse du wallet on-chain.
`network`	Oui	Réseau blockchain (ex. `TRON`, `ETH`, `BTC`).
`memo_tag`	Non	Mémo ou tag de destination (requis par certains réseaux).

Réponse

{
  "id": "po_...",
  "amount": { "value": 5000, "formatted": "5,000 XOF", "short": "5K", "currency": "XOF" },
  "method": "momo_mtn",
  "status": "processing",
  "reference": "PO-2026-0001",
  "description": "Salary payout",
  "customer": {
    "id": "cus_...",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "avatar_url": null
  },
  "instrument": {
    "id": "poi_...",
    "type": "phone",
    "phone_number": "+22990000000",
    "country": "BJ"
  },
  "gateway": {
    "transaction": {
      "id": "gw_tx_123",
      "reference": "po_ref_generated",
      "external_id": null
    }
  },
  "fee_amount": 0,
  "failure": { "code": null, "message": null },
  "metadata": {},
  "initiated_at": "2026-06-14T10:00:00+00:00",
  "completed_at": null,
  "failed_at": null,
  "created_at": "2026-06-14T10:00:00+00:00"
}

string

Identifiant public du payout, préfixé po_.

amount

object

Afficher amount

value

number

Montant en unités majeures (décimal).

formatted

string

Chaîne d’affichage localisée (ex. 5,000 XOF).

short

string

Chaîne d’affichage abrégée (ex. 5K).

currency

string

Code devise ISO 4217.

method

string

Code de méthode de payout utilisé.

status

string

pending, processing, completed ou failed. Voir Cycle de vie.

reference

string

Votre référence, si fournie.

description

string

Description du payout.

customer

object

Client de projet résolu (simplifié : id, first_name, last_name, email, avatar_url).

instrument

object

Objet instrument complet renvoyé tel que fourni.

gateway

object

Afficher gateway

transaction

object

Afficher transaction

string

Identifiant interne de la transaction passerelle.

reference

string

Référence utilisée auprès de la passerelle.

external_id

string|null

Identifiant de transaction propre à la passerelle, une fois disponible.

fee_amount

number

Frais du payout en unités majeures (décimal).

failure

object

Renseigné lorsque status vaut failed. Voir Cycle de vie.

metadata

object

Vos métadonnées telles que fournies.

initiated_at

string|null

Horodatage ISO 8601 de la soumission du payout à la passerelle.

completed_at

string|null

Horodatage ISO 8601 de la complétion du payout, ou null.

failed_at

string|null

Horodatage ISO 8601 de l’échec du payout, ou null.

created_at

string

Horodatage ISO 8601 de la création.

Ne traitez pas le status initial de cette réponse comme définitif. Le statut du payout est résolu de façon asynchrone. Écoutez les événements webhook ou pollez l’endpoint de récupération pour connaître le résultat autoritaire.

​Requête

​Corps de la requête

​Types d’instrument

​Réponse

Requête

Corps de la requête

Types d’instrument

Réponse