neo-pays

Rééquilibrages

Page générée depuis la spécification OpenAPI que la passerelle sert (GET /v1/openapi.json). Ne la modifiez pas à la main : elle est réécrite à chaque build.

Méthode Chemin Description
GET /v1/rebalances Lister les rééquilibrages
POST /v1/rebalances Rééquilibrer entre vos plateformes
GET /v1/rebalances/{id} Consulter un rééquilibrage
GET /v1/settlement-expectations Lister les règlements carte attendus
POST /v1/settlement-expectations Annoncer le règlement carte attendu
GET /v1/rebalance-requests Lister les demandes de rééquilibrage
POST /v1/rebalance-requests Demander un rééquilibrage à la trésorerie
GET /v1/rebalance-requests/{id} Lire une demande de rééquilibrage

GET /v1/rebalances

Lister les rééquilibrages

Même pagination que les encaissements.

Paramètres

Nom Emplacement Requis Description
page query non Page, à partir de 1.
per_page query non Taille de page, 100 au maximum.

Réponses

  • 200 — OK (OperationList)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

POST /v1/rebalances

Rééquilibrer entre vos plateformes

Le jumeau à un seul compte du virement interne : déplace vos propres fonds d'une plateforme vers une autre. Mêmes conditions que le virement interne.

Nommer les deux corridors. Chacun accepte son identifiant ou son code — platform_id / platform_code pour la source, destination_platform_id / destination_platform_code pour la destination. Ils se résolvent indépendamment : corriger la source ne masque pas une destination erronée.

Nommer les pots. platform_account_handle (source) et destination_platform_account_handle (destination) désignent un sous-compte précis par son nom stable, tel que GET /v1/balances le rend. Absents = le pot principal du corridor, comme avant. Un nom inconnu est refusé (422 unknown_platform_account), jamais replié sur le pot principal.

Paramètres

Nom Emplacement Requis Description
Idempotency-Key header non Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409).

Corps de la requête

Champ Type Requis Description
asset_id integer oui
amount_minor string oui Montant en UNITÉS MINEURES, en chaîne de caractères. Jamais un nombre à virgule flottante : les deux perdent des centimes. Le nombre de décimales de l'actif est donné par GET /v1/assets.
country string oui ISO 3166-1 alpha-2
platform_id integer non L'identifiant numérique du corridor. ⚠️ NON PORTABLE ENTRE ENVIRONNEMENTS : les identifiants de plateforme sont attribués par ordre d'insertion en base, si bien qu'un identifiant relevé en bac à sable peut nommer un autre rail en production. Préférez platform_code. Envoyez l'un ou l'autre ; envoyer les deux n'est accepté que s'ils concordent, et refusé par un 422 platform_conflict sinon.
platform_code string non Le code STABLE du corridor — 'orange', 'wave', 'yas'. Insensible à la casse. Désigne la même plateforme dans tous les environnements, ce que platform_id ne fait pas. Envoyez celui-ci ou platform_id.
destination_platform_id integer oui La plateforme créditée.
destination_platform_code string non Le code stable du corridor de destination. Se résout indépendamment de platform_code, et refuse son propre désaccord avec destination_platform_id.
platform_account_handle string non Optionnel. Le nom stable du pot SOURCE sur sa plateforme (client_platform_accounts.handle). Absent = le pot principal.
destination_platform_account_handle string non Optionnel. Le nom stable du pot DESTINATION, ex. 'neo-card-card-programme'. Absent = le pot principal. Résolu indépendamment de la source.
client_ref string non
description string non

