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

# Créer un transfert interwallet

> Déplace des fonds entre deux de vos wallets (pays différents), avec conversion automatique

<Warning>
  Le header `Idempotency-Key` est **requis** — un double-clic/retry réseau sans elle réserverait deux fois le montant sur le wallet source.
</Warning>

<Note>
  Un seul transfert `PENDING` est autorisé à la fois par marchand. Le wallet source doit ne pas être gelé (le wallet destination, lui, reste toujours créditable même gelé). Selon votre configuration, la réponse peut revenir directement en `COMPLETED` (auto-approbation activée par un administrateur) ou rester `PENDING` jusqu'à validation. Erreurs possibles, toutes en `422` : `same_country`, `transfer_already_pending`, `wallet_frozen`, `insufficient_balance`, `no_exchange_rate`.
</Note>


## OpenAPI

````yaml api-reference/openapi.json POST /wallet-transfers/
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:
  /wallet-transfers/:
    post:
      tags:
        - Wallet
      summary: Créer un transfert interwallet
      description: >-
        Nécessite un header Idempotency-Key. Un seul transfert PENDING autorisé
        à la fois par marchand. Conversion de devise automatique via le taux de
        change en vigueur.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: Valeur unique par tentative logique de transfert.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from_country:
                  type: string
                  description: Code ISO2, ex BJ
                to_country:
                  type: string
                  description: Code ISO2, ex CM
                from_amount:
                  type: string
                  format: decimal
              required:
                - from_country
                - to_country
                - from_amount
            example:
              from_country: BJ
              to_country: CM
              from_amount: '100000.00'
      responses:
        '201':
          description: Transfert créé (PENDING ou COMPLETED si auto-approuvé)
          content:
            application/json:
              example:
                id: 1a2b3c4d-1111-2222-3333-444455556666
                reference: f4e5d6c7-3333-4444-5555-666677778888
                merchant: 8a1f5c3e-0000-1111-2222-333344445555
                requested_by_member: null
                from_country: BJ
                to_country: CM
                from_amount: '100000.00'
                from_currency: XOF
                to_amount: '984.00'
                to_currency: XAF
                exchange_rate: '0.00984000'
                status: PENDING
                approved_by_admin: null
                approved_at: null
                completed_at: null
                rejection_reason: null
                created_at: '2026-08-12T10:10:00Z'
                updated_at: '2026-08-12T10:10:00Z'
        '422':
          description: >-
            Erreur métier — same_country, transfer_already_pending,
            wallet_frozen, insufficient_balance ou no_exchange_rate
          content:
            application/json:
              example:
                message: >-
                  Un transfert interwallet est déjà en attente pour ce marchand
                  — attendez sa résolution avant d'en demander un autre.
                code: transfer_already_pending
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).

````