Charges

Encaissements directs et remboursements.

POST/api/v1/merchant/merchants/:merchantId/chargesClé API

Créer une charge

Crée une charge directe sur le wallet d'un payeur (flux serveur-à-serveur).

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID du marchand

Corps de requête

NomTypeRequisDescription
amountstringOuiMontant
currencystringOuiDevise
payerWalletIdstringOuiWallet source du payeur
idempotencyKeystringOuiClé d'idempotence unique
referencestringNonRéférence métier
descriptionstringNonDescription

Exemple requête

json
{
  "amount": "1500",
  "currency": "USD",
  "payerWalletId": "6015fa0e-0e44-461e-9ec8-b598ca19c14b",
  "idempotencyKey": "charge-order-1234",
  "reference": "ORDER-1234"
}

Réponse (data)

NomTypeRequisDescription
objectstringOuiToujours charge
idstringOuiIdentifiant charge
amountstringOuiMontant
currencystringOuiDevise ISO 4217
statusstringOuiPENDING, CAPTURED, FAILED, REFUNDED
feeAmountstringOuiFrais plateforme
netAmountstringOuiMontant net marchand
idempotencyKeystringOuiClé d'idempotence
paymentIntentIdstring | nullNonIntent financial-core lié
createdAtstringOuiDate ISO 8601

Exemple réponse

json
{
  "success": true,
  "data": {
    "object": "charge",
    "id": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "tenantId": "tenant-1",
    "merchantId": "mch-1",
    "merchantName": "Boutique Kinshasa",
    "reference": "ORDER-1234",
    "amount": "1500",
    "currency": "USD",
    "feeAmount": "37.50",
    "netAmount": "1462.50",
    "status": "CAPTURED",
    "customerRef": "[email protected]",
    "idempotencyKey": "charge-order-1234",
    "description": "Commande #1234",
    "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
    "refundedAmount": "0",
    "capturedAt": "2026-08-28T10:00:00.000Z",
    "createdBy": "user-1",
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "error": null
}

Erreurs

  • IDEMPOTENCY_KEY_REQUIRED (400): Header Idempotency-Key ou body idempotencyKey requis
  • MERCHANT_KYB_NOT_APPROVED (400): Marchand non autorisé à transacter

Exemples

bash
curl -X POST https://api.izzi-finance.com/api/v1/merchant/merchants/:merchantId/charges \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Idempotency-Key: charge-order-1234-unique" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "1500",
  "currency": "USD",
  "payerWalletId": "6015fa0e-0e44-461e-9ec8-b598ca19c14b",
  "idempotencyKey": "charge-order-1234",
  "reference": "ORDER-1234"
}'

Voir aussi

GET/api/v1/merchant/merchants/:merchantId/chargesClé API

Lister les charges

Liste paginée des charges d'un marchand.

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID du marchand

Paramètres de requête

NomTypeRequisDescription
pagenumberNonPage
limitnumberNonLimite
statusstringNonFiltrer par statut

Réponse (data)

NomTypeRequisDescription
[].objectstringOuicharge sur chaque élément
objectstringOuiToujours charge
idstringOuiIdentifiant charge
amountstringOuiMontant
currencystringOuiDevise ISO 4217
statusstringOuiPENDING, CAPTURED, FAILED, REFUNDED
feeAmountstringOuiFrais plateforme
netAmountstringOuiMontant net marchand
idempotencyKeystringOuiClé d'idempotence
paymentIntentIdstring | nullNonIntent financial-core lié
createdAtstringOuiDate ISO 8601
meta.pagenumberOuiPage courante
meta.pageSizenumberOuiTaille de page
meta.totalnumberOuiTotal d'éléments

Exemple réponse

json
{
  "success": true,
  "data": [
    {
      "object": "charge",
      "id": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
      "tenantId": "tenant-1",
      "merchantId": "mch-1",
      "merchantName": "Boutique Kinshasa",
      "reference": "ORDER-1234",
      "amount": "1500",
      "currency": "USD",
      "feeAmount": "37.50",
      "netAmount": "1462.50",
      "status": "CAPTURED",
      "customerRef": "[email protected]",
      "idempotencyKey": "charge-order-1234",
      "description": "Commande #1234",
      "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
      "refundedAmount": "0",
      "capturedAt": "2026-08-28T10:00:00.000Z",
      "createdBy": "user-1",
      "createdAt": "2026-08-28T10:00:00.000Z",
      "updatedAt": "2026-08-28T10:00:00.000Z"
    }
  ],
  "error": null,
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 1,
    "totalPages": 1
  }
}

Exemples

bash
curl -X GET https://api.izzi-finance.com/api/v1/merchant/merchants/:merchantId/charges \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

GET/api/v1/merchant/charges/:chargeIdPermission · merchant.charges.read

Détail d'une charge

Récupère une charge par identifiant.

Paramètres de chemin

NomTypeRequisDescription
chargeIdstringOuiUUID de la charge

Réponse (data)

