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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID du marchand

Corps de requête

Nom	Type	Requis	Description
amount	string	Oui	Montant
currency	string	Oui	Devise
payerWalletId	string	Oui	Wallet source du payeur
idempotencyKey	string	Oui	Clé d'idempotence unique
reference	string	—	Référence métier
description	string	—	Description

Exemple requête

json

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

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours charge
id	string	Oui	Identifiant charge
amount	string	Oui	Montant
currency	string	Oui	Devise ISO 4217
status	string	Oui	PENDING, CAPTURED, FAILED, REFUNDED
feeAmount	string	Oui	Frais plateforme
netAmount	string	Oui	Montant net marchand
idempotencyKey	string	Oui	Clé d'idempotence
paymentIntentId	string \| null	—	Intent financial-core lié
createdAt	string	Oui	Date 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": "customer@example.com",
    "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.dev.izzi-finance.com/api/v1/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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID du marchand

Paramètres de requête

Nom	Type	Requis	Description
page	number	—	Page
limit	number	—	Limite
status	string	—	Filtrer par statut

Réponse (data)

Nom	Type	Requis	Description
[].object	string	Oui	charge sur chaque élément
object	string	Oui	Toujours charge
id	string	Oui	Identifiant charge
amount	string	Oui	Montant
currency	string	Oui	Devise ISO 4217
status	string	Oui	PENDING, CAPTURED, FAILED, REFUNDED
feeAmount	string	Oui	Frais plateforme
netAmount	string	Oui	Montant net marchand
idempotencyKey	string	Oui	Clé d'idempotence
paymentIntentId	string \| null	—	Intent financial-core lié
createdAt	string	Oui	Date ISO 8601
meta.page	number	Oui	Page courante
meta.pageSize	number	Oui	Taille de page
meta.total	number	Oui	Total 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": "customer@example.com",
      "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.dev.izzi-finance.com/api/v1/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

Nom	Type	Requis	Description
chargeId	string	Oui	UUID de la charge

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours charge
id	string	Oui	Identifiant charge
amount	string	Oui	Montant
currency	string	Oui	Devise ISO 4217
status	string	Oui	PENDING, CAPTURED, FAILED, REFUNDED
feeAmount	string	Oui	Frais plateforme
netAmount	string	Oui	Montant net marchand
idempotencyKey	string	Oui	Clé d'idempotence
paymentIntentId	string \| null	—	Intent financial-core lié
createdAt	string	Oui	Date 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": "customer@example.com",
    "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.dev.izzi-finance.com/api/v1/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

Nom	Type	Requis	Description
chargeId	string	Oui	UUID de la charge

Corps de requête

Nom	Type	Requis	Description
amount	string	—	Montant partiel (omis = total)
reason	string	—	Motif du remboursement
idempotencyKey	string	Oui	Clé d'idempotence

Exemple requête

json

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

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours refund
refundId	string	Oui	Identifiant remboursement
chargeId	string	Oui	Charge remboursée
amount	string	Oui	Montant
currency	string	Oui	Devise
status	string	Oui	COMPLETED, FAILED
reason	string	—	Motif 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.dev.izzi-finance.com/api/v1/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

Nom	Type	Requis	Description
page	number	—	Page (défaut 1)
limit	number	—	Taille page (défaut 20, max 100)
starting_after	string	—	ID charge pour pagination curseur (charge suivante)
status	string	—	Filtrer par statut
merchantId	string	—	Filtrer par marchand
currency	string	—	Filtrer par devise
reference	string	—	Recherche référence
dateFrom	string	—	Date début ISO
dateTo	string	—	Date fin ISO

Réponse (data)

Nom	Type	Requis	Description
object	string	Oui	Toujours charge
id	string	Oui	Identifiant charge
amount	string	Oui	Montant
currency	string	Oui	Devise ISO 4217
status	string	Oui	PENDING, CAPTURED, FAILED, REFUNDED
feeAmount	string	Oui	Frais plateforme
netAmount	string	Oui	Montant net marchand
idempotencyKey	string	Oui	Clé d'idempotence
paymentIntentId	string \| null	—	Intent financial-core lié
createdAt	string	Oui	Date 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": "customer@example.com",
      "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.dev.izzi-finance.com/api/v1/api/v1/payments/charges \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"