Plugins SoleasPay v4

Les plugins SoleasPay v4 sont concus pour integrer le paiement dans une application tierce sans gerer OAuth, JWT, intent, execute ou status cote marchand. Vous utilisez simplement votre apikey marchand SoleasPay. Le plugin se charge de charger les services disponibles, d’afficher l’interface de paiement, de collecter les informations client, de soumettre la transaction et de retourner le resultat.

Les plugins v4 sont distincts de l’API gateway serveur a serveur. Pour Checkout v4 et Button v4, l’integration se fait avec une API key, pas avec un access token OAuth.

Choisir le bon plugin

Plugin	Integration	Experience utilisateur
Checkout v4	Formulaire ou payload envoye vers `https://pay.soleaspay.com`	Page de paiement complete hebergee par SoleasPay
Button v4	Script JavaScript `https://btn.soleaspay.com/main.js`	Bouton de paiement integre directement dans votre page

Utilisez Checkout v4 si vous voulez rediriger le client vers une page de paiement complete. Utilisez Button v4 si vous voulez garder le bouton dans votre page produit, panier, facture ou espace client.

Prerequis

Vous avez besoin de:

une apikey marchand SoleasPay;
un montant et une devise;
une reference de commande unique;
une URL de succes;
une URL d’echec.

Votre apikey identifie le marchand et permet au plugin de charger les moyens de paiement autorises. Ne publiez pas une cle qui donne acces a des actions sensibles hors contexte plugin.

Checkout v4

Checkout v4 affiche une page de paiement hebergee. Votre application soumet les donnees du paiement vers:

https://pay.soleaspay.com

Le client choisit son pays, son moyen de paiement, confirme l’operation, puis revient vers successUrl ou failureUrl.

Exemple HTML

Vous pouvez creer un formulaire HTML classique.

<form method="POST" action="https://pay.soleaspay.com">
  <input type="hidden" name="apiKey" value="YOUR_API_KEY" />
  <input type="hidden" name="amount" value="25000" />
  <input type="hidden" name="currency" value="XAF" />
  <input type="hidden" name="orderId" value="ORDER-2026-0001" />
  <input type="hidden" name="description" value="Paiement commande ORDER-2026-0001" />
  <input type="hidden" name="shopName" value="Shop Name" />
  <input type="hidden" name="successUrl" value="https://yourdomain.com/receivePayment" />
  <input type="hidden" name="failureUrl" value="https://yourdomain.com/paymentFailed" />

  <button type="submit">Payer avec SoleasPay</button>
</form>

Exemple JSON serveur

Si votre backend initie la checkout, envoyez le meme payload.

curl -X POST "https://pay.soleaspay.com" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "amount": 25000,
    "currency": "XAF",
    "orderId": "ORDER-2026-0001",
    "description": "Paiement commande ORDER-2026-0001",
    "shopName": "Shop Name",
    "successUrl": "https://yourdomain.com/receivePayment",
    "failureUrl": "https://yourdomain.com/paymentFailed",
    "customer": {
      "name": "Ada Client",
      "email": "ada@example.com"
    }
  }'

Champs Checkout v4

Champ	Obligatoire	Description
`apiKey`	Oui	API key marchand SoleasPay
`amount`	Oui	Montant a payer
`currency`	Oui	Devise du montant, par exemple `XAF`, `XOF`, `USD`
`orderId`	Oui	Reference unique de commande cote marchand
`description`	Oui	Description affichee au client
`shopName`	Oui	Nom de la boutique ou du service
`successUrl`	Oui	URL appelee apres un paiement reussi
`failureUrl`	Oui	URL appelee apres un paiement echoue ou annule
`customer`	Non	Donnees client pour pre-remplir la checkout
`line`	Non	`up` pour autoriser la conversion de devise
`area`	Non	Zone ou pays souhaite pour filtrer les services
`feeBearer`	Non	`CUSTOMER` si le client paie les frais, `MERCHANT` si le marchand les supporte

Frais plugin

Les plugins peuvent indiquer qui supporte les frais a chaque paiement. Le backend normalise cette valeur puis recalcule les frais cote serveur au moment du collect. Priorite de resolution:

feeBearer dans le payload du collect.
feeBearer dans la query string.
Fallback historique si aucune valeur n’est fournie.

Valeurs canoniques:

Valeur	Effet
`CUSTOMER`	Les frais sont ajoutes au montant payable par le client
`MERCHANT`	Les frais sont supportes par le marchand

Les alias booleens customerPaysFees et customer_pays_fees sont acceptes temporairement a la frontiere HTTP puis normalises vers CUSTOMER ou MERCHANT.

Dans Checkout v4, le devis de frais est calcule par le plugin pendant la session de paiement. Votre integration continue d’utiliser apiKey; elle ne doit pas gerer un JWT pour ce calcul.

Le plugin relaie le calcul vers la gateway avec origin: "PLUGIN", le service choisi, le montant, la devise et le contexte feeBearer.

{
  "origin": "PLUGIN",
  "provider": "mtn_cmr",
  "amount": 25000,
  "currency": "XAF",
  "plugin": "CHECKOUT",
  "feeBearer": "CUSTOMER"
}

Si vous construisez votre propre backend serveur a serveur hors plugin, utilisez plutot la route gateway POST /transactions/fees/quote avec x-sp-auth-token.

Retour apres paiement

Apres le paiement, Checkout v4 redirige le client vers l’URL appropriee avec les donnees de paiement dans soleaspay_data.

https://yourdomain.com/receivePayment?soleaspay_data=<json-url-encoded>

Une fois decode, soleaspay_data contient les informations de transaction.

