POST/api/v1/payments/payoutsClé API · merchant.charges.manage

Créer un décaissement

Initie un payout vers un bénéficiaire enregistré.

Corps de requête

Nom	Type	Requis	Description
amount	string	Oui	Montant
currency	string	Oui	Devise
beneficiaryId	string	—	Bénéficiaire enregistré
idempotencyKey	string	Oui	Clé d'idempotence
description	string	—	Libellé

Exemple requête

json

{
  "amount": "500",
  "currency": "USD",
  "beneficiaryId": "ben_abc123",
  "idempotencyKey": "payout-week-32"
}

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours payout
id	string	Oui	Identifiant payout
amount	string	Oui	Montant
currency	string	Oui	Devise
status	string	Oui	PENDING, PROCESSING, SUCCEEDED, FAILED
method	string	—	BANK_TRANSFER, MOBILE_MONEY, etc.
destinationRef	string	—	Référence compte de destination
beneficiaryName	string \| null	—	Nom du bénéficiaire
providerCode	string \| null	—	Code provider d'exécution
executedAt	string \| null	—	Date d'exécution ISO 8601
idempotencyKey	string	Oui	Clé d'idempotence
createdAt	string	Oui	Date ISO 8601
updatedAt	string	Oui	Dernière mise à jour ISO 8601

Exemple réponse

json

{
  "success": true,
  "data": {
    "object": "payout",
    "id": "po_abc123",
    "tenantId": "tenant-1",
    "merchantId": "mch-1",
    "reference": "PAYOUT-001",
    "amount": "10000",
    "currency": "CDF",
    "status": "PENDING",
    "idempotencyKey": "payout-001",
    "beneficiaryId": "ben-1",
    "method": "BANK_TRANSFER",
    "destinationRef": "1000123456789",
    "beneficiaryName": "Compte principal",
    "providerCode": null,
    "providerRef": null,
    "failureReason": null,
    "rejectionReason": null,
    "approvedAt": null,
    "rejectedAt": null,
    "executedAt": null,
    "createdAt": "2026-08-28T11:00:00.000Z",
    "updatedAt": "2026-08-28T11:00:00.000Z"
  },
  "error": null
}

Erreurs

IDEMPOTENCY_KEY_REQUIRED (400) — Header Idempotency-Key requis
INSUFFICIENT_WALLET_BALANCE (400) — Solde wallet insuffisant
PAYOUT_BELOW_MINIMUM (400) — Montant sous le minimum autorisé

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/payments/payouts \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Idempotency-Key: charge-order-1234-unique" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500",
  "currency": "USD",
  "beneficiaryId": "ben_abc123",
  "idempotencyKey": "payout-week-32"
}'

Voir aussi

GET/api/v1/payments/payoutsPermission · merchant.payouts.read

Lister les décaissements

Liste paginée des payouts.

Paramètres de requête

Nom	Type	Requis	Description
page	number	—	Page (défaut 1)
limit	number	—	Taille page (défaut 25)
status	string	—	Filtrer par statut
merchantId	string	—	Filtrer par marchand

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours payout
id	string	Oui	Identifiant payout
amount	string	Oui	Montant
currency	string	Oui	Devise
status	string	Oui	PENDING, PROCESSING, SUCCEEDED, FAILED
method	string	—	BANK_TRANSFER, MOBILE_MONEY, etc.
destinationRef	string	—	Référence compte de destination
beneficiaryName	string \| null	—	Nom du bénéficiaire
providerCode	string \| null	—	Code provider d'exécution
executedAt	string \| null	—	Date d'exécution ISO 8601
idempotencyKey	string	Oui	Clé d'idempotence
createdAt	string	Oui	Date ISO 8601
updatedAt	string	Oui	Dernière mise à jour ISO 8601

Exemple réponse

json

