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

# Créer une session de checkout (widget embarqueable)



## OpenAPI

````yaml /openapi.json post /v1/checkout-sessions/
openapi: 3.1.0
info:
  title: KryptaPay API
  description: >-
    API B2B de paiements numériques pour l'Afrique francophone.


    ## Authentification

    Deux méthodes sont supportées :

    - **Session utilisateur** : JWT signé dans un cookie `kp_token` (HttpOnly,
    SameSite=Lax) — utilisé par le tableau de bord.

    - **Clé API** : header `Authorization: Bearer kp_<env>_xxx` — utilisé par
    les intégrations serveur.


    Les endpoints sensibles exigent l'une ou l'autre. Les écritures monétaires
    acceptent un header `Idempotency-Key` pour la dé-duplication.


    ## Enveloppe de réponse

    Toutes les réponses suivent le format `{ ok: boolean, data?: T, error?: {
    code, message, details? } }`.


    ## Webhooks sortants

    Signature HMAC SHA-256 dans le header `X-KryptaPay-Signature`. Le secret est
    défini à la création de l'endpoint.
  version: 1.0.0
  contact:
    name: KryptaPay Support
    email: support@kryptapay.test
    url: https://kryptapay.test
  license:
    name: Proprietary
servers:
  - url: http://localhost
    description: Local dev
security:
  - bearerAuth: []
  - cookieAuth: []
tags:
  - name: wallets
    description: Portefeuilles fiat / stablecoin / IBAN virtuels
  - name: transactions
    description: Historique unifié des mouvements
  - name: payouts
    description: Versements Mobile Money / banque / stablecoin
  - name: payins
    description: Encaissements et liens de paiement
  - name: fx
    description: Cotations et conversions multi-devises
  - name: counterparties
    description: Bénéficiaires et tiers
  - name: invoices
    description: Factures + paiement public + reçus
  - name: status
    description: Statut public des services
paths:
  /v1/checkout-sessions/:
    post:
      tags:
        - checkout-sessions
      summary: Créer une session de checkout (widget embarqueable)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amountFiat:
                  type: string
                  pattern: ^\d+(\.\d{1,8})?$
                  description: >-
                    Decimal amount with up to 8 fractional digits, e.g. "1500"
                    or "1500.75"
                currency:
                  type: string
                  enum:
                    - XOF
                    - XAF
                    - NGN
                    - GHS
                    - CDF
                    - EUR
                    - USD
                    - USDC
                    - USDT
                description:
                  type: string
                  maxLength: 500
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                      maxLength: 180
                    email:
                      type: string
                      format: email
                    msisdn:
                      type: string
                      maxLength: 20
                  additionalProperties: false
                webhookUrl:
                  type: string
                  format: uri
                successUrl:
                  type: string
                  format: uri
                cancelUrl:
                  type: string
                  format: uri
                allowedOrigins:
                  type: array
                  items:
                    type: string
                    format: uri
                  maxItems: 10
                expiresInSec:
                  type: integer
                  minimum: 60
                  maximum: 604800
                metadata:
                  type: object
                  additionalProperties: {}
              required:
                - amountFiat
                - currency
              additionalProperties: false
        required: true
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      token:
                        type: string
                      status:
                        type: string
                      embedUrl:
                        type: string
                      amountFiat:
                        type: string
                        pattern: ^\d+(\.\d{1,8})?$
                        description: >-
                          Decimal amount with up to 8 fractional digits, e.g.
                          "1500" or "1500.75"
                      currency:
                        type: string
                        enum:
                          - XOF
                          - XAF
                          - NGN
                          - GHS
                          - CDF
                          - EUR
                          - USD
                          - USDC
                          - USDT
                      expiresAt:
                        type: string
                      webhookSecret:
                        type: string
                        nullable: true
                    required:
                      - id
                      - token
                      - status
                      - embedUrl
                      - amountFiat
                      - currency
                      - expiresAt
                      - webhookSecret
                    additionalProperties: false
                required:
                  - ok
                  - data
                additionalProperties: false
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details: {}
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - ok
                  - error
                additionalProperties: false
                description: Authentication required
        '403':
          description: Forbidden — no org / role / KYB
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details: {}
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - ok
                  - error
                additionalProperties: false
                description: Forbidden — no org / role / KYB
        '422':
          description: Validation error or business-rule violation
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details: {}
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - ok
                  - error
                additionalProperties: false
                description: Validation error or business-rule violation
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT utilisateur ou clé API `kp_<env>_xxx`
    cookieAuth:
      type: apiKey
      in: cookie
      name: kp_token
      description: Session signée (front Next.js)

````