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

# Créer un lien de paiement

> Crée une intention de paiement et renvoie soit une **URL de page de paiement hébergée**,
soit un **QR code** (`isQrCode: true`). Le lien expire au bout de **24 heures**.

Une fois le client redirigé vers `paymentUrl`, il choisit son opérateur, saisit son numéro
et confirme sur son téléphone. Vous êtes ensuite notifié par [webhook](/guides/webhooks)
et le client est redirigé vers `return_url` ou `cancel_url`.


<Tip>
  Conservez `paymentLink.reference` avec votre commande **avant** de rediriger le client. Guides : [Lien de paiement](/guides/lien-de-paiement) · [QR code](/guides/qr-code).
</Tip>


## OpenAPI

````yaml POST /web-merchant/create-web-payment-link
openapi: 3.1.0
info:
  title: Djonanko Pay API
  version: 1.0.0
  description: >
    API de la passerelle de paiement mobile money **Djonanko Pay**.


    Deux modes d'authentification coexistent :


    - **Clé API** (`x-api-key` + `x-api-secret`) — pour l'intégration serveur à
    serveur :
      création de liens de paiement et de QR codes.
    - **Jeton marchand** (`authenticationtoken`) — un JWT obtenu via `POST
    /user/login-merchant`,
      utilisé par le dashboard marchand pour tout le reste (statut, solde, reversements, rapports…).

    Toutes les réponses sont en JSON. Les montants sont exprimés en **FCFA (XOF
    / XAF)** sans décimales.
  contact:
    name: Support Djonanko
    url: https://www.djonanko.ci/#contact
servers:
  - url: https://apidjonanko.tech
    description: Production
security: []
tags:
  - name: Authentification
  - name: Paiements
  - name: Solde & statistiques
  - name: Webhooks
  - name: Reversements
  - name: Sécurité
  - name: Rapports
  - name: Compte marchand
paths:
  /web-merchant/create-web-payment-link:
    post:
      tags:
        - Paiements
      summary: Créer un lien de paiement
      description: >
        Crée une intention de paiement et renvoie soit une **URL de page de
        paiement hébergée**,

        soit un **QR code** (`isQrCode: true`). Le lien expire au bout de **24
        heures**.


        Une fois le client redirigé vers `paymentUrl`, il choisit son opérateur,
        saisit son numéro

        et confirme sur son téléphone. Vous êtes ensuite notifié par
        [webhook](/guides/webhooks)

        et le client est redirigé vers `return_url` ou `cancel_url`.
      operationId: createWebPaymentLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkRequest'
            examples:
              lien:
                summary: Lien de paiement
                value:
                  amount: 5000
                  merchant_reference: beautyshop
                  return_url: https://example.com/success
                  cancel_url: https://example.com/cancel
                  metadata:
                    order_id: CMD-2026-00042
                    email: client@example.com
                    phoneNumber: '+2250700000000'
              qrcode:
                summary: QR code
                value:
                  amount: 5000
                  merchant_reference: beautyshop
                  isQrCode: true
                  return_url: https://example.com/success
                  cancel_url: https://example.com/cancel
                  metadata:
                    order_id: CMD-2026-00042
      responses:
        '201':
          description: Lien créé.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentLinkResponse'
              examples:
                lien:
                  summary: Lien de paiement
                  value:
                    success: true
                    paymentLink:
                      id: 50f668cf-2a84-41e7-9bcb-6874b0d5d286
                      message: Payment link created successfully
                      paymentUrl: https://checkout.djonanko.ci/PAYR9PVUYEWVF
                      reference: PAYR9PVUYEWVF
                qrcode:
                  summary: QR code
                  value:
                    success: true
                    paymentLink:
                      id: 50f668cf-2a84-41e7-9bcb-6874b0d5d286
                      message: Payment link created successfully
                      qrcode: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…
                      reference: PAYR9PVUYEWVF
        '400':
          description: Montant invalide (doit être > 100) ou URL manquante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message: Amount must be greater than 100
                error: Bad Request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Compte marchand désactivé.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 403
                message: Merchant account is not active
                error: Forbidden
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKey: []
          ApiSecret: []
components:
  schemas:
    CreatePaymentLinkRequest:
      type: object
      required:
        - amount
        - merchant_reference
        - return_url
        - cancel_url
      properties:
        amount:
          type: integer
          minimum: 101
          description: >-
            Montant à encaisser en FCFA. Doit être **strictement supérieur à
            100**.
          example: 5000
        merchant_reference:
          type: string
          description: Référence de votre compte marchand.
          example: beautyshop
        return_url:
          type: string
          format: uri
          description: URL vers laquelle le client est redirigé après un paiement réussi.
          example: https://example.com/success
        cancel_url:
          type: string
          format: uri
          description: >-
            URL vers laquelle le client est redirigé après un échec ou une
            annulation.
          example: https://example.com/cancel
        isQrCode:
          type: boolean
          default: false
          description: >-
            Si `true`, la réponse contient un QR code (image PNG encodée en data
            URL) au lieu de l'URL de paiement.
          example: false
        metadata:
          $ref: '#/components/schemas/Metadata'
    CreatePaymentLinkResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        paymentLink:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Identifiant interne du lien.
              example: 50f668cf-2a84-41e7-9bcb-6874b0d5d286
            message:
              type: string
              example: Payment link created successfully
            reference:
              type: string
              description: >-
                Référence du paiement (préfixe `PAY`). Conservez-la, c'est la
                clé pour interroger le statut et rapprocher le webhook.
              example: PAYR9PVUYEWVF
            paymentUrl:
              type: string
              format: uri
              description: >-
                URL de la page de paiement hébergée. Présente uniquement si
                `isQrCode` est `false`.
              example: https://checkout.djonanko.ci/PAYR9PVUYEWVF
            qrcode:
              type: string
              description: >-
                Image PNG du QR code encodée en data URL
                (`data:image/png;base64,…`). Présente uniquement si `isQrCode`
                est `true`.
              example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 401
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Invalid API credentials
        error:
          type: string
          example: Unauthorized
    Metadata:
      type: object
      description: >-
        Données libres que vous souhaitez retrouver dans le webhook et dans la
        liste des transactions.
      properties:
        order_id:
          type: string
          description: >-
            Identifiant de la commande dans votre système. Il est aussi utilisé
            comme "référence marchand" dans le dashboard et les exports.
          example: CMD-2026-00042
        email:
          type: string
          description: Email du client.
          example: client@example.com
        phoneNumber:
          type: string
          description: Numéro du client (format international recommandé).
          example: '+2250700000000'
  responses:
    Unauthorized:
      description: Identifiants manquants ou invalides.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            message: Invalid API credentials
            error: Unauthorized
    NotFound:
      description: Ressource introuvable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            message: Merchant not found
            error: Not Found
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Votre clé API publique (préfixe `DJN-`). Visible dans l'espace
        Développeur du dashboard.
    ApiSecret:
      type: apiKey
      in: header
      name: x-api-secret
      description: >-
        Votre secret API (64 caractères hexadécimaux). Communiqué une seule fois
        par SMS à la création du compte ou à la régénération.

````