🔁Intégration Standard

Vue d'ensemble

Moneroo Standard est notre flux de paiement qui redirige votre client vers une page de paiement hébergée par Moneroo.

Voici comment cela fonctionne :

• Depuis votre serveur, appelez le endpoint "initialiser le paiement" de notre API avec les détails du paiement.

• Nous vous renvoyons un lien vers une page de paiement. Redirigez votre client vers ce lien pour effectuer le paiement.

• Lorsque la transaction est terminée, nous redirigeons le client vers vous (vers return_url que vous avez fournie) avec les détails du paiement.

Étape 1 : Collecte des données de paiement

Tout d'abord, vous devez rassembler les données de paiement qui seront envoyées à votre API sous la forme d'un objet JSON.

Voici les champs à collecter :

Nom du champ	Type	Exigée	Description
amount	integer	Oui	Le montant du paiement.
currency	string	Oui	La devise du paiement.
description	string	Oui	Description du paiement.
return_url	string	Oui	URL de retour où votre client sera redirigé après le paiement.
customer.email	string	Oui	Adresse e-mail du client.
customer.first_name	string	Oui	Prénom du client.
customer.last_name	string	Oui	Nom de famille du client.
customer.phone	string	Non¹	Numéro de téléphone du client.
customer.address	string	Non¹	Adresse du client.
customer.city	string	Non¹	Ville du client.
customer.state	string	Non¹	État du client.
customer.country	string	Non¹	Pays du client.
customer.zip	string	Non¹	Code postal du client.
metadata	array	Non²	Données complémentaires pour le paiement.
methods	array	Non³	Méthodes de paiement autorisées.
restrict_country_code	string	Non⁴	Restreindre le paiement à un pays spécifique.
restricted_phone	object	Non⁴	Restreindre le paiement à un numéro de téléphone spécifique.
restricted_phone.number	string	Oui⁵	Le numéro de téléphone auquel restreindre le paiement.
restricted_phone.country_code	string	Oui⁵	Le code pays du numéro de téléphone restreint.

1. Si ces informations ne sont pas fournies, le client peut être invité à les saisir au cours de la procédure de paiement, en fonction de la méthode de paiement sélectionnée.

2. Il doit s'agir d'un tableau de paires clé-valeur. Seules les chaînes de caractères sont autorisées.

3. S'il n'est pas fourni, tous les modes de paiement disponibles seront autorisés. Le tableau ne doit contenir que les modes de paiement pris en charge.

4. Vous pouvez utiliser soit restrict_country_code, soit restricted_phone, mais pas les deux. Ils sont mutuellement exclusifs.

5. Obligatoire si restricted_phone est fourni.

Étape 2 : Obtention d'un lien de paiement

Ensuite, initiez le paiement en appelant notre API avec les détails de paiement collectés (n'oubliez pas d'autoriser avec votre clé secrète).

Exemple de demande :

