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

# Créer un payout

> Initier un décaissement (Mobile Money, Virement Bancaire, SWIFT)

Crée un payout (décaissement) pour envoyer de l'argent vers un compte Mobile Money ou bancaire.

<Tip>
  **Flux recommandé :** Obtenez d'abord un devis avec `POST /payouts/quote`, puis confirmez avec `POST /payouts/initiate` en passant le `quoteId`. Le marchand sait exactement combien sera débité avant de confirmer.
</Tip>

### Authentification

```bash theme={null}
X-API-Key: pk_test_xxx:sk_test_xxx
```

## Avec un devis (recommandé)

Quand `quoteId` est fourni, les montants, taux, frais et méthode sont verrouillés. Seuls les détails du bénéficiaire sont requis.

### Mobile Money (avec quote)

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payouts/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QT-MOBILE-001",
    "externalReference": "PAY-2024-001",
    "recipient": {
      "phone": "+221771234567",
      "firstName": "Amadou",
      "lastName": "Diallo"
    },
    "description": "Paiement fournisseur"
  }'
```

```json 201 - Réponse theme={null}
{
  "transactionId": "POMLWYG1W59FDCEA",
  "externalReference": "PAY-2024-001",
  "status": "pending",
  "amount": 50000,
  "currency": "XOF",
  "fees": 750,
  "netAmount": 49250,
  "method": "mobile_money",
  "recipient": {
    "name": "Amadou Diallo",
    "firstName": "Amadou",
    "lastName": "Diallo",
    "phone": "+221771234567"
  },
  "mobileWallet": {
    "provider": "wave"
  },
  "createdAt": "2024-01-15T14:00:00.000Z",
  "updatedAt": "2024-01-15T14:00:00.000Z"
}
```

### Virement Bancaire Local (avec quote)

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payouts/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QT-BANK-001",
    "externalReference": "PAY-2024-002",
    "recipient": {
      "name": "SARL Mon Entreprise",
      "email": "finance@monentreprise.sn"
    },
    "bankAccount": {
      "bankName": "BICIS",
      "bankCode": "SN048",
      "accountNumber": "SN08SN000101015000001234567",
      "accountName": "SARL Mon Entreprise",
      "swiftBic": "BICISNDAXXX"
    },
    "description": "Virement mensuel"
  }'
```

```json 201 - Réponse theme={null}
{
  "transactionId": "POMLWYG2X6AGDCEB",
  "externalReference": "PAY-2024-002",
  "status": "pending",
  "amount": 500000,
  "currency": "XOF",
  "fees": 2500,
  "netAmount": 497500,
  "method": "bank_transfer",
  "recipient": {
    "name": "SARL Mon Entreprise",
    "email": "finance@monentreprise.sn"
  },
  "bankAccount": {
    "bankName": "BICIS",
    "bankCode": "SN048",
    "accountNumber": "SN08SN000101015000001234567",
    "accountName": "SARL Mon Entreprise",
    "swiftBic": "BICISNDAXXX"
  },
  "createdAt": "2024-01-15T14:30:00.000Z",
  "updatedAt": "2024-01-15T14:30:00.000Z"
}
```

### International C2C (avec quote)

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payouts/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QT-A1B2C3D4E5F6",
    "externalReference": "PAY-C2C-2024-001",
    "purpose": "family_support",
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+447911123456",
      "email": "john@email.com",
      "address": "123 High Street, London",
      "dateOfBirth": "1985-06-15",
      "nationality": "GB",
      "sourceOfIncome": "salary",
      "relationWithRecipient": "family",
      "identity": {
        "type": "passport",
        "number": "GB123456789",
        "issuingCountry": "GB",
        "issueDate": "2018-01-01",
        "expiryDate": "2028-01-01"
      }
    },
    "recipient": {
      "firstName": "Raj",
      "lastName": "Kumar",
      "phone": "+919876543210",
      "nationality": "IN",
      "address": {
        "line1": "456 MG Road",
        "city": "Mumbai",
        "postalCode": "400001",
        "country": "IN"
      }
    },
    "bankAccount": {
      "bankName": "HDFC BANK",
      "bankCode": "HDFC0001234",
      "accountNumber": "12345678901234",
      "accountName": "Raj Kumar"
    },
    "description": "Transfert familial"
  }'