{
  "success": true,
  "data": [
    {
      "object": "payout",
      "id": "po_abc123",
      "tenantId": "tenant-1",
      "merchantId": "mch-1",
      "reference": "PAYOUT-001",
      "amount": "10000",
      "currency": "CDF",
      "status": "PENDING",
      "idempotencyKey": "payout-001",
      "beneficiaryId": "ben-1",
      "method": "BANK_TRANSFER",
      "destinationRef": "1000123456789",
      "beneficiaryName": "Compte principal",
      "providerCode": null,
      "providerRef": null,
      "failureReason": null,
      "rejectionReason": null,
      "approvedAt": null,
      "rejectedAt": null,
      "executedAt": null,
      "createdAt": "2026-08-28T11:00:00.000Z",
      "updatedAt": "2026-08-28T11:00:00.000Z"
    }
  ],
  "error": null,
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 1,
    "totalPages": 1
  }
}

Exemples

bash

curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/payments/payouts \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/payments/payouts/:id/executePermission · merchant.payouts.approve, merchant.charges.manage

Exécuter un décaissement

Lance l'exécution d'un payout approuvé.

Paramètres de chemin

Nom	Type	Requis	Description
id	string	Oui	payoutId

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours payout
id	string	Oui	Identifiant payout
amount	string	Oui	Montant
currency	string	Oui	Devise
status	string	Oui	PENDING, PROCESSING, SUCCEEDED, FAILED
method	string	—	BANK_TRANSFER, MOBILE_MONEY, etc.
destinationRef	string	—	Référence compte de destination
beneficiaryName	string \| null	—	Nom du bénéficiaire
providerCode	string \| null	—	Code provider d'exécution
executedAt	string \| null	—	Date d'exécution ISO 8601
idempotencyKey	string	Oui	Clé d'idempotence
createdAt	string	Oui	Date ISO 8601
updatedAt	string	Oui	Dernière mise à jour ISO 8601

Exemple réponse

json

{
  "success": true,
  "data": {
    "object": "payout",
    "id": "po_abc123",
    "tenantId": "tenant-1",
    "merchantId": "mch-1",
    "reference": "PAYOUT-001",
    "amount": "10000",
    "currency": "CDF",
    "status": "PENDING",
    "idempotencyKey": "payout-001",
    "beneficiaryId": "ben-1",
    "method": "BANK_TRANSFER",
    "destinationRef": "1000123456789",
    "beneficiaryName": "Compte principal",
    "providerCode": null,
    "providerRef": null,
    "failureReason": null,
    "rejectionReason": null,
    "approvedAt": null,
    "rejectedAt": null,
    "executedAt": null,
    "createdAt": "2026-08-28T11:00:00.000Z",
    "updatedAt": "2026-08-28T11:00:00.000Z"
  },
  "error": null
}

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/payments/payouts/:id/execute \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/payments/payouts/beneficiariesClé API

Créer un bénéficiaire

Enregistre un compte de sortie pour les payouts.

Corps de requête

Nom	Type	Requis	Description
label	string	Oui	Nom affiché
type	string	Oui	BANK_TRANSFER ou MOBILE_MONEY
accountRef	string	Oui	Numéro de compte ou MSISDN
isDefault	boolean	—	Bénéficiaire par défaut

Exemple requête

json

{
  "label": "Compte principal",
  "type": "BANK_TRANSFER",
  "accountRef": "1000123456789",
  "isDefault": true
}

Réponse (data)

Nom	Type	Requis	Description
id	string	Oui	beneficiaryId

Exemple réponse

json

{
  "success": true,
  "data": {
    "id": "ben_abc123",
    "label": "Compte principal",
    "status": "ACTIVE"
  }
}

Exemples

bash

curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/payments/payouts/beneficiaries \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Compte principal",
  "type": "BANK_TRANSFER",
  "accountRef": "1000123456789",
  "isDefault": true
}'

Voir aussi

GET/api/v1/payments/payouts/beneficiariesClé API

Lister les bénéficiaires

Liste des comptes de sortie.

Réponse (data)

Nom	Type	Requis	Description
id	string	Oui	Identifiant

Exemple réponse

json

{
  "success": true,
  "data": [
    {
      "id": "ben_abc123",
      "label": "Compte principal"
    }
  ]
}

Exemples

bash

curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/payments/payouts/beneficiaries \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"