# Créer un paiement

`POST https://api.payiz.app/v1/payments`

Demande une clé secrète qui porte le geste « Paiements · créer ».

Crée un paiement, et rend la page à partager avec le payeur.

Le paiement naît « requires_payment » : rien n’est prélevé tant que le payeur n’a pas validé sur son téléphone. Envoyez-lui « payment_url », et attendez le webhook — c’est lui qui dit que l’argent est arrivé. Avec « payer », la demande part aussitôt sur son téléphone : le paiement direct.

## Les en-têtes

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `Idempotency-Key` | texte | — | Obligatoire avec « payer » : la même clé rend le même paiement, sans relancer le téléphone. Conseillée sinon. |

## Ce qu'on envoie

Un corps JSON.

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `amount` | entier | oui | Ce qu’on demande au payeur. |
| `currency` | texte | — | Sans précision : la monnaie de l’espace. |
| `description` | texte | — | Ce que le payeur lira sur sa page : dites-lui ce qu’il paie. |
| `reference` | texte | — | Votre référence, rendue telle quelle. |
| `return_url` | texte | — | Où renvoyer le payeur une fois qu’il a payé. |
| `expires_at` | entier | — | En secondes depuis 1970. |
| `fees_paid_by` | « merchant » · « customer » | — | « customer » : les frais s’ajoutent à ce qu’on lui demande. |
| `metadata` | objet | — | Vos propres clés, rendues telles quelles ; jamais lues par Payiz. |
| `payer` | objet | — | Le paiement direct : la demande part aussitôt sur son téléphone. Exige le geste « Paiements · lancer » et un en-tête Idempotency-Key. |

## Ce qu'on reçoit

`201` · un objet `payment`

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `client_secret` | texte | — | Le secret du client, rendu une seule fois à la création : il ouvre le suivi de ce paiement-là depuis le navigateur, sans clé secrète. |
| `object` | « payment » | — | Le genre de l’objet rendu : il ne change jamais. |
| `id` | texte | — | Un identifiant préfixé « pay_ », par exemple pay_01j9x3kq7m4tzv8qhw2n. |
| `amount` | entier | — | Ce qui est demandé au payeur. |
| `currency` | texte | — | Le code ISO 4217, en majuscules. |
| `status` | « requires_payment » · « processing » · « succeeded » · « expired » · « canceled » · « partially_refunded » · « refunded » | — | Où en est le paiement. |
| `description` | texte ou null | — | Ce que le payeur lit sur sa page. |
| `reference` | texte ou null | — | Votre propre référence, telle que vous l’avez posée. |
| `metadata` | objet | — | Ce que vous y avez rangé ; jamais lu par Payiz. |
| `fees_paid_by` | « merchant » · « customer » | — | Qui porte la commission : le marchand, ou le payeur en plus du montant. |
| `amount_paid` | entier ou null | — | Ce que le payeur a réellement versé, frais compris. |
| `fee` | entier ou null | — | La commission de Payiz. |
| `net` | entier ou null | — | Ce qui revient au marchand, commission prise. |
| `amount_refunded` | entier | — | Ce qui a déjà été rendu sur ce paiement. |
| `payment_url` | texte | — | La page à partager avec le payeur. |
| `return_url` | texte ou null | — | Où renvoyer le payeur une fois qu’il a payé. |
| `expires_at` | entier ou null | — | Des secondes depuis 1970, ou null. |
| `paid_at` | entier ou null | — | Des secondes depuis 1970, ou null. |
| `available_at` | entier ou null | — | Quand l’argent devient retirable. Null tant qu’il attend. |
| `latest_attempt` | objet ou null | — | La dernière demande envoyée au téléphone du payeur, ou null. |
| `created` | entier ou null | — | Des secondes depuis 1970, ou null. |
| `livemode` | vrai ou faux | — | Faux en mode test : aucun argent ne circule. |

## La demande

```bash
curl https://api.payiz.app/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: paiements-creer-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "description": "Commande 42",
    "reference": "cmd-42",
    "return_url": "https://boutique.bj/merci"
  }'
```

## La réponse

```json
{
  "client_secret": "pcs_01j9x3kq7m4tzv8qhw2n_k3f8",
  "object": "payment",
  "id": "pay_01j9x3kq7m4tzv8qhw2n",
  "amount": 10000,
  "currency": "XOF",
  "status": "requires_payment",
  "description": "Commande 42",
  "reference": "cmd-42",
  "metadata": {},
  "fees_paid_by": "merchant",
  "amount_paid": null,
  "fee": null,
  "net": null,
  "amount_refunded": 0,
  "payment_url": "https://pay.payiz.app/pay_01j9x3kq7m4tzv8qhw2n",
  "return_url": "https://boutique.bj/merci",
  "expires_at": 1790089092,
  "paid_at": null,
  "available_at": null,
  "latest_attempt": null,
  "created": 1790002692,
  "livemode": false
}
```