> ## 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.

# Ouvrir l'espace client

> Crée un accès d'une heure à l'espace client d'un de vos abonnés. Redirigez-le tout de suite vers `url`, sans la stocker.

À ouvrir depuis un bouton « Gérer mon abonnement » de votre site. Voir [Espace client](https://docs.mercy-pay.com/subscriptions/billing-portal.md) pour ce que votre abonné y fait.


## OpenAPI

````yaml POST /api/v1/billing_portal/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/billing_portal/sessions:
    post:
      tags:
        - Espace client
      summary: Ouvrir l'espace client
      description: >-
        Crée un accès d'une heure à l'espace client d'un de vos abonnés.
        Redirigez-le tout de suite vers `url`, sans la stocker.
      operationId: createBillingPortalSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_email
              properties:
                customer_email:
                  type: string
                  description: >-
                    Adresse d'un client qui a au moins un abonnement dans cet
                    environnement
                  format: email
                  maxLength: 255
                return_url:
                  type: string
                  description: >-
                    Votre page, affichée en lien « Retour vers » suivi du nom de
                    votre boutique
                  format: uri
                  maxLength: 2048
            example:
              customer_email: awa@example.com
              return_url: https://boutique.example.com/mon-compte
      responses:
        '201':
          description: Accès créé
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: Adresse de l'espace client, valable une heure
                    format: uri
                  expires_at:
                    type: string
                    description: Fin de validité
                    format: date-time
              example:
                url: >-
                  https://mercy-pay.com/facturation/Xk9pL2mQ7vR4sT8wY1zA3bC6dE0fG5hJ2kL7mN4pQ9rS1tU
                expires_at: '2026-11-07T11:00:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Espace client désactivé dans vos Paramètres
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: authentication_error
                  code: forbidden
                  message: L'espace client est désactivé pour ce compte.
                  param: null
                  doc_url: https://docs.mercy-pay.com/developers/errors#forbidden
                  request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
        '404':
          description: Aucun abonnement pour cette adresse dans cet environnement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: invalid_request_error
                  code: resource_not_found
                  message: Aucun abonnement pour ce client.
                  param: null
                  doc_url: >-
                    https://docs.mercy-pay.com/developers/errors#resource_not_found
                  request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  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
    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
  schemas:
    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
  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.