# lomi. Payment Elements
Source: https://docs.lomi.africa/build/accept/payment-elements

Acceptez les paiements dans votre application grâce à l’infrastructure de paiement en marque blanche lomi.

***

title: lomi. Payment Elements
description: Acceptez les paiements dans votre application grâce à l’infrastructure de paiement en marque blanche lomi.
-----------------------------------------------------------------------------------------------------------------------

import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from '@/components/docs/docs-callout';

lomi. Payment Elements permet d’encaisser par carte directement dans votre application, sans rediriger vers un tunnel hébergé. Vous gardez la maîtrise de l’expérience utilisateur tandis que lomi. prend en charge la complexité du traitement des paiements.

<Callout type="info">
  lomi. Payment Elements s’appuie sur une infrastructure sécurisée et conforme PCI. Vous ne manipulez jamais les données brutes de carte.
</Callout>

## Vue d’ensemble

Trois façons d’intégrer les paiements lomi. :

| Méthode                                     | Cas d’usage                                                           |
| ------------------------------------------- | --------------------------------------------------------------------- |
| **SDK JS (`@lomi/js`)**                     | Applications web en JavaScript vanilla ou framework                   |
| **SDK React Native (`@lomi/react-native`)** | Applications natives iOS et Android                                   |
| **Tunnel intégré (`@lomi./embed`)**         | Intégration en iframe conservant l’interface complète du tunnel lomi. |

***

<Callout type="info">
  Le navigateur utilise votre clé publique, `lomi_pk_test_…` ou `lomi_pk_live_…`. La clé secrète reste sur votre serveur. Le numéro de carte n’atteint jamais votre serveur ni l’API lomi.
</Callout>

## Apple Pay et Google Pay

La même page peut afficher Apple Pay et Google Pay au-dessus des champs carte. Ces boutons restent ceux d’Apple et de Google. `loadLomi` enregistre le domaine de la page. Vous n’avez pas à l’ajouter vous-même.

```javascript
import { loadLomi, mountLomiExpressCheckout, createLomiCardElements, mountLomiCardFields } from '@lomi./sdk';

const lomi = await loadLomi('lomi_pk_test_...');
mountLomiExpressCheckout(lomi, clientSecret, '#wallets');

const elements = createLomiCardElements(lomi);
mountLomiCardFields(elements, {
  number: '#card-number',
  expiry: '#card-expiry',
  cvc: '#card-cvc',
});
```

`clientSecret` vient de `POST /charge/card` avec la clé secrète. Apple Pay s’affiche dans Safari et Google Pay dans Chrome quand l’enregistrement du domaine est actif. Localhost est ignoré.

## Installation

<Tabs items={['Web (JS)', 'React Native', 'Tunnel intégré']}>
  <Tab value="Web (JS)">`bash npm install @lomi/js `</Tab>
  <Tab value="React Native">`bash npm install @lomi/react-native `</Tab>
  <Tab value="Tunnel intégré">`bash npm install @lomi./embed `</Tab>
</Tabs>

***

## Démarrage rapide

### 1. Obtenir vos clés API