```

```json 201 - Réponse theme={null}
{
  "transactionId": "POMNIY89ABC1D234",
  "externalReference": "PAY-C2C-2024-001",
  "status": "pending",
  "amount": 500,
  "currency": "USD",
  "fees": 10,
  "netAmount": 490,
  "method": "bank_transfer",
  "recipient": {
    "name": "Raj Kumar",
    "firstName": "Raj",
    "lastName": "Kumar",
    "phone": "+919876543210"
  },
  "bankAccount": {
    "bankName": "HDFC BANK",
    "bankCode": "HDFC0001234",
    "accountNumber": "12345678901234",
    "accountName": "Raj Kumar"
  },
  "international": {
    "destinationCountry": "IN",
    "destinationCurrency": "INR",
    "destinationAmount": 42170,
    "fxRate": 84.34,
    "purpose": "family_support"
  },
  "createdAt": "2026-04-03T14:00:00.000Z",
  "updatedAt": "2026-04-03T14:00:00.000Z"
}
```

### B2B SWIFT (avec quote)

<Warning>
  Le champ `sender.company` est **requis** pour les transferts B2B.
</Warning>

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payouts/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QT-B2B-001",
    "externalReference": "PAY-B2B-001",
    "purpose": "trade_payment",
    "sender": {
      "firstName": "Amadou",
      "lastName": "Diallo",
      "email": "amadou@cauris.com",
      "phone": "+221770001234",
      "address": "Dakar, Sénégal",
      "nationality": "SN",
      "dateOfBirth": "1980-05-20",
      "identity": {
        "type": "passport",
        "number": "A12345678",
        "issuingCountry": "SN",
        "issueDate": "2020-01-01",
        "expiryDate": "2030-01-01"
      },
      "company": {
        "name": "Cauris Technologies SARL",
        "legalForm": "LLC",
        "businessType": "Trading",
        "countryOfTrade": "SN",
        "currencies": ["USD", "EUR"]
      }
    },
    "recipient": {
      "name": "TechCorp GmbH",
      "email": "finance@techcorp.de",
      "nationality": "DE",
      "address": {
        "line1": "Friedrichstraße 100",
        "city": "Berlin",
        "postalCode": "10117",
        "country": "DE"
      }
    },
    "bankAccount": {
      "bankName": "Deutsche Bank",
      "accountNumber": "DE89370400440532013000",
      "accountName": "TechCorp GmbH",
      "swiftBic": "DEUTDEFFXXX",
      "bankBranch": "Berlin Main",
      "bankAddress": "Taunusanlage 12, 60325 Frankfurt"
    },
    "correspondentBank": {
      "bankName": "JPMorgan Chase",
      "swiftBic": "CHASUS33XXX",
      "accountNumber": "400-123-456"
    },
    "description": "Paiement fournisseur Q1 2024"
  }'
```

```json 201 - Réponse theme={null}
{
  "transactionId": "POMLWYG5A9DJGFHI",
  "externalReference": "PAY-B2B-001",
  "status": "pending",
  "amount": 5000,
  "currency": "USD",
  "fees": 15000,
  "netAmount": 4975,
  "method": "bank_transfer",
  "recipient": {
    "name": "TechCorp GmbH",
    "email": "finance@techcorp.de"
  },
  "bankAccount": {
    "bankName": "Deutsche Bank",
    "accountNumber": "DE89370400440532013000",
    "accountName": "TechCorp GmbH",
    "swiftBic": "DEUTDEFFXXX",
    "bankBranch": "Berlin Main",
    "bankAddress": "Taunusanlage 12, Frankfurt"
  },
  "correspondentBank": {
    "bankName": "JPMorgan Chase",
    "swiftBic": "CHASUS33XXX",
    "accountNumber": "400-123-456"
  },
  "international": {
    "destinationCountry": "DE",
    "destinationCurrency": "EUR",
    "destinationAmount": 4580,
    "fxRate": 0.916
  },
  "createdAt": "2024-01-15T16:30:00.000Z",
  "updatedAt": "2024-01-15T16:30:00.000Z"
}
```

## Sans devis (legacy)

Vous pouvez aussi créer un payout sans devis en spécifiant tous les paramètres directement.

```bash theme={null}
curl -X POST https://sandbox-api.caurisflux.com/api/v1/payouts/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "PAY-2024-001",
    "amount": 50000,
    "country": "SN",
    "currency": "XOF",
    "method": "MOBILE_MONEY",
    "recipient": {
      "phone": "+221771234567",
      "firstName": "Amadou",
      "lastName": "Diallo"
    },
    "mobileWallet": {
      "provider": "wave"
    },
    "description": "Paiement fournisseur"
  }'
```

## Paramètres

### Avec quote (recommandé)

| Champ               | Type   | Requis        | Description                                  |
| ------------------- | ------ | ------------- | -------------------------------------------- |
| `quoteId`           | string | Oui           | ID du devis obtenu via `POST /payouts/quote` |
| `externalReference` | string | Non           | Votre référence unique                       |
| `purpose`           | string | International | Motif du transfert                           |
| `sender`            | object | International | Informations sur l'expéditeur                |
| `recipient`         | object | Oui           | Informations sur le bénéficiaire             |
| `bankAccount`       | object | Virement      | Coordonnées bancaires                        |
| `correspondentBank` | object | SWIFT         | Banque correspondante                        |
| `description`       | string | Non           | Commentaire                                  |

### Sans quote

