Payout API — VALIDIF card and account payouts

Payouts

Un payout envoie des fonds vers une carte, un compte bancaire ou un wallet.

Créer un payout

POST /v1/payouts. La destination est toujours un token : jamais un numéro de carte en clair.

Requête

curl https://api.validif.com/v1/payouts \
  -H "Authorization: Bearer vl_sec_xxxxx" \
  -H "Idempotency-Key: payout_5521" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "XOF",
    "destination_type": "card",
    "destination_token": "dst_tok_9f3a21",
    "description": "Seller settlement 5521"
  }'

Réponse 201

{
  "id": "po_7c14da55",
  "reference": "out_5521_b9c2",
  "amount": 150000,
  "currency": "XOF",
  "status": "pending",
  "destination_masked": "**** **** **** 4242",
  "request_id": "req_1c93be70"
}

Champ	Type	Description
amount	integer	Montant en unité mineure, strictement positif.
currency	string	Code ISO 4217.
destination_type	card \| account \| wallet	Type de destination.
destination_token	string	Token de destination obtenu via VALIDIF.
description	string	Libellé de règlement.
Idempotency-Key	header	Obligatoire. Rejouable pendant 24 h.

Statuts

pending ──▶ processing ──▶ succeeded
                │            └──▶ reversed / partially_reversed
                ├──▶ failed
                └──▶ returned

Champ	Type	Description
pending	status	Payout accepté, en attente d'exécution.
processing	status	Transmis au réseau de paiement.
succeeded	status	Fonds envoyés.
failed	status	Rejet définitif.
returned	status	Retourné par la banque destinataire.
reversed	status	Annulé après exécution.

Suivre un payout

GET

curl https://api.validif.com/v1/payouts/po_7c14da55 \
  -H "Authorization: Bearer vl_sec_xxxxx"

curl "https://api.validif.com/v1/payouts?limit=25&status=succeeded" \
  -H "Authorization: Bearer vl_sec_xxxxx"

Événements associés

Chaque changement de statut émet un événement payout.* livré à vos endpoints webhook (payout.created, payout.succeeded, payout.failed, payout.reversed).