Deux clés sont nécessaires dans le [Dashboard lomi.](https://lomi.africa/dashboard/settings/api-keys) :

* **Clé publique** (`lomi_pk_...`) : côté client pour initialiser le SDK
* **Clé secrète** (`lomi_sk_...`) : côté serveur pour créer les Payment Intents

<Callout type="warning">
  N’exposez jamais la clé secrète dans le code client.
</Callout>

### 2. Créer un Payment Intent (serveur)

Avant l’encaissement, créez un Payment Intent sur votre serveur :

```javascript
// Votre serveur (exemple Node.js)
const response = await fetch('https://api.lomi.africa/charge/card', {
  method: 'POST',
  headers: {
    'X-API-KEY': process.env.LOMI_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000, // Amount in smallest currency unit (e.g., 10000 XOF)
    currency_code: 'XOF',
    customer_email: 'customer@example.com',
  }),
});

const body = await response.json();
const clientSecret = body.data.client_secret;
// Pass clientSecret to your frontend
```

Détails : [Créer un encaissement carte](/api/charge/ChargesController_createCardCharge)

### 3. Encaisser le paiement (client)

<Tabs items={['Web (JS)', 'React Native', 'Tunnel intégré']}>
  <Tab value="Web (JS)">
    ```javascript
    import { loadLomi } from '@lomi/js';

    // Initialize Lomi
    const lomi = await loadLomi('lomi_pk_your_publishable_key');

    // Create payment elements
    const elements = lomi.elements({ clientSecret });
    const paymentElement = elements.create('payment');
    paymentElement.mount('#payment-element');

    // Handle form submission
    form.addEventListener('submit', async (e) => {
      e.preventDefault();

      const { error } = await lomi.confirmPayment({
        elements,
        confirmParams: {
          return_url: 'https://yoursite.com/success',
        },
      });

      if (error) {
        console.error(error.message);
      }
    });
    ```
  </Tab>

  <Tab value="React Native">
    ```tsx
    import { LomiProvider, LomiCardField, useLomi } from '@lomi/react-native';

    function App() {
      return (
        <LomiProvider publishableKey="lomi_pk_your_publishable_key">
          <PaymentScreen />
        </LomiProvider>
      );
    }

    function PaymentScreen() {
      const { confirmPayment } = useLomi();

      const handlePay = async () => {
        const { error } = await confirmPayment(clientSecret, {
          paymentMethodType: 'Card',
        });

        if (error) {
          console.error(error.message);
        }
      };

      return (
        <>
          <LomiCardField
            postalCodeEnabled={false}
            style={{ width: '100%', height: 50 }}
          />
          <Button title="Pay" onPress={handlePay} />
        </>
      );
    }
    ```
  </Tab>

  <Tab value="Tunnel intégré">
    Guide complet : [Tunnel de paiement intégré](/build/accept/embed-widget).

    ```javascript
    import { loadLomiCheckout } from '@lomi./embed';

    loadLomiCheckout({
      checkoutUrl: session.checkout_url,
      mode: 'modal',
      onComplete: (payload) => {
        console.log(payload.transactionId, payload.hasDigitalDeliverables);
      },
    });
    ```

    Pour un tunnel inline déclaratif, utilisez `data-lomi-checkout-url` sur un conteneur, puis chargez le bundle IIFE (`dist/lomi.js`) ou importez le package npm.
  </Tab>
</Tabs>

***

## Référence API

### Endpoint Payment Intent

```
POST https://api.lomi.africa/charge/card
```

| Paramètre        | Type   | Obligatoire | Description                                            |
| ---------------- | ------ | ----------- | ------------------------------------------------------ |
| `amount`         | number | Oui         | Montant dans la plus petite unité monétaire            |
| `currency_code`  | string | Non         | Code devise (XOF, EUR, USD). Valeur par défaut : `XOF` |
| `currency`       | string | Non         | Alias rétrocompatible de `currency_code`               |
| `customer_email` | string | Non         | Adresse e-mail du client                               |
| `customer_name`  | string | Non         | Nom complet du client                                  |
| `description`    | string | Non         | Libellé sur le reçu                                    |
| `metadata`       | object | Non         | Paires clé-valeur                                      |

**Réponse :**

```json
{
  "success": true,
  "data": {
    "id": "pi_abc123",
    "client_secret": "pi_abc123_secret_xyz",
    "amount": 152,
    "currency": "eur",
    "original_amount": 10000,
    "original_currency": "XOF",
    "status": "requires_payment_method"
  }
}
```

***

## Webhooks

Après un paiement réussi, lomi. envoie un webhook vers votre URL configurée :

```json
{
  "event": "PAYMENT_SUCCEEDED",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 10000,
    "currency": "XOF",
    "status": "completed",
    "metadata": {}
  }
}
```

Voir [Documentation Webhooks](/build/reliability).

***

## Tests

Utilisez les clés de test (`lomi_pk_test_...` et `lomi_sk_test_...`) avec `https://sandbox.api.lomi.africa` pour tester sans transaction réelle.

Pour les numéros de carte de test, le mobile money (Wave, MTN), la QA sur checkout hébergé et les soldes de test, voir **[Paiements en bac à sable](/start/sandbox-payments)**.