POST /v1/payments/initialize
Host: https://api.moneroo.io
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
Accept: application/json
{
    "amount": 100,
    "currency": "USD",
    "description": "Payment for order #123",
    "customer": {
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": "https://example.com/payments/thank-you"
    "metadata": {
        "order_id": "123",
        "customer_id": "123" 
    },
    "methods": ["qr_ngn", "bank_transfer_ngn"]
}

Exemple de réponse :

{
  "success": true,
  "message": "Transaction initialized successfully",
  "data": {
    "id": "5f7b1b2c-1b2c-5f7b-0000-000000000000",
    "checkout_url": "https://checkout.moneroo.io/5f7b1b2c-1b2c-5f7b-0000-000000000000"
  }
}

Étape 3 : Redirection de l'utilisateur vers le lien de paiement

Il vous suffit de rediriger votre client vers le lien renvoyé dans data.link. Nous afficherons notre interface de paiement pour que le client puisse effectuer le paiement.

Étape 4 : Après le paiement

Une fois le paiement effectué (avec ou sans succès), cinq choses se produisent :

• Nous redirigeons vers votre URL de retour avec le statut, monerooPaymentId, et monerooPaymentStatus dans les paramètres de la requête une fois que le paiement est terminé.

• Nous vous enverrons un Webhook si vous l'avez activé. Pour plus d'informations sur les Webhooks et pour voir des exemples, consultez notre guide sur les Webhooks.

• Nous enverrons un accusé de réception à votre client si le paiement a été effectué avec succès (sauf si vous l'avez désactivé).

• Nous vous enverrons un email (sauf si vous l'avez désactivé).

• Côté serveur, vous devez gérer la redirection et toujours vérifier l'état final de la transaction. Un exemple de vérification d'une transaction dans une application PHP avec notre backend SDK sera fourni plus loin.

Si vous avez activé les Webhooks, nous vous enverrons une notification pour chaque tentative de paiement échouée. C'est utile si vous souhaitez contacter ultérieurement les clients qui ont eu des difficultés à payer. Consultez notre guide des Webhooks pour un exemple.

Exemple

• N'oubliez pas de remplacer YOUR_SECRET_KEY par votre véritable clé secrète.

• Tous les exemples suivants doivent être réalisés dans le backend, ne jamais exposer votre clé secrète au public.

cURL

curl -X POST https://api.moneroo.io/v1/payments/initialize \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Accept: application/json" \
     -d '{
         "amount": 100,
         "currency": "USD",
         "description": "Payment for order #123",
         "customer": {
             "email": "[e-mail]",
             "first_name": "John",
             "last_name": "Doe"
         },
         "return_url": "https://example.com/payments/thank-you",
         "metadata": {
             "order_id": "123",
             "customer_id": "123"
         },
         "methods": ["qr_ngn", "bank_transfer_ngn"]
     }'

PHP

<?php

$url = 'https://api.moneroo.io/v1/payments/initialize';

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_SECRET_KEY'
    'Accept: application/json'
];

$data = [
    "amount" => 100,
    "currency" => "USD",
    "description" => "Payment for order #123",
    "customer" => [
        "email" => "[e-mail]",
        "first_name" => "John",
        "last_name" => "Doe"
    ],
    "return_url" => "https://example.com/payments/thank-you",
    "metadata" => [
        "order_id" => "123",
        "customer_id" => "123",
    ],
    "methods" => ["qr_ngn", "bank_transfer_ngn"]
];

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if ($httpcode != 201) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

$response_data = json_decode($response, true);

// Redirect to checkout page
header("Location: " . $response_data['checkout_url']);

?>

Python

import requests
import json

url = 'https://api.moneroo.io/v1/payments/initialize'

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SECRET_KEY'
    'Accept': 'application/json'
}

data = {
    "amount": 100,
    "currency": "USD",
    "description": "Payment for order #123",
    "customer": {
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": "https://example.com/payments/thank-you",
    "metadata": {
        "order_id": "123",
        "customer_id": "123",
    },
    "methods": ["qr_ngn", "bank_transfer_ngn"]
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code != 201:
    raise Exception(f"Request failed with status {response.status_code}")

checkout_url = response.json()['checkout_url']
print(f"Redirect to: {checkout_url}")

Go

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"fmt"
)

func main() {
	data := map[string]interface{}{
		"amount": 100,
		"currency": "USD",
		"description": "Payment for order #123",
		"customer": map[string]string{
			"email": "[e-mail]",
			"first_name": "John",
			"last_name": "Doe",
		},
		"return_url": "https://example.com/payments/thank-you",
		"metadata": map[string]string{
			"order_id": "123",
			"customer_id": "123",
		},
		"methods": []string{"qr_ngn", "bank_transfer_ngn"},
	}

	bytesRepresentation, _ := json.Marshal(data)

	req, _ := http.NewRequest("POST", "https://api.moneroo.io/v1/payments/initialize", bytes.NewBuffer(bytesRepresentation))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer YOUR_SECRET_KEY")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	response, _ := client.Do(req)
	defer response.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(response.Body).Decode(&result)

	if response.StatusCode != 201 {
		panic(fmt.Sprintf("Request failed with status %d", response.StatusCode))
	}

	fmt.Printf("Redirect to: %s", result["checkout_url"])
}

JavaScript (Node.js)

const axios = require('axios');

const data = {
    "amount": 100,
    "currency": "USD",
    "description": "Payment for order #123",
    "customer": {
        "email": "[e-mail]",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": "https://example.com/payments/thank-you",
    "metadata": {
        "order_id": "123",
        "customer_id": "123",
    },
    "methods": ["qr_ngn", "bank_transfer_ngn"]
};

const options = {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SECRET_KEY'
    'Accept': 'application/json'
  }
};

axios.post('https://api.moneroo.io/v1/payments/initialize', data, options)
    .then((response) => {
        if (response.status !== 201) {
            throw new Error(`Request failed with status ${response.status}`);


 }
        console.log(`Redirect to: ${response.data.checkout_url}`);
    })
    .catch((error) => {
        console.error(error);
    });