# Lancer une demande

`POST https://api.payiz.app/v1/payments/{id}/attempts`

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

Envoie la demande sur le téléphone du payeur, ou la relance après un échec.

Le paiement doit attendre d’être payé : une demande en cours répond « attempt_in_progress ». La réponse dit « pending » ; l’issue arrive par webhook. Exige le geste « Paiements · lancer » et un en-tête Idempotency-Key.

## Les en-têtes

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `Idempotency-Key` | texte | oui | Obligatoire ici : la même clé rend la même demande, sans relancer le téléphone. Tirez-la de votre commande. |

## Ce qu'on envoie

Un corps JSON.

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `phone` | texte | oui | Le numéro du payeur, au format international (+2290197000000). |
| `country` | texte | — | Son pays, quand le numéro est écrit sans indicatif. |
| `operator` | texte | — | Son opérateur, quand le numéro ne suffit pas à le reconnaître : un code de GET /v1/payment_methods. |

## Ce qu'on reçoit

`201` · un objet `payment_attempt`

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `object` | « payment_attempt » | — | Le genre de l’objet rendu : il ne change jamais. |
| `id` | texte | — | Un identifiant préfixé « tnt_ », par exemple tnt_01j9x4a2b7c5d8e3f6g1h0jk. |
| `payment` | texte | — | Le paiement qu’elle cherche à régler. |
| `status` | « pending » · « succeeded » · « failed » · « expired » | — | « pending » tant que le payeur n’a pas validé ; puis réussie, échouée ou expirée. |
| `source` | « payer » · « dashboard » · « api » | — | Qui l’a lancée : le payeur sur la page de paiement, votre espace, ou votre serveur par l’API. |
| `phone` | texte | — | Masqué : un numéro ne sort jamais en clair. |
| `country` | texte | — | Le pays du payeur, en ISO 3166-1 alpha-3. |
| `operator` | texte | — | Le code public de l’opérateur, par exemple « mtn ». |
| `amount` | entier | — | Ce qui est demandé au payeur, dans sa monnaie, frais compris quand il les paie. |
| `currency` | texte | — | La monnaie du payeur, celle de son pays. |
| `failure_code` | « insufficient_funds » · « payer_declined » · « timeout » · « invalid_phone » · « operator_limit » · « operator_unavailable » · « declined » · « unknown » ou null | — | La raison d’un échec ou d’une expiration ; null sinon. |
| `payer_message` | texte ou null | — | La phrase à montrer au payeur : la consigne tant qu’il doit valider, la raison si la demande échoue. Réglée par Payiz, dans la langue de « Accept-Language » ; null s’il n’y en a pas. |
| `operator_reference` | texte ou null | — | La référence que l’opérateur a donnée au payeur, quand il la donne. |
| `created` | entier ou null | — | Des secondes depuis 1970, ou null. |
| `completed_at` | entier ou null | — | Quand elle s’est conclue ; null tant qu’elle attend. |
| `livemode` | vrai ou faux | — | Faux en mode test : aucun argent ne circule. |

## La demande

```bash
curl https://api.payiz.app/v1/payments/pay_01j9x3kq7m4tzv8qhw2n/attempts \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: paiements-lancer-01" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+2290197123456",
    "operator": "mtn"
  }'
```

## La réponse

```json
{
  "object": "payment_attempt",
  "id": "tnt_01j9x4a2b7c5d8e3f6g1h0jk",
  "payment": "pay_01j9x3kq7m4tzv8qhw2n",
  "status": "pending",
  "source": "api",
  "phone": "+229 01 •• •• 34 56",
  "country": "BEN",
  "operator": "mtn",
  "amount": 10000,
  "currency": "XOF",
  "failure_code": null,
  "payer_message": "Validez le paiement de 10 000 F CFA sur votre téléphone. Si rien n’arrive, vérifiez votre solde et votre réseau, puis réessayez.",
  "operator_reference": null,
  "created": 1790002700,
  "completed_at": null,
  "livemode": false
}
```