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

# Initier un paiement softpay

> Push direct d'une demande de paiement sur le téléphone du client

<Note>
  `checkout_url` est vide (`""`) dans l'immense majorité des cas — softpay pousse directement la demande de paiement, sans redirection. Une valeur non vide n'apparaît que si le réseau/gateway choisi retombe exceptionnellement sur un flux de redirection.
</Note>


## OpenAPI

````yaml api-reference/openapi.json POST /payments/softpay/
openapi: 3.1.0
info:
  title: SasPay 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.saspay.me/api/v1
security:
  - bearerAuth: []
paths:
  /payments/softpay/:
    post:
      tags:
        - Paiements
      summary: Initier un paiement softpay
      description: >-
        Pousse directement une demande de paiement sur le téléphone du client
        (USSD/notification), sans page de redirection. Nécessite un scope de clé
        API `PAYIN` ou `BOTH`. Header `Idempotency-Key` requis.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - country
                - customer
                - network
              properties:
                merchant:
                  type: string
                  format: uuid
                  description: >-
                    UUID du marchand visé. Ignoré pour une clé API (toujours
                    vous-même) ; pour un token dashboard gérant plusieurs
                    marchands, résout la boutique visée si le header
                    X-Merchant-Id n'est pas fourni.
                amount:
                  type: string
                  format: decimal
                  example: '2500.00'
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                  example: XOF
                country:
                  type: string
                  minLength: 2
                  maxLength: 2
                  example: BJ
                description:
                  type: string
                  example: Abonnement mensuel
                customer:
                  type: object
                  required:
                    - email
                    - first_name
                    - last_name
                    - phone
                  properties:
                    email:
                      type: string
                      format: email
                      example: client@example.com
                    first_name:
                      type: string
                      example: Awa
                    last_name:
                      type: string
                      example: Sossou
                    phone:
                      type: string
                      example: '+22997505050'
                network:
                  type: string
                  description: Code réseau, cf. référentiel pays/réseaux
                  example: mtn_bj
                metadata:
                  type: object
                  additionalProperties: true
                fee_charge_mode:
                  type: string
                  enum:
                    - ADD_ON
                    - DEDUCTED
                  nullable: true
                  description: >-
                    ADD_ON : les frais s'ajoutent au montant débité au client.
                    DEDUCTED : les frais sont déduits du montant net reversé au
                    marchand. Défaut : configuration du marchand.
                preferred_gateway:
                  type: string
                  description: >-
                    Code gateway à privilégier si plusieurs sont éligibles pour
                    ce réseau
            example:
              amount: '2500.00'
              currency: XOF
              country: BJ
              description: Abonnement mensuel
              customer:
                email: client@example.com
                first_name: Awa
                last_name: Sossou
                phone: '+22997505050'
              network: mtn_bj
      responses:
        '201':
          description: Paiement poussé avec succès
          content:
            application/json:
              example:
                message: Payment pushed successfully
                id: 9c3f2a10-4b7e-4f1a-9d2e-9b6a7c1e4a02
                status: PENDING
                checkout_url: ''
        '403':
          description: Scope de clé API insuffisant (PAYIN requis)
          content:
            application/json:
              example:
                message: >-
                  Cette clé API n'est pas autorisée pour les opérations payin
                  (scope actuel : Payout).
                code: api_key_scope_forbidden
        '422':
          description: >-
            Requête valide mais impossible à router. Codes possibles :
            `missing_method`, `invalid_country`, `no_exchange_rate`,
            `invalid_customer`, `invalid_method`, `no_route_available`.
          content:
            application/json:
              example:
                message: 'Réseau inconnu ou inactif : ''mtn_xx''.'
                code: invalid_method
components:
  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).

````