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

# Démarrage rapide

> Encaissez votre premier paiement de test avec AlphaPay en moins de 5 minutes.

## 1. Obtenez votre clé API

Connectez-vous sur [app.alphapay.me](https://app.alphapay.me) et copiez votre clé API secrète depuis la section Développeur de votre tableau de bord.

```
Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx
```

Utilisez une clé `sk_test_...` pour tester sans argent réel, `sk_live_...` une fois prêt à encaisser en production.

## 2. Découvrez les pays et réseaux supportés

Avant d'initier un paiement, vérifiez quels réseaux mobile money sont disponibles dans le pays de votre client. Cet appel ne nécessite aucune authentification.

```bash theme={null}
curl https://api.alphapay.me/api/v1/countries/
```

Repérez le `code` du réseau qui vous intéresse (ex. `mtn_bj` pour MTN Bénin) via [Liste des réseaux](/api-reference/reference/networks).

## 3. Encaissez un paiement

Deux façons d'encaisser sont disponibles selon votre intégration.

<Tabs>
  <Tab title="Softpay (direct)">
    Poussez directement une demande de paiement sur le téléphone du client — idéal si vous avez déjà son numéro et son réseau.

    ```bash theme={null}
    curl -X POST https://api.alphapay.me/api/v1/payments/softpay/ \
      -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
      -d '{
        "amount": "2500.00",
        "currency": "XOF",
        "country": "BJ",
        "network": "mtn_bj",
        "description": "Abonnement mensuel",
        "customer": {
          "email": "client@example.com",
          "first_name": "Awa",
          "last_name": "Sossou",
          "phone": "+22997505050"
        }
      }'
    ```

    ```json Réponse theme={null}
    { "message": "Payment pushed successfully", "id": "b1f2c3d4-...", "status": "PENDING", "checkout_url": "" }
    ```

    <Warning>
      `checkout_url` est vide ici parce que MTN Bénin fonctionne en push. Sur Wave, Orange Money, Djamo ou une carte bancaire, elle sera **non vide** et vous devrez y rediriger votre client — sinon aucun paiement n'a lieu. Testez toujours ce champ.
    </Warning>

    <Note>
      Le header `Idempotency-Key` est optionnel, mais vivement recommandé ici : sans lui, un retry réseau crée un second paiement réel. Générez un identifiant unique (UUID par exemple) par tentative. Voir [Idempotence](/api-reference/introduction#idempotence).
    </Note>

    Le client reçoit l'invite de paiement directement sur son téléphone (USSD ou notification, selon le réseau). Suivez ensuite l'étape 4 pour connaître le résultat.
  </Tab>

  <Tab title="Checkout hébergé">
    Générez une page de paiement à laquelle rediriger votre client — idéal si vous ne voulez pas gérer l'interface de paiement vous-même.

    ```bash theme={null}
    curl -X POST https://api.alphapay.me/api/v1/checkout-sessions/ \
      -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "5000.00",
        "currency": "XOF",
        "description": "Facture #1042",
        "customer_email": "client@example.com",
        "customer_name": "Awa Sossou",
        "return_url": "https://votre-site.com/merci"
      }'
    ```

    ```json Réponse theme={null}
    { "id": "c9a1...", "slug": "kZ2v9rT4bQxL8mNpYw==", "checkout_url": "https://pay.alphapay.me/checkout/kZ2v9rT4bQxL8mNpYw==", "status": "PENDING" }
    ```

    Redirigez votre client vers `checkout_url` — il y choisit son réseau et confirme le paiement lui-même.

    <Warning>
      `return_url` est optionnel mais fortement recommandé : sans lui, votre client reste bloqué sur la page de succès AlphaPay après paiement, sans moyen de revenir chez vous. Si vous le fournissez, il est automatiquement redirigé vers cette URL 3 secondes après un paiement **réussi**. Ce n'est pas encore le cas sur un paiement échoué — dans ce cas le client voit un bouton "Réessayer" et doit fermer l'onglet lui-même.
    </Warning>
  </Tab>
</Tabs>

## 4. Vérifiez le résultat

Ne faites jamais confiance à un simple délai — interrogez toujours le statut réel avant de considérer un paiement comme réussi.

```bash theme={null}
curl https://api.alphapay.me/api/v1/payments/b1f2c3d4-.../verify/ \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx"
```

```json Réponse theme={null}
{ "message": "Payment transaction fetched successfully", "id": "b1f2c3d4-...", "status": "SUCCESS", "net_amount": "2500.00", "currency": "XOF" }
```

<Tip>
  Plutôt que d'interroger cet endpoint en boucle, configurez un [webhook](/api-reference/webhooks) pour être notifié en temps réel dès que le statut change.
</Tip>

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Paiements" icon="credit-card" href="/api-reference/payments">
    Softpay, checkout hébergé, retry, confirmation OTP
  </Card>

  <Card title="Retraits" icon="paper-plane" href="/api-reference/payouts">
    Payer un bénéficiaire en mobile money
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Recevez vos événements en temps réel
  </Card>

  <Card title="Créer un compte" icon="id-card" href="/account-setup">
    Inscription, KYC, première clé API
  </Card>
</CardGroup>