{
  "transaction_reference": "TRX-123456",
  "reference": "TRX-123456",
  "invoice_reference": "ORDER-2026-0001",
  "provider_reference": "PROVIDER-789",
  "status": "SUCCESS",
  "success": true,
  "operation": "COLLECTION",
  "channel": "PROVIDER",
  "amount": 25000,
  "currency": "XAF"
}

Votre backend doit mettre a jour la commande avec transaction_reference, status, amount, currency et invoice_reference.

Checkout avec split

Checkout v4 peut recevoir un contexte de repartition.

{
  "apiKey": "YOUR_API_KEY",
  "amount": 25000,
  "currency": "XAF",
  "orderId": "ORDER-SPLIT-001",
  "description": "Commande marketplace",
  "shopName": "Marketplace",
  "successUrl": "https://yourdomain.com/receivePayment",
  "failureUrl": "https://yourdomain.com/paymentFailed",
  "settlement_mode": "SPLIT",
  "distribution": [
    {
      "matricule": "SELLER-001",
      "rate": 80,
      "description": "Part vendeur"
    },
    {
      "matricule": "MARKET-001",
      "rate": 20,
      "description": "Commission marketplace"
    }
  ]
}

La somme des rate ne doit pas depasser 100.

Button v4

Button v4 ajoute un bouton SoleasPay dans votre page. Il se charge d’ouvrir l’interface de paiement, de charger les moyens de paiement et de retourner le resultat dans votre JavaScript.

Installation du script

Ajoutez un conteneur pour le bouton, puis chargez le script.

<div id="soleaspay_btn_V4_1"></div>

<script
  id="SBScript"
  type="text/javascript"
  data-lang="fr"
  data-apikey="YOUR_API_KEY"
  src="https://btn.soleaspay.com/main.js">
</script>

data-lang controle la langue de l’interface. Utilisez par exemple fr ou en.

Initialiser le paiement

<script type="text/javascript">
  const options = {
    btnTitle: "Pay",
    amount: 25,
    currency: "USD",
    orderId: "MLS00000025F",
    description: "Test sopay button payment",
    businessName: "Shop Name",
    loadInvoice: true,
    successUrl: "https://yourdomain.com/receivePayment",
    mode: "BILLING"
  };

  function initButton() {
    return SopayButton.pay(options)
      .then((res) => console.log(res))
      .catch((err) => console.log(err));
  }

  initButton();
</script>

Si vous voulez recreer automatiquement le bouton apres chaque tentative de paiement, vous pouvez relancer initButton() dans le finally.

function initButton() {
  return SopayButton.pay(options)
    .then((res) => console.log(res))
    .catch((err) => console.log(err))
    .finally(initButton);
}

Options Button v4

Option	Obligatoire	Description
`btnTitle`	Non	Texte affiche sur le bouton
`amount`	Oui en `BILLING`	Montant a payer
`currency`	Oui	Devise du paiement
`orderId`	Oui	Reference unique de paiement
`description`	Oui	Description affichee au client
`businessName`	Oui	Nom de la boutique ou du service
`loadInvoice`	Non	Charge ou cree l’invoice cote plugin
`successUrl`	Oui	URL de retour apres succes
`mode`	Oui	`BILLING` ou `TIPING`

Modes Button v4

Mode	Comportement
`BILLING`	Le montant est fixe par votre application
`TIPING`	Le client peut saisir le montant a payer

Conservez l’orthographe TIPING si votre integration utilise ce mode, car c’est la valeur attendue par le plugin.

Reponse JavaScript

SopayButton.pay(options) retourne une promesse. En cas de succes, vous recevez un objet exploitable dans votre interface.

{
  "success": true,
  "status": "SUCCESS",
  "message": "Transaction submitted",
  "data": {
    "transaction_reference": "TRX-123456",
    "reference": "TRX-123456",
    "status": "SUCCESS",
    "amount": 25,
    "currency": "USD"
  }
}

Utilisez cette reponse pour afficher un message au client. Pour une commande sensible, votre backend doit aussi verifier la transaction avant de livrer le service.

Bonnes pratiques

Utilisez un orderId unique par paiement.
Chargez Button v4 une seule fois par page.
Ne melangez pas Checkout v4 et Button v4 sur le meme parcours utilisateur.
Verifiez que successUrl et failureUrl sont accessibles en HTTPS.
Enregistrez transaction_reference des que le plugin la retourne.
Ne considerez un paiement comme reussi que si status vaut COMPLETED ou SUCCESS.

Demarrer

Paiements

Catalogue

Choisir le bon plugin

Prerequis

Checkout v4

Exemple HTML

Exemple JSON serveur

Champs Checkout v4

Frais plugin

Retour apres paiement

Checkout avec split

Button v4

Installation du script

Initialiser le paiement

Options Button v4

Modes Button v4

Reponse JavaScript

Bonnes pratiques

​Choisir le bon plugin

​Prerequis

​Checkout v4

​Exemple HTML

​Exemple JSON serveur

​Champs Checkout v4

​Frais plugin

​Retour apres paiement

​Checkout avec split

​Button v4

​Installation du script

​Initialiser le paiement

​Options Button v4

​Modes Button v4

​Reponse JavaScript

​Bonnes pratiques

Choisir le bon plugin

Prerequis

Checkout v4

Exemple HTML

Exemple JSON serveur

Champs Checkout v4

Frais plugin

Retour apres paiement

Checkout avec split

Button v4

Installation du script

Initialiser le paiement

Options Button v4

Modes Button v4

Reponse JavaScript

Bonnes pratiques