NomTypeRequisDescription
objectstringOuiToujours charge
idstringOuiIdentifiant charge
amountstringOuiMontant
currencystringOuiDevise ISO 4217
statusstringOuiPENDING, CAPTURED, FAILED, REFUNDED
feeAmountstringOuiFrais plateforme
netAmountstringOuiMontant net marchand
idempotencyKeystringOuiClé d'idempotence
paymentIntentIdstring | nullNonIntent financial-core lié
createdAtstringOuiDate ISO 8601

Exemple réponse

json
{
  "success": true,
  "data": {
    "object": "charge",
    "id": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "tenantId": "tenant-1",
    "merchantId": "mch-1",
    "merchantName": "Boutique Kinshasa",
    "reference": "ORDER-1234",
    "amount": "1500",
    "currency": "USD",
    "feeAmount": "37.50",
    "netAmount": "1462.50",
    "status": "CAPTURED",
    "customerRef": "[email protected]",
    "idempotencyKey": "charge-order-1234",
    "description": "Commande #1234",
    "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
    "refundedAmount": "0",
    "capturedAt": "2026-08-28T10:00:00.000Z",
    "createdBy": "user-1",
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "error": null
}

Exemples

bash
curl -X GET https://api.izzi-finance.com/api/v1/merchant/charges/:chargeId \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/merchant/charges/:chargeId/refundPermission · merchant.charges.manage

Rembourser une charge

Crée un remboursement total ou partiel sur une charge capturée.

Paramètres de chemin

NomTypeRequisDescription
chargeIdstringOuiUUID de la charge

Corps de requête

NomTypeRequisDescription
amountstringNonMontant partiel (omis = total)
reasonstringNonMotif du remboursement
idempotencyKeystringOuiClé d'idempotence

Exemple requête

json
{
  "amount": "500",
  "reason": "customer_request",
  "idempotencyKey": "refund-order-1234"
}

Réponse (data)

NomTypeRequisDescription
objectstringOuiToujours refund
refundIdstringOuiIdentifiant remboursement
chargeIdstringOuiCharge remboursée
amountstringOuiMontant
currencystringOuiDevise
statusstringOuiCOMPLETED, FAILED
reasonstringNonMotif optionnel

Exemple réponse

json
{
  "success": true,
  "data": {
    "object": "refund",
    "refundId": "ref_abc123",
    "chargeId": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "amount": "500",
    "currency": "USD",
    "status": "COMPLETED",
    "reason": "customer_request"
  },
  "error": null
}

Erreurs

  • IDEMPOTENCY_KEY_REQUIRED (400): Header Idempotency-Key requis

Exemples

bash
curl -X POST https://api.izzi-finance.com/api/v1/merchant/charges/:chargeId/refund \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Idempotency-Key: charge-order-1234-unique" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500",
  "reason": "customer_request",
  "idempotencyKey": "refund-order-1234"
}'

Voir aussi

GET/api/v1/payments/chargesPermission · payments.read, merchant.charges.read

Lister les charges (portail)

Liste paginée des charges avec filtres avancés et pagination curseur.

Paramètres de requête

NomTypeRequisDescription
pagenumberNonPage (défaut 1)
limitnumberNonTaille page (défaut 20, max 100)
starting_afterstringNonID charge pour pagination curseur (charge suivante)
statusstringNonFiltrer par statut
merchantIdstringNonFiltrer par marchand
currencystringNonFiltrer par devise
referencestringNonRecherche référence
dateFromstringNonDate début ISO
dateTostringNonDate fin ISO

Réponse (data)

NomTypeRequisDescription
objectstringOuiToujours charge
idstringOuiIdentifiant charge
amountstringOuiMontant
currencystringOuiDevise ISO 4217
statusstringOuiPENDING, CAPTURED, FAILED, REFUNDED
feeAmountstringOuiFrais plateforme
netAmountstringOuiMontant net marchand
idempotencyKeystringOuiClé d'idempotence
paymentIntentIdstring | nullNonIntent financial-core lié
createdAtstringOuiDate ISO 8601

Exemple réponse

json
{
  "success": true,
  "data": [
    {
      "object": "charge",
      "id": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
      "tenantId": "tenant-1",
      "merchantId": "mch-1",
      "merchantName": "Boutique Kinshasa",
      "reference": "ORDER-1234",
      "amount": "1500",
      "currency": "USD",
      "feeAmount": "37.50",
      "netAmount": "1462.50",
      "status": "CAPTURED",
      "customerRef": "[email protected]",
      "idempotencyKey": "charge-order-1234",
      "description": "Commande #1234",
      "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
      "refundedAmount": "0",
      "capturedAt": "2026-08-28T10:00:00.000Z",
      "createdBy": "user-1",
      "createdAt": "2026-08-28T10:00:00.000Z",
      "updatedAt": "2026-08-28T10:00:00.000Z"
    }
  ],
  "error": null,
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 42,
    "totalPages": 3
  }
}

Exemples

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

Voir aussi

API charges : Izzi Pay | Portail marchand izzi-pay