SDK Java

Le SDK Java de Papi (papi-api-client) fournit un client typé pour l'API de paiement Papi. Il gère la communication HTTP, la sérialisation et les classes de modèles afin que vous puissiez vous concentrer sur votre logique métier.

Installation

Le SDK est hébergé sur le dépôt de paquets Ibonia. Ajoutez le dépôt et la dépendance à votre projet.

Maven

<repositories>
  <repository>
    <id>ibonia-repo-group</id>
    <url>https://package-repository.ibonia.com/repository/ibonia-mvn-group</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.ibonia.papi</groupId>
    <artifactId>papi-api-client</artifactId>
    <version>1.0.2</version>
  </dependency>
</dependencies>

Gradle

repositories {
    maven { url 'https://package-repository.ibonia.com/repository/ibonia-mvn-group' }
}

dependencies {
    implementation 'com.ibonia.papi:papi-api-client:1.0.2'
}

Classes principales

Classe	Package	Description
`ApiClient`	`com.ibonia.papi.apiclient`	Client HTTP de base. À instancier une seule fois et à partager.
`PaymentLinksApi`	`com.ibonia.papi.apiclient.api`	Méthodes pour créer des liens de paiement.
`PaymentLinkRequest`	`com.ibonia.papi.apiclient.model`	Corps de la requête pour créer un lien de paiement.
`PaymentLinkResponse`	`com.ibonia.papi.apiclient.model`	Réponse retournée après la création d'un lien de paiement.
`PaymentResponse`	`com.ibonia.papi.apiclient.model`	Charge envoyée par Papi à votre endpoint de notification.

Utilisation

Initialiser le client

Créez une instance ApiClient (elle est thread-safe) et passez-la à PaymentLinksApi. Dans une application Spring, faites-le dans le constructeur afin que l'instance API soit prête à l'utilisation dès la création du bean.

import com.ibonia.papi.apiclient.ApiClient;
import com.ibonia.papi.apiclient.api.PaymentLinksApi;

ApiClient apiClient = new ApiClient();
PaymentLinksApi paymentLinksApi = new PaymentLinksApi(apiClient);

Construire la requête de lien de paiement

Construisez un PaymentLinkRequest via le builder fluent. Les champs amount, description, clientName, reference et notificationUrl sont obligatoires.

import com.ibonia.papi.apiclient.model.PaymentLinkRequest;
import java.net.URI;

PaymentLinkRequest request = new PaymentLinkRequest()
        .amount(15000.0)
        .description("Paiement Commande #123")
        .clientName("Jean Dupont")
        .reference("ORDER-123")
        .payerEmail("jean.dupont@example.com")
        .payerPhone("+261340000000")
        .notificationUrl(new URI("https://votreapp.com/api/notifications-paiement"))
        .validDuration(60);   // le lien expire après 60 minutes

Créer le lien de paiement

Appelez createPaymentLink avec votre clé API (disponible dans le tableau de bord) et la requête. La méthode retourne un wrapper — appelez .getData() pour obtenir le PaymentLinkResponse.

import com.ibonia.papi.apiclient.model.PaymentLinkResponse;

PaymentLinkResponse response = paymentLinksApi
        .createPaymentLink("VOTRE_CLE_API", request)
        .getData();

String urlPaiement  = response.getPaymentLink();        // redirigez l'utilisateur ici
String notifToken   = response.getNotificationToken();  // stockez ceci pour la vérification

Redirigez le client vers urlPaiement. Après le paiement, Papi appellera votre notificationUrl avec le résultat.

Gérer la notification de paiement

Exposez un endpoint POST qui accepte un corps PaymentResponse. Papi appelle cet endpoint après chaque tentative de paiement.

import com.ibonia.papi.apiclient.model.PaymentResponse;

@PostMapping("/api/notifications-paiement")
public ResponseEntity<?> handleNotification(
        @RequestBody @Valid PaymentResponse notification) {

    // Vérifiez l'authenticité avant toute action
    boolean tokenOk = notifToken.equals(notification.getNotificationToken());
    boolean refOk   = "ORDER-123".equals(notification.getMerchantPaymentReference());

    if (!tokenOk || !refOk) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
    }

    switch (notification.getPaymentStatus()) {
        case SUCCESS -> handleSuccess(notification);
        case FAILED  -> handleFailure(notification);
        case PENDING -> handlePending(notification);
    }

    return ResponseEntity.ok().build();
}

Champs de `PaymentLinkRequest`

