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

# Créer une session

> Crée une page de paiement hébergée et renvoie son adresse dans `checkout_url`. Redirigez-y votre client.

> [!TIP]
>
> Essayez avec une clé **sandbox** (`mp_sandbox_…`) : aucun argent réel ne bouge. Voir [Test et production](https://docs.mercy-pay.com/start/environments.md).

La session dure 30 minutes. Votre client choisit sur la page son moyen de paiement : carte, ou mobile money dans n'importe quel pays proposé, avec conversion automatique. Voir [Accepter un paiement](https://docs.mercy-pay.com/payments/accept-a-payment.md) pour le parcours complet.


## OpenAPI

````yaml POST /api/v1/checkout_sessions
openapi: 3.1.0
info:
  title: API Mercy Pay
  version: 1.0.0
  description: >-
    Encaissez par mobile money et par carte, facturez en récurrent et versez vos
    fonds. Les montants sont des entiers en unités mineures. Chaque réponse
    porte un en-tête `Request-Id`.
servers:
  - url: https://mercy-pay.com
    description: >-
      Production. La clé choisit l'environnement : `mp_sandbox_…` ou
      `mp_live_…`.
security:
  - bearerAuth: []
tags:
  - name: Compte
  - name: Sessions de paiement
  - name: Paiements
  - name: Remboursements
    description: Rendre un paiement au client, en entier.
  - name: Liens de paiement
  - name: Plans
  - name: Abonnements
  - name: Clients
  - name: Factures
  - name: Espace client
  - name: Soldes
  - name: Retraits
  - name: État des opérateurs
  - name: Événements
    description: Tout ce qui s'est passé sur le compte, envoyé ou non à un endpoint.
  - name: Endpoints de webhook
    description: Les URL de votre serveur qui reçoivent les événements.
paths:
  /api/v1/checkout_sessions:
    post:
      tags:
        - Sessions de paiement
      summary: Créer une session
      description: >-
        Crée une page de paiement hébergée et renvoie son adresse dans
        `checkout_url`. Redirigez-y votre client.
      operationId: createCheckoutSession
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
              properties:
                amount:
                  type: integer
                  description: >-
                    Montant en unités mineures, au moins `1`. Voir [Montants et
                    devises](/payments/amounts-and-currencies).
                  minimum: 1
                currency:
                  type: string
                  description: Code devise ISO 4217 de 3 lettres, par exemple `XAF`.
                  minLength: 3
                  maxLength: 3
                description:
                  type: string
                  description: Affichée au client. 500 caractères maximum.
                  maxLength: 500
                payer_name:
                  type: string
                  description: Nom du payeur, prérempli
                  maxLength: 255
                payer_email:
                  type: string
                  description: E-mail du payeur, prérempli
                  format: email
                  maxLength: 255
                payer_phone:
                  type: string
                  description: Téléphone du payeur, prérempli
                  maxLength: 20
                success_url:
                  type: string
                  description: >-
                    Retour après paiement réussi `{CHECKOUT_SESSION_ID}` y est
                    remplacé par l'identifiant de la session (`cs_…`) au retour
                    du client.
                  format: uri
                  maxLength: 2048
                cancel_url:
                  type: string
                  description: >-
                    Retour si le client abandonne `{CHECKOUT_SESSION_ID}` y est
                    remplacé par l'identifiant de la session (`cs_…`) au retour
                    du client.
                  format: uri
                  maxLength: 2048
                payment_method_types:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - mobile_money
                      - card
                  description: >-
                    Ne proposer que ces moyens. Par exemple `["mobile_money"]`
                    si vous encaissez déjà la carte ailleurs. Absent : tous les
                    moyens ouverts.
                allowed_countries:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  description: >-
                    Ne proposer que ces pays mobile money (codes à 3 lettres,
                    pays ouverts uniquement). Absent : tous les pays ouverts.
                metadata:
                  type: object
                  additionalProperties: true
                  description: >-
                    Vos données libres, renvoyées dans les réponses et les
                    webhooks.
            example:
              amount: 15000
              currency: XAF
              description: Commande 4821
              success_url: https://boutique-ada.example/merci
              cancel_url: https://boutique-ada.example/panier
              metadata:
                order_id: '4821'
      responses:
        '201':
          description: Session créée
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CheckoutSession'
              example:
                data:
                  id: cs_01J9Z3V8QK4M2XW7R6TB5N0HYD
                  object: checkout_session
                  livemode: false
                  created: '2026-10-03T10:20:00+00:00'
                  amount: 15000
                  currency: XAF
                  description: Commande 4821
                  payer_name: null
                  payer_email: null
                  payer_phone: null
                  payer_address: null
                  success_url: https://boutique-ada.example/merci
                  cancel_url: https://boutique-ada.example/panier
                  status: created
                  metadata:
                    order_id: '4821'
                  checkout_url: https://mercy-pay.com/paiement/01J9Z3V8QK4M2XW7R6TB5N0HYD
                  expires_at: '2026-10-03T10:50:00+00:00'
                  payment: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        Une clé unique par opération : la rejouer pendant 24 heures renvoie la
        même réponse sans rien créer de plus. Voir
        [Idempotence](/developers/idempotency).
  schemas:
    CheckoutSession:
      type: object
      properties:
        id:
          type: string
          description: Identifiant de la session (`cs_…`)
        object:
          type: string
          const: checkout_session
        livemode:
          type: boolean
          description: '`true` pour de l''argent réel (clé live), `false` en sandbox'
        created:
          type:
            - string
            - 'null'
          format: date-time
          description: Date de création, ISO 8601
        amount:
          type: integer
          description: Montant demandé, en unités mineures.
        currency:
          type: string
          description: Devise du montant
        description:
          type:
            - string
            - 'null'
          description: Affichée au client
        payer_name:
          type:
            - string
            - 'null'
          description: Nom du payeur
        payer_email:
          type:
            - string
            - 'null'
          description: E-mail du payeur
        payer_phone:
          type:
            - string
            - 'null'
          description: Téléphone du payeur
        payer_address:
          type:
            - object
            - 'null'
          description: >-
            Adresse saisie, si un lien de paiement la demande : `line1`, `city`,
            `country`.
        payment_link:
          type:
            - string
            - 'null'
          description: Lien de paiement d'origine (`plink_…`), `null` sinon
        custom_fields:
          type: object
          additionalProperties: true
          description: >-
            Réponses aux champs personnalisés d'un lien de paiement, par `id` de
            champ. Pour un fichier, son nom.
        success_url:
          type:
            - string
            - 'null'
          description: Retour après paiement réussi
        cancel_url:
          type:
            - string
            - 'null'
          description: Retour si le client abandonne
        payment_method_types:
          type:
            - array
            - 'null'
          items:
            type: string
            enum:
              - mobile_money
              - card
          description: >-
            Moyens proposés sur la page de paiement. `null` : tous les moyens
            ouverts.
        allowed_countries:
          type:
            - array
            - 'null'
          items:
            type: string
          description: 'Pays mobile money proposés. `null` : tous les pays ouverts.'
        status:
          type: string
          description: >-
            Voir [Sessions de
            paiement](/payments/checkout-sessions#cycle-de-vie).
          enum:
            - created
            - pending_payment
            - completed
            - expired
            - cancelled
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Vos données libres. Voir [Metadata](/developers/metadata).
        checkout_url:
          type: string
          description: Page de paiement hébergée où rediriger votre client.
          format: uri
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Fin de validité, 30 minutes après la création.
        payment:
          oneOf:
            - $ref: '#/components/schemas/Payment'
            - type: 'null'
          description: >-
            Dernière tentative de paiement du client, `null` tant qu'il n'a rien
            lancé.
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Identifiant du paiement (`pay_…`)
        object:
          type: string
          const: payment
        livemode:
          type: boolean
          description: '`true` pour de l''argent réel (clé live), `false` en sandbox'
        created:
          type:
            - string
            - 'null'
          format: date-time
          description: Date de création, ISO 8601
        checkout_session:
          type:
            - string
            - 'null'
          description: >-
            Session de checkout d'origine (`cs_…`), `null` pour un paiement
            direct. Avec `expand[]=checkout_session`, la session complète
        amount:
          type: integer
          description: Montant payé par le payeur, en unités mineures
        fee_amount:
          type: integer
          description: Frais retenus
        net_amount:
          type: integer
          description: Montant versé sur votre solde
        fee_paid_by:
          type: string
          enum:
            - merchant
            - customer
          description: >-
            Qui a payé les frais. `merchant` : ils sont déduits de `net_amount`.
            `customer` : ils sont ajoutés à `amount`, et `net_amount` est le
            prix demandé.
        amount_refunded:
          type: integer
          description: >-
            Ce qui a déjà été rendu au client par des remboursements, en unités
            mineures. Le paiement passe à `refunded` quand il atteint `amount`.
        currency:
          type: string
          description: >-
            Devise réellement encaissée. En mobile money, celle de l'opérateur,
            après conversion si besoin.
        payment_method:
          type: string
          description: Canal de paiement
          enum:
            - mobile_money
            - card
        mobile_money_country:
          type:
            - string
            - 'null'
          description: Pays de l'opérateur, `null` pour une carte.
        mobile_money_provider:
          type:
            - string
            - 'null'
          description: Opérateur, `null` pour une carte.
        payer:
          type: object
          description: >-
            Le payeur, tel que saisi sur la page de paiement ou transmis à la
            création. Pour le mobile money, `phone` est le numéro réellement
            débité.
          properties:
            name:
              type:
                - string
                - 'null'
            email:
              type:
                - string
                - 'null'
            phone:
              type:
                - string
                - 'null'
              description: Indicatif compris, sans `+`, par exemple `237677123456`.
        status:
          type: string
          description: Voir [Paiements](/payments/payment-object#statuts).
          enum:
            - pending
            - processing
            - succeeded
            - failed
            - canceled
            - expired
            - refunded
            - disputed
        failure_code:
          type:
            - string
            - 'null'
          description: >-
            Code stable de l'échec quand `status` vaut `failed`, sinon `null`.
            Voir [la liste](/api/payments/create#failure_code).
        failure_reason:
          type:
            - string
            - 'null'
          description: Raison de l'échec en français, à afficher telle quelle.
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Vos données libres. Voir [Metadata](/developers/metadata).
        next_action:
          $ref: '#/components/schemas/NextAction'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - invalid_request_error
                - idempotency_error
                - payment_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: Code stable, à tester dans votre code
            message:
              type: string
              description: Explication en français, pour un humain
            param:
              type:
                - string
                - 'null'
              description: Le premier champ en cause
            doc_url:
              type: string
              description: Explication de ce code
            request_id:
              type: string
              description: >-
                Identifiant de la requête (`req_…`), aussi dans l'en-tête
                `Request-Id`
            errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
              description: Détail par champ refusé, sur une erreur `422`
      required:
        - error
    NextAction:
      type:
        - object
        - 'null'
      description: >-
        Ce que votre client doit encore faire. Décidez selon `type`, pas selon
        la seule présence du champ : un futur moyen de paiement pourra ajouter
        son propre `type`.
      properties:
        type:
          type: string
          description: >-
            `card_payment` (confirmer une carte depuis votre formulaire) ou
            `redirect` (envoyer le client sur `redirect_url`).
          enum:
            - card_payment
            - redirect
        client_secret:
          type: string
          description: >-
            `card_payment` : secret qui confirme le paiement depuis votre
            formulaire.
        redirect_url:
          type: string
          description: '`redirect` : page hébergée où le client termine.'
          format: uri
  responses:
    Unauthorized:
      description: Clé absente, invalide ou révoquée
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              code: api_key_invalid
              message: Clé API invalide.
              param: null
              doc_url: https://docs.mercy-pay.com/developers/errors#api_key_invalid
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
    Forbidden:
      description: Compte suspendu, ou clé live avant l'approbation du KYC
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              code: live_mode_requires_kyc
              message: Le mode live demande un KYC approuvé.
              param: null
              doc_url: >-
                https://docs.mercy-pay.com/developers/errors#live_mode_requires_kyc
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
    Conflict:
      description: Conflit avec l'état de la ressource, ou clé d'idempotence réutilisée
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: conflict
              message: 'Cette ressource est utilisée : archivez-la.'
              param: null
              doc_url: https://docs.mercy-pay.com/developers/errors#conflict
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
    ValidationFailed:
      description: Données invalides, avec le détail dans `errors`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: validation_failed
              message: Le champ amount est obligatoire.
              param: amount
              doc_url: https://docs.mercy-pay.com/developers/errors#validation_failed
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
              errors:
                amount:
                  - Le champ amount est obligatoire.
    RateLimited:
      description: Plus de 60 requêtes par minute avec cette clé
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: rate_limit_error
              code: rate_limited
              message: Trop de requêtes.
              param: null
              doc_url: https://docs.mercy-pay.com/developers/errors#rate_limited
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Votre clé API. Utilisez une clé sandbox (`mp_sandbox_…`) pour essayer :
        aucun argent réel ne bouge.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.