> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphapay.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Relancer un paiement échoué

> Rejoue le routage sur la même transaction, sans en créer une nouvelle

<Note>
  Réutilise le même `id` de transaction — aucune nouvelle transaction n'est créée. Réservé aux paiements entrants (`flow_direction: "INBOUND"`) ; un payout renvoie `400 invalid_flow`.
</Note>

## Éviter un doublon en cas de coupure réseau

Le header `Idempotency-Key` est **optionnel** : sans lui, chaque appel relance le paiement — un simple retry réseau le relance donc une seconde fois. Avec lui, renvoyer la même clé après un timeout vous renvoie la réponse d'origine au lieu de rejouer l'opération.

Un timeout n'est jamais la preuve qu'une requête a échoué : elle a pu aboutir côté serveur. C'est précisément ce cas que la clé couvre.

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/payments/{payment_id}/retry/ \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Générez une clé **par intention** (un UUID convient), et réutilisez-la pour chaque retry de cette même tentative. Réutiliser une clé avec un corps différent renvoie `409`. Détails : [Idempotence](/api-reference/introduction#idempotence).


## OpenAPI

````yaml api-reference/openapi.json POST /payments/{payment_id}/retry/
openapi: 3.1.0
info:
  title: AlphaPay API
  description: >-
    API d'encaissement et de paiement mobile money/carte pour l'Afrique de
    l'Ouest et du Centre. Toutes les routes marchand nécessitent une clé API
    secrète (header Authorization: Bearer sk_...).
  version: 1.0.0
servers:
  - url: https://api.alphapay.me/api/v1
security:
  - bearerAuth: []
paths:
  /payments/{payment_id}/retry/:
    post:
      tags:
        - Paiements
      summary: Relancer un paiement échoué
      description: >-
        Rejoue le routage sur la Transaction existante — ne crée jamais de
        nouvelle transaction, réutilise le même `id`. Header `Idempotency-Key`
        optionnel, mais vivement recommandé : sans lui, un retry réseau relance
        une seconde fois le paiement. Scope requis dérivé automatiquement du
        sens de la transaction ciblée (PAYIN en pratique, seul un paiement
        entrant est réessayable ici).
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                methods:
                  type: array
                  items:
                    type: string
                  description: >-
                    Codes réseau à essayer, dans l'ordre. Défaut : réseau
                    d'origine de la transaction.
                  example:
                    - moov_bj
                customer:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                    first_name:
                      type: string
                    last_name:
                      type: string
                    phone:
                      type: string
                      description: 'Format international, ex: +22997505050'
                preferred_gateway:
                  type: string
            example:
              methods:
                - moov_bj
      responses:
        '200':
          description: Paiement relancé (même id de transaction)
          content:
            application/json:
              example:
                message: Payment retried successfully
                id: 9c3f2a10-4b7e-4f1a-9d2e-9b6a7c1e4a02
                checkout_url: ''
        '400':
          description: >-
            La transaction ciblée est un flux sortant (payout), non réessayable
            via cet endpoint
          content:
            application/json:
              example:
                message: >-
                  Seuls les paiements (INBOUND) sont réessayables via cet
                  endpoint.
                code: invalid_flow
        '404':
          description: Paiement introuvable
          content:
            application/json:
              example:
                message: Transaction introuvable.
                code: not_found
        '409':
          description: Transaction déjà dans un état terminal, non réessayable
          content:
            application/json:
              example:
                message: Transaction déjà 'SUCCESS', non réessayable.
                code: not_retryable
        '422':
          description: >-
            Requête valide mais impossible à router (mêmes codes que
            l'initialisation d'un paiement)
          content:
            application/json:
              example:
                message: 'Réseau inconnu ou inactif : ''moov_xx''.'
                code: invalid_method
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Identifiant unique que **vous** générez pour cette tentative (un UUID
        par exemple). Optionnel : sans lui, chaque appel est traité comme une
        nouvelle demande. Avec lui, si vous renvoyez la même clé — après un
        timeout ou une coupure réseau — AlphaPay renvoie la réponse d'origine au
        lieu de créer un second paiement. Réutilisez la même clé pour les retrys
        d'une même tentative, changez-en pour toute nouvelle intention. La même
        clé avec un corps de requête différent renvoie une erreur `409`. Voir
        [Idempotence](/api-reference/introduction#idempotence).
      schema:
        type: string
        maxLength: 255
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_live_... / sk_test_...
      description: >-
        Clé API secrète du marchand — header Authorization: Bearer sk_live_xxx
        (ou sk_test_xxx en environnement de test).

````