| Champ               | Type   | Requis | Description                       |
| ------------------- | ------ | ------ | --------------------------------- |
| `amount`            | number | Oui    | Montant du payout                 |
| `method`            | string | Oui    | `MOBILE_MONEY` ou `BANK_TRANSFER` |
| `country`           | string | Non    | Code ISO du pays (défaut: SN)     |
| `currency`          | string | Non    | Devise (défaut: XOF)              |
| `externalReference` | string | Non    | Votre référence unique            |
| `callbackUrl`       | string | Non    | URL de callback                   |
| `metadata`          | object | Non    | Données personnalisées            |

### Objet `sender` (international/B2B)

| Champ                   | Type   | Requis | Description                    |
| ----------------------- | ------ | ------ | ------------------------------ |
| `firstName`             | string | Oui    | Prénom                         |
| `lastName`              | string | Oui    | Nom                            |
| `phone`                 | string | Non    | Numéro de téléphone            |
| `email`                 | string | Non    | Email                          |
| `address`               | string | Oui    | Adresse                        |
| `dateOfBirth`           | string | Oui    | Date de naissance (YYYY-MM-DD) |
| `nationality`           | string | Oui    | Code ISO du pays               |
| `sourceOfIncome`        | string | Non    | Source de revenus              |
| `relationWithRecipient` | string | Non    | Relation avec le bénéficiaire  |
| `identity`              | object | Oui    | Pièce d'identité               |
| `company`               | object | B2B    | Informations entreprise        |

### Objet `sender.identity`

| Champ            | Type   | Requis | Description                                  |
| ---------------- | ------ | ------ | -------------------------------------------- |
| `type`           | string | Oui    | `passport`, `national_id`, `driving_license` |
| `number`         | string | Oui    | Numéro du document                           |
| `issuingCountry` | string | Oui    | Pays d'émission (ISO 2)                      |
| `issueDate`      | string | Oui    | Date d'émission (YYYY-MM-DD)                 |
| `expiryDate`     | string | Oui    | Date d'expiration (YYYY-MM-DD)               |

### Objet `sender.company` (B2B)

| Champ            | Type   | Requis | Description                        |
| ---------------- | ------ | ------ | ---------------------------------- |
| `name`           | string | Oui    | Raison sociale                     |
| `legalForm`      | string | Non    | Forme juridique (LLC, SA, SARL...) |
| `businessType`   | string | Non    | Secteur d'activité                 |
| `countryOfTrade` | string | Non    | Pays d'activité                    |
| `currencies`     | array  | Non    | Devises utilisées                  |

### Objet `recipient`

| Champ         | Type   | Requis             | Description                   |
| ------------- | ------ | ------------------ | ----------------------------- |
| `phone`       | string | Mobile Money       | Numéro (format E.164)         |
| `firstName`   | string | International      | Prénom                        |
| `lastName`    | string | International      | Nom                           |
| `name`        | string | Non                | Raison sociale ou nom complet |
| `email`       | string | Non                | Email                         |
| `nationality` | string | International      | Code ISO du pays              |
| `address`     | object | Certains corridors | Adresse structurée            |

### Objet `bankAccount`

| Champ           | Type   | Requis        | Description              |
| --------------- | ------ | ------------- | ------------------------ |
| `accountNumber` | string | Oui           | Numéro de compte ou IBAN |
| `swiftBic`      | string | International | Code SWIFT/BIC           |
| `bankName`      | string | SWIFT         | Nom de la banque         |
| `bankCode`      | string | Non           | Code de la banque        |
| `accountName`   | string | Non           | Nom du titulaire         |
| `bankBranch`    | string | SWIFT         | Agence/branche           |
| `bankAddress`   | string | SWIFT         | Adresse de la banque     |

### Objet `correspondentBank` (SWIFT, optionnel)

| Champ           | Type   | Requis | Description                     |
| --------------- | ------ | ------ | ------------------------------- |
| `bankName`      | string | Non    | Nom de la banque correspondante |
| `swiftBic`      | string | Non    | SWIFT/BIC correspondant         |
| `accountNumber` | string | Non    | Numéro de compte correspondant  |

## Providers Mobile Money

| Code           | Nom              |
| -------------- | ---------------- |
| `wave`         | Wave             |
| `orange_money` | Orange Money     |
| `mtn_money`    | MTN Mobile Money |
| `moov_money`   | Moov Money       |
| `free_money`   | Free Money       |

## Erreurs

| Code  | Message                 | Solution                                |
| ----- | ----------------------- | --------------------------------------- |
| `400` | Quote expiré            | Demandez un nouveau devis               |
| `400` | Corridor non supporté   | Vérifiez `/payouts/reference/corridors` |
| `400` | Purpose requis          | Ajoutez le champ `purpose`              |
| `400` | Solde insuffisant       | Rechargez votre compte                  |
| `400` | Limite dépassée         | Vérifiez `/payouts/limits`              |
| `400` | Company requis pour B2B | Ajoutez `sender.company`                |