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

> Envoie des fonds depuis votre solde marchand vers un bénéficiaire mobile money

<Warning>
  **Whitelist IP obligatoire pour une clé API.** Si aucune IP n'est whitelistée pour votre marchand, cet appel échoue avec `403 ip_not_whitelisted`, quelle que soit la validité de votre clé. Ajoutez l'IP de votre serveur depuis votre tableau de bord ou l'API de gestion du marchand avant votre premier appel. Ce prérequis ne s'applique pas à un appel authentifié via le dashboard (JWT).
</Warning>

<Note>
  Contrairement à l'encaissement, le mismatch entre `currency` et `country` est ici **rejeté** (`422 currency_country_mismatch`), sans conversion automatique.
</Note>


## OpenAPI

````yaml api-reference/openapi.json POST /payouts/initialize/
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:
  /payouts/initialize/:
    post:
      tags:
        - Retraits
      summary: Initier un payout
      description: >-
        Envoie des fonds depuis votre solde marchand vers un bénéficiaire mobile
        money. Nécessite un scope de clé API `PAYOUT` ou `BOTH`, un header
        `Idempotency-Key`, et — pour un appel authentifié par clé API — une IP
        whitelistée pour ce marchand.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - country
                - customer
                - method
                - recipient
              properties:
                merchant:
                  type: string
                  format: uuid
                  description: >-
                    UUID du marchand visé. Ignoré pour une clé API (toujours
                    vous-même).
                amount:
                  type: string
                  format: decimal
                  example: '10000.00'
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                  example: XAF
                country:
                  type: string
                  minLength: 2
                  maxLength: 2
                  example: CM
                description:
                  type: string
                  example: 'Remboursement commande #778'
                customer:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                    first_name:
                      type: string
                    last_name:
                      type: string
                    phone:
                      type: string
                      description: 'Format international, ex: +22997505050'
                method:
                  type: string
                  description: Code réseau du bénéficiaire
                  example: mtn_cm
                recipient:
                  type: object
                  required:
                    - msisdn
                  properties:
                    msisdn:
                      type: string
                      example: '677889900'
                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
            example:
              amount: '10000.00'
              currency: XAF
              country: CM
              customer:
                phone: '+237677889900'
              method: mtn_cm
              recipient:
                msisdn: '677889900'
              description: 'Remboursement commande #778'
      responses:
        '201':
          description: Payout initialisé
          content:
            application/json:
              example:
                message: Payout transaction initialized successfully
                id: a4b5c6d7-e8f9-4a0b-8c1d-2e3f4a5b6c7d
        '403':
          description: >-
            `payout_not_enabled` (fonctionnalité désactivée pour ce marchand),
            `ip_not_whitelisted` (aucune IP whitelistée pour ce marchand) ou
            scope de clé API insuffisant.
          content:
            application/json:
              example:
                message: >-
                  IP non autorisée pour les payouts — ajoutez l'IP de votre
                  serveur à la whitelist IP de votre marchand.
                code: ip_not_whitelisted
        '422':
          description: >-
            Requête valide mais impossible à router. Codes possibles :
            `currency_country_mismatch` (aucune conversion automatique côté
            payout, contrairement au payin), `invalid_country`,
            `invalid_customer`, `invalid_method`, `no_route_available`,
            `wallet_frozen`.
          content:
            application/json:
              example:
                message: La devise XOF ne correspond pas au pays CM.
                code: currency_country_mismatch
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).

````