Champ	Type	Obligatoire	Description
`amount`	`double`	✓	Montant du paiement (minimum 300 MGA).
`clientName`	`String`	✓	Nom complet du client.
`reference`	`String`	✓	Votre identifiant unique pour ce paiement.
`description`	`String`	✓	Courte description du paiement (max 255 caractères).
`notificationUrl`	`URI`	✓	Endpoint qui reçoit les notifications de statut de paiement.
`payerEmail`	`String`	✗	Adresse e-mail du client.
`payerPhone`	`String`	✗	Numéro de téléphone du client.
`successUrl`	`URI`	✗	URL de redirection après un paiement réussi.
`failureUrl`	`URI`	✗	URL de redirection après un paiement échoué.
`validDuration`	`int`	✗	Durée de validité du lien en minutes (défaut : 1).
`provider`	`String`	✗	Restreindre à un fournisseur : `MVOLA`, `ARTEL_MONEY`, `ORANGE_MONEY`, `BRED`.
`isTestMode`	`boolean`	✗	`true` pour marquer la transaction comme test dans le tableau de bord.
`testReason`	`String`	✗	Raison affichée dans le tableau de bord lorsque le mode test est activé.

Champs de `PaymentResponse`

Champ	Getter	Description
`paymentStatus`	`getPaymentStatus()`	`SUCCESS`, `FAILED` ou `PENDING`.
`paymentMethod`	`getPaymentMethod()`	Fournisseur utilisé : `MVOLA`, `ARTEL_MONEY`, `ORANGE_MONEY`, `BRED`.
`currency`	`getCurrency()`	Toujours `MGA`.
`amount`	`getAmount()`	Montant payé.
`fee`	`getFee()`	Frais de transaction déduits.
`clientName`	`getClientName()`	Nom du client.
`description`	`getDescription()`	Description du paiement.
`merchantPaymentReference`	`getMerchantPaymentReference()`	Référence interne du fournisseur de paiement.
`notificationToken`	`getNotificationToken()`	Token de la réponse initiale du lien — utilisé pour vérifier l'authenticité.
`paymentReference`	`getPaymentReference()`	Votre `reference` de la requête initiale.
`payerEmail`	`getPayerEmail()`	E-mail du client (si fourni).
`payerPhone`	`getPayerPhone()`	Téléphone du client (si fourni).

Exemple complet (Spring Boot)

L'exemple ci-dessous illustre un service Spring Boot complet qui crée un lien de paiement et gère la notification de callback — le même schéma utilisé en production.

import com.ibonia.papi.apiclient.ApiClient;
import com.ibonia.papi.apiclient.api.PaymentLinksApi;
import com.ibonia.papi.apiclient.model.PaymentLinkRequest;
import com.ibonia.papi.apiclient.model.PaymentLinkResponse;
import com.ibonia.papi.apiclient.model.PaymentResponse;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import java.net.URI;

@Service
public class PaymentService {

    private final PaymentLinksApi paymentLinksApi;

    @Value("${app.domain}")
    private String appDomain;

    public PaymentService() {
        this.paymentLinksApi = new PaymentLinksApi(new ApiClient());
    }

    public String createPaymentLink(String apiKey, double amount,
                                    String reference, String customerName,
                                    String email, String phone) throws Exception {
        PaymentLinkRequest request = new PaymentLinkRequest()
                .amount(amount)
                .description("Paiement " + reference)
                .clientName(customerName)
                .reference(reference)
                .payerEmail(email)
                .payerPhone(phone)
                .notificationUrl(new URI(appDomain + "/api/notifications-paiement"))
                .validDuration(60);

        PaymentLinkResponse response = paymentLinksApi
                .createPaymentLink(apiKey, request)
                .getData();

        // Persistez response.getNotificationToken() avec la référence de commande
        // pour pouvoir le vérifier lors de la réception de la notification.

        return response.getPaymentLink();
    }

    public void handleNotification(PaymentResponse notification) {
        String storedToken = lookupNotificationToken(
                notification.getMerchantPaymentReference());

        if (!storedToken.equals(notification.getNotificationToken())) {
            throw new SecurityException("Token de notification invalide");
        }

        if (notification.getPaymentStatus() == PaymentResponse.PaymentStatusEnum.SUCCESS) {
            confirmOrder(notification.getMerchantPaymentReference());
        }
    }

    // ... implémentations de lookupNotificationToken et confirmOrder
}

Installation​

Maven​

Gradle​

Classes principales​

Utilisation​

Champs de PaymentLinkRequest​

Champs de PaymentResponse​

Exemple complet (Spring Boot)​