Réponses

  • 201 — Rééquilibrage créé (Operation)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 409 — Clé d'idempotence rejouée avec une charge utile différente, ou aucun tarif de virement interne configuré pour cet actif et ce pays (pricing_unavailable) (Error)
  • 422 — Requête recevable mais refusée : champ manquant, corridor fermé, destination non payable (invalid_destination), pot nommé inconnu (unknown_platform_account), solde insuffisant (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
  • 503 — platform_code momentanément irrésoluble : le catalogue des plateformes est illisible (temporarily_unavailable). Ce n'est pas un refus — renvoyer la même requête après Retry-After (Error)

GET /v1/rebalances/{id}

Consulter un rééquilibrage

La même vue masquée que GET /v1/payments/{id}.

Paramètres

Nom Emplacement Requis Description
id path oui Identifiant interne, référence de l'opération, ou votre propre client_ref.

Réponses

  • 200 — OK (Operation)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

GET /v1/settlement-expectations

Lister les règlements carte attendus

Vos attentes par jour de règlement (bornes incluses), la plus récente d'abord. Sans to : aujourd'hui (UTC) ; sans from : 30 jours avant to ; 366 jours au plus.

Paramètres

Nom Emplacement Requis Description
from query non Premier jour de règlement inclus, YYYY-MM-DD.
to query non Dernier jour de règlement inclus, YYYY-MM-DD.

Réponses

  • 200 — OK (SettlementExpectationList)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 422 — Bornes mal formées ou intervalle trop long (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

POST /v1/settlement-expectations

Annoncer le règlement carte attendu

Annonce le montant que le schéma carte débitera, un jour donné, du pot nommé (ex. le compte programme carte Ecobank, neo-card-card-programme). neo-pays le conserve awaiting_bank et rapproche le débit du relevé bancaire de ce montant. Aucun fonds ne bouge.

Idempotent sur le jour et le pot. Le même montant pour le même (settlement_date, pot) renvoie l'attente enregistrée (200), quelle que soit la clé d'idempotence ; un montant DIFFÉRENT est refusé (409 expectation_conflict) et ne remplace jamais le premier.

Scope can_payout ; une clé live exige un compte live.

Paramètres

Nom Emplacement Requis Description
Idempotency-Key header non Conservée pour la traçabilité (ex. l'identifiant de votre outbox). L'idempotence porte sur (settlement_date, pot), pas sur cette clé.

Corps de la requête

Champ Type Requis Description
settlement_date string oui Le jour de règlement, YYYY-MM-DD.
asset_id integer oui
country string oui ISO 3166-1 alpha-2
platform_id integer non L'identifiant numérique de la plateforme (non portable). Envoyez celui-ci ou platform_code.
platform_code string non Le code stable de la plateforme, ex. 'sn-ecobank-senegal'.
platform_account_handle string non Optionnel. Le nom stable du pot, ex. 'neo-card-card-programme'. Absent = le pot principal ; inconnu = 422 unknown_platform_account.
amount_minor string oui Montant attendu en UNITÉS MINEURES, entier ≥ 0, en chaîne.
client_ref string non Votre référence, ex. la référence du rapport de règlement.

Réponses

  • 200 — Rejeu : la même attente (même jour, même pot, même montant) était déjà enregistrée (SettlementExpectationResponse)
  • 201 — Attente enregistrée (SettlementExpectationResponse)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 409 — expectation_conflict : une attente existe déjà pour ce jour et ce pot avec un autre montant ; le corps porte aussi l'attente enregistrée sous data (Error)
  • 422 — Requête recevable mais refusée : champ manquant ou mal formé, plateforme inconnue, pot nommé inconnu (unknown_platform_account) (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
  • 503 — platform_code momentanément irrésoluble : le catalogue des plateformes est illisible (temporarily_unavailable). Ce n'est pas un refus — renvoyer la même requête après Retry-After (Error)

GET /v1/rebalance-requests

Lister les demandes de rééquilibrage

Vos demandes, la plus récente d'abord, du mode (test ou live) de la clé. Scope can_read_transactions.

Paramètres

Nom Emplacement Requis Description
status query non Filtre sur le statut.
limit query non 1–200, défaut 50.

Réponses

  • 200 — Les demandes (RebalanceRequestList)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

POST /v1/rebalance-requests

Demander un rééquilibrage à la trésorerie

Demande à la trésorerie neo-pays de déplacer vos créances d'un de vos pots vers un autre — y compris vers un pot que POST /v1/rebalances refuse (invalid_destination), comme la ligne PI du produit ou le compte programme carte. Une demande, pas un mouvement : elle entre dans la file à quatre yeux de la finance ; une fois approuvée, elle s'exécute comme un rééquilibrage ordinaire qui apparaît alors dans GET /v1/rebalances (rebalance_id). Seuls les pots inscrits sur votre liste d'autorisation peuvent être demandés (422 destination_not_allowed).

Idempotent sur client_ref. Le même corps renvoie la demande enregistrée (200) ; un corps différent est refusé (409 rebalance_request_conflict).

Suivi par interrogation (pas d'événement) : GET /v1/rebalance-requests/{id} toutes les 5 minutes tant que le statut n'est pas final (executed, failed, rejected, expired).

Scope can_payout ; une clé live exige un compte live.

Corps de la requête

Champ Type Requis Description
amount_minor string oui Montant en UNITÉS MINEURES, entier > 0, en chaîne.
asset_id integer oui
country string oui ISO 3166-1 alpha-2
source object oui
source.platform_code string non Le code stable de la plateforme, ex. 'neo-card' (ligne PI) ou 'sn-ecobank-senegal'.
source.platform_id integer non L'identifiant numérique (non portable). Envoyez celui-ci ou platform_code.
source.platform_account_handle string non Optionnel. Le nom stable du pot, ex. 'neo-card-card-programme'. Absent = le pot principal.
destination object oui
destination.platform_code string non Le code stable de la plateforme, ex. 'neo-card' (ligne PI) ou 'sn-ecobank-senegal'.
destination.platform_id integer non L'identifiant numérique (non portable). Envoyez celui-ci ou platform_code.
destination.platform_account_handle string non Optionnel. Le nom stable du pot, ex. 'neo-card-card-programme'. Absent = le pot principal.
reason string oui Pourquoi (≤ 500 caractères) — lu par la personne qui approuve.
client_ref string oui Votre référence (≤ 128), la clé d'idempotence.

Réponses

  • 200 — Rejeu : la même demande était déjà enregistrée (RebalanceRequestResponse)
  • 201 — Demande enregistrée, en attente d'approbation (pending_approval) (RebalanceRequestResponse)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 409 — rebalance_request_conflict : ce client_ref nomme déjà une demande au corps différent (Error)
  • 422 — Refusée : champ manquant (invalid_request), plateforme ou pot inconnu (unknown_platform, unknown_platform_account), source = destination (same_pot), destination hors liste d'autorisation (destination_not_allowed) (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)
  • 503 — platform_code momentanément irrésoluble : le catalogue des plateformes est illisible (temporarily_unavailable). Ce n'est pas un refus — renvoyer la même requête après Retry-After (Error)

GET /v1/rebalance-requests/{id}

Lire une demande de rééquilibrage

Le statut courant d'une de vos demandes : pending_approval → approved → executed (avec rebalance_id), ou rejected, expired, failed (avec failure_code). Scope can_read_transactions.

Paramètres

Nom Emplacement Requis Description
id path oui L'identifiant de la demande.

Réponses

  • 200 — La demande (RebalanceRequestResponse)
  • 401 — Clé API manquante ou rejetée (Error)
  • 403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
  • 404 — Aucune demande de ce compte (et de ce mode) sous cet identifiant (Error)
  • 429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

Schémas

Les formes renvoyées par les opérations ci-dessus.

OperationList

Champ Type Description
data Operation[]
data[].id string L'identifiant public de l'opération. C'est celui des chemins /v1/payments/{id}.
data[].ref string Notre référence interne, lisible. Distincte de l'identifiant : citez-la au support.
data[].client_ref string La référence que vous avez fournie à la création, rendue telle quelle.
data[].kind string payin | payout | withdrawal | refund | chargeback | adjustment | transfer | rebalance. Le même objet sert les cinq familles ; ce champ dit laquelle.
data[].status string L'état détaillé du rail. ⚠️ Pour décider si l'argent est arrivé, lisez outcome : status porte le détail du parcours et son vocabulaire dépend du rail.
data[].outcome string pending | succeeded | failed | cancelled | expired | reversed. Le seul champ sur lequel fonder une décision métier.
data[].asset_id integer L'actif de l'opération, par son identifiant (GET /v1/assets).
data[].amount_minor string Le montant BRUT en unités mineures, en chaîne de caractères.
data[].fee_minor string Les frais prélevés, en unités mineures.
data[].net_minor string Le net en unités mineures : amount_minor moins fee_minor.
data[].platform_id integer La plateforme qui a porté l'opération. Absent tant qu'un encaissement hébergé attend que le payeur choisisse.
data[].is_test boolean Vrai pour une opération créée avec une clé de test. Aucun argent réel ne bouge.
data[].payment_url string La page de paiement hébergée, quand le rail en fournit une. Absent tant que la soumission n'a pas abouti.
data[].deeplink string Le lien profond vers l'application du rail, quand il en fournit un.
data[].qrcode_url string Le QR à présenter au payeur, quand le rail en fournit un.
data[].risk Risk État du contrôle des risques (FRAML). Absent si l’opération n’a pas été évaluée — ce qui n’est pas la même chose que « clear ». Le webhook sortant et cette lecture rendent le même bloc.
data[].risk.status string held : les fonds ne sont pas partis. review : le paiement a suivi son cours, quelque chose est examiné. clear : rien à signaler.
data[].risk.case_ref string Référence du dossier opérationnel, à citer auprès du support. Null lorsque la retenue relève d’un examen de conformité.
data[].risk.case_kind string Accompagne case_ref ou rien du tout.
data[].risk.reason string Le seul texte que ce bloc porte, et il est identique pour toute retenue.
data[].risk.signals object[] Signaux produit, consultatifs. Absent s’il n’y en a aucun.
data[].risk.signals[].code string
data[].risk.signals[].detail_fr string
data[].amount_refunded_minor string Encaissements seulement : la somme des remboursements ABOUTIS, en unités mineures.
data[].amount_refund_pending_minor string Encaissements seulement : la somme des remboursements EN COURS, en unités mineures.
data[].amount_refundable_minor string Encaissements seulement : ce qui peut être remboursé MAINTENANT, en unités mineures — le montant d'origine moins les remboursements aboutis et en cours, ou "0" quand la règle de remboursement n'en permet plus aucun (encaissement non abouti, délai Wave dépassé après un remboursement partiel…).
data[].refund_count integer Encaissements seulement : le nombre de remboursements non échoués.
data[].partial_refund_deadline string Encaissements Wave seulement : jusqu'à quand un remboursement partiel est possible (RFC 3339). Absent pour les autres rails, ou quand les remboursements partiels Wave sont désactivés.
page integer
per_page integer

Error

Champ Type Description
error object
error.code string
error.message string

Operation

Une opération monétaire — encaissement, versement, remboursement, virement ou rééquilibrage. Le même objet dans les cinq familles.

Champ Type Description
id string L'identifiant public de l'opération. C'est celui des chemins /v1/payments/{id}.
ref string Notre référence interne, lisible. Distincte de l'identifiant : citez-la au support.
client_ref string La référence que vous avez fournie à la création, rendue telle quelle.
kind string payin | payout | withdrawal | refund | chargeback | adjustment | transfer | rebalance. Le même objet sert les cinq familles ; ce champ dit laquelle.
status string L'état détaillé du rail. ⚠️ Pour décider si l'argent est arrivé, lisez outcome : status porte le détail du parcours et son vocabulaire dépend du rail.
outcome string pending | succeeded | failed | cancelled | expired | reversed. Le seul champ sur lequel fonder une décision métier.
asset_id integer L'actif de l'opération, par son identifiant (GET /v1/assets).
amount_minor string Le montant BRUT en unités mineures, en chaîne de caractères.
fee_minor string Les frais prélevés, en unités mineures.
net_minor string Le net en unités mineures : amount_minor moins fee_minor.
platform_id integer La plateforme qui a porté l'opération. Absent tant qu'un encaissement hébergé attend que le payeur choisisse.
is_test boolean Vrai pour une opération créée avec une clé de test. Aucun argent réel ne bouge.
payment_url string La page de paiement hébergée, quand le rail en fournit une. Absent tant que la soumission n'a pas abouti.
deeplink string Le lien profond vers l'application du rail, quand il en fournit un.
qrcode_url string Le QR à présenter au payeur, quand le rail en fournit un.
risk Risk État du contrôle des risques (FRAML). Absent si l’opération n’a pas été évaluée — ce qui n’est pas la même chose que « clear ». Le webhook sortant et cette lecture rendent le même bloc.
risk.status string held : les fonds ne sont pas partis. review : le paiement a suivi son cours, quelque chose est examiné. clear : rien à signaler.
risk.case_ref string Référence du dossier opérationnel, à citer auprès du support. Null lorsque la retenue relève d’un examen de conformité.
risk.case_kind string Accompagne case_ref ou rien du tout.
risk.reason string Le seul texte que ce bloc porte, et il est identique pour toute retenue.
risk.signals object[] Signaux produit, consultatifs. Absent s’il n’y en a aucun.
risk.signals[].code string
risk.signals[].detail_fr string
amount_refunded_minor string Encaissements seulement : la somme des remboursements ABOUTIS, en unités mineures.
amount_refund_pending_minor string Encaissements seulement : la somme des remboursements EN COURS, en unités mineures.
amount_refundable_minor string Encaissements seulement : ce qui peut être remboursé MAINTENANT, en unités mineures — le montant d'origine moins les remboursements aboutis et en cours, ou "0" quand la règle de remboursement n'en permet plus aucun (encaissement non abouti, délai Wave dépassé après un remboursement partiel…).
refund_count integer Encaissements seulement : le nombre de remboursements non échoués.
partial_refund_deadline string Encaissements Wave seulement : jusqu'à quand un remboursement partiel est possible (RFC 3339). Absent pour les autres rails, ou quand les remboursements partiels Wave sont désactivés.

SettlementExpectationList

Champ Type Description
data SettlementExpectation[]
data[].id string
data[].object string
data[].settlement_date string Le jour de règlement (YYYY-MM-DD).
data[].asset_id integer
data[].country string ISO 3166-1 alpha-2
data[].platform_id integer
data[].platform_code string Le code stable de la plateforme ; null s'il est inconnu.
data[].platform_account_id integer Le pot (0 = notre compte de plateforme).
data[].platform_account_handle string Le nom stable du pot ; null pour le pot principal non nommé.
data[].amount_minor string Montant attendu en unités mineures ; 0 = aucun règlement ce jour-là.
data[].client_ref string
data[].status string awaiting_bank à la création ; matched / unmatched après rapprochement.
data[].is_test boolean
data[].created_at string
data[].updated_at string
data[].match object Le débit du relevé bancaire rapproché de cette attente ; null tant que status n'est pas matched. Le rapprochement tolère un écart de date (± N jours ouvrés autour de settlement_date) et, si la finance l'a fixée, une tolérance de montant.
data[].match.statement_ref string La référence stable de la ligne du relevé (:<référence bancaire>).
data[].match.amount_minor string Ce que la banque a débité, en unités mineures — le montant du déchargement du pot ; peut différer de amount_minor dans la tolérance.
data[].match.date string La date de comptabilisation de la ligne bancaire (YYYY-MM-DD).
data[].match.matched_at string
data[].match.discharge_status string L'écriture qui sort le montant du pot : posted une fois comptabilisée ; refused si le pot ne le couvrait pas (reprise quotidienne).
data[].match.discharged_at string
data[].unmatched_reason string Pourquoi l'attente est unmatched (ex. no_bank_debit_within_window) ; null sinon.
data[].unmatched_at string

SettlementExpectationResponse

Champ Type Description
data SettlementExpectation Le règlement carte ATTENDU pour un jour et un pot, tel que l'application l'annonce. Reste awaiting_bank jusqu'au rapprochement du débit correspondant sur le relevé bancaire.
data.id string
data.object string
data.settlement_date string Le jour de règlement (YYYY-MM-DD).
data.asset_id integer
data.country string ISO 3166-1 alpha-2
data.platform_id integer
data.platform_code string Le code stable de la plateforme ; null s'il est inconnu.
data.platform_account_id integer Le pot (0 = notre compte de plateforme).
data.platform_account_handle string Le nom stable du pot ; null pour le pot principal non nommé.
data.amount_minor string Montant attendu en unités mineures ; 0 = aucun règlement ce jour-là.
data.client_ref string
data.status string awaiting_bank à la création ; matched / unmatched après rapprochement.
data.is_test boolean
data.created_at string
data.updated_at string
data.match object Le débit du relevé bancaire rapproché de cette attente ; null tant que status n'est pas matched. Le rapprochement tolère un écart de date (± N jours ouvrés autour de settlement_date) et, si la finance l'a fixée, une tolérance de montant.
data.match.statement_ref string La référence stable de la ligne du relevé (:<référence bancaire>).
data.match.amount_minor string Ce que la banque a débité, en unités mineures — le montant du déchargement du pot ; peut différer de amount_minor dans la tolérance.
data.match.date string La date de comptabilisation de la ligne bancaire (YYYY-MM-DD).
data.match.matched_at string
data.match.discharge_status string L'écriture qui sort le montant du pot : posted une fois comptabilisée ; refused si le pot ne le couvrait pas (reprise quotidienne).
data.match.discharged_at string
data.unmatched_reason string Pourquoi l'attente est unmatched (ex. no_bank_debit_within_window) ; null sinon.
data.unmatched_at string

RebalanceRequestList

Champ Type Description
data RebalanceRequest[]
data[].id string
data[].object string
data[].status string
data[].asset_id integer
data[].country string
data[].source object
data[].source.platform_id integer
data[].source.platform_code string
data[].source.platform_account_handle string
data[].destination object
data[].destination.platform_id integer
data[].destination.platform_code string
data[].destination.platform_account_handle string
data[].amount_minor string
data[].reason string
data[].client_ref string
data[].is_test boolean
data[].rebalance_id string Le rééquilibrage exécuté (GET /v1/rebalances), une fois executed.
data[].failure_code string
data[].created_at string
data[].updated_at string
data[].executed_at string

RebalanceRequestResponse

Champ Type Description
data RebalanceRequest
data.id string
data.object string
data.status string
data.asset_id integer
data.country string
data.source object
data.source.platform_id integer
data.source.platform_code string
data.source.platform_account_handle string
data.destination object
data.destination.platform_id integer
data.destination.platform_code string
data.destination.platform_account_handle string
data.amount_minor string
data.reason string
data.client_ref string
data.is_test boolean
data.rebalance_id string Le rééquilibrage exécuté (GET /v1/rebalances), une fois executed.
data.failure_code string
data.created_at string
data.updated_at string
data.executed_at string