API de paiement Standard

Paramètre API Token

Toute requête vers l'API WiniPayer doit contenir les tokens d'authentification du compte marchand dans le Header de la requête. Les Tokens de l'API sont disponibles sur la page de detail de chaque compte marchand dans votre Manager.

Paramètres Headers	Obligatoire	Exemple
X-Merchant-Apply	`Oui`	5NqZlFTai12YsSWbGbS6
X-Merchant-Token	`Oui`	828209b9-a457-4a06-9635-35dc46187330

{info} NB : Il est tout à fait possible de générer des liens de paiement en TEST ou en PROD en fonction de l'environnement du compte marchand :
- Si le compte marchand est en TEST vous ne pouvez générer que des liens de paiements en TEST en utilisant les Tokens de TEST.
- Si le compte marchand est en PROD vous ne pouvez générer que des liens de paiement en PROD en utilisant les Tokens de PROD.

Générer un lien de paiement

Pour générer un lien de paiement vous aurez besoin des éléments suivants :

1 - Endpoint API Standard

Pour générer un lien de paiement standard, vous devez effectuer une requête HTTP POST sur l'URL suivant :

https://api-v2.winipayer.com/checkout/standard/create

2 - Paramètres Body de base

En plus des parametres Headers, vous devez utiliser en paramètres Body les clés suivantes:

Paramètres Body	Type	Obligatoire	Exemple
env	`string`	`Oui`	`test` pour un paiement en TEST et `prod` pour un paiement en PRODUCTION
amount	`int`	`Oui`	`3500` Le montant de la transaction.
description	`string`	`Oui`	`Facture Client Mariam N° 2563584`
items	`json`	`Non`	Le paramètre items est un tableau d'objet. Exemple ci-dessous
custom_data	`json`	`Non`	`{"user_id":33,"order_id":365}`
client_pay_fee	`boolean`	`Non`	`true` Permets de specifier si le client payé les frais de transaction.
cancel_url	`url`	`Oui`	`https://tester.winipayer.com/cancel`
return_url	`url`	`Oui`	`https://tester.winipayer.com/return`
callback_url	`url`	`Oui`	`https://tester.winipayer.com/callback`

NB : Pour les paramètres supplémentaires facultatif, veuillez vous référer à la section Paramètres supplémentaires

Exemple de paramètre items

[
    {
        "name": "Boubou marocain",
        "quantity": 1,
        "price_unit": 3500,
        "description": "Qualité supérieur",
        "price_total": 3500
    },
    ...
]

NB : Les montants des items n'ont aucun impact sur le montant à payer par le client . ses informations sont à titre indicatif pour votre client.

Exemple de requête cURL

curl --location 'https://api-v2.winipayer.com/checkout/standard/create' \
--header 'X-Merchant-Apply: 5NqZlFTai12YsSWbGbS6' \
--header 'X-Merchant-Token: 828209b9-a457-4a06-9635-35dc46187330' \
--form 'env="prod"' \
--form 'amount="3500"' \
--form 'description="Facture Client Mariam N° 2563584"' \
--form 'items="[{\"name\":\"Boubou marocain\",\"quantity\":1,\"price_unit\":3500,\"description\":"Qualité supérieur",\"price_total\":3500}]"' \
--form 'custom_data="{\"user_id\":33,\"order_id\":365}"' \
--form 'client_pay_fee="true"' \
--form 'cancel_url="https://tester.winipayer.com/cancel"' \
--form 'return_url="https://tester.winipayer.com/return"' \
--form 'callback_url="https://tester.winipayer.com/callback"'

Exemple de réponse succès

{success} Si les paramètres sont valides vous devez obtenir une réponse au format JSON :

{
    "success": true,
    "results": {
        "uuid": "2f1e1d74-78f3-4759-96a4-1ff6bc409d91",
        "crypto": "invoice_prod_9d6b71764a1f20cfe851f00f57908e599439e7c548fa1eae8bc4f53b00e5f571a0e8923e725bae4a1a86e191cb7911b1e08ad8e3",
        "env": "prod",
        "amount": 500,
        "currency": "xof",
        "operator": null,
        "operator_process": null,
        "operator_message": null,
        "checkout_process": "https://checkout-v2.winipayer.com/process/tng/invoice_prod_9d6b71764a1f20cfe851f00f57908e599439e7c548fa1eae8bc4f53b00e5f571a0e8923e725bae4a1a86e191cb7911b1e08ad8e3",
        "expired_at": "2024-07-08 21:35:55"
    },
    "errors": [],
    "messages": []
}

Après avoir obtenu l'URL de paiement checkout_process vous devez rediriger l'utilisateur sur ce lien (Portail de paiement) pour effectuer le paiement.

Attention !

Il est recommandé de sauvegarder la réponse de l'API pour des vérifications ultérieures après le paiement du client.
uuid est la référence permanente de la facture. Elle vous servira pour obtenir les informations détaillées du paiement.
crypto est la référence temporaire de la facture. Elle est valide uniquement durant la transaction.
expired_at est la date d'expiration du lien de paiement. Elle a une durée de validité de 30 minutes

Exemple de réponse erreur

{
    "success": false,
    "results": [],
    "errors": {
        "code": 2000,
        "key": "amount",
        "msg": "The amount field is required."
    },
    "messages": []
}

Portail de paiement (Checkout)

Portail de paiment client.

Vérifier un lien de paiement

Endpoint API de vérification

Pour obtenir les détails d'un lien de paiement, vous devez effectuer une requête HTTP POST sur l'URL suivant :

https://api-v2.winipayer.com/checkout/standard/detail/:uuid

Attention !

:uuid remplacer cette clé par la valeur de la reference UUID de la facture :

Exemple : `https://api-v2.winipayer.com/checkout/standard/detail/2f1e1d74-78f3-4759-96a4-1ff6bc409d91`

Paramètres Body

En plus des parametres Headers, vous devez utiliser en paramètres Body les clés suivantes:

Paramètres Body	Type	Obligatoire	Exemple
env	`string`	`Oui`	`test` pour un paiement en TEST et `prod` pour un paiement en PRODUCTION

Exemple de réponse succès

{
    "success": true,
    "results": {
        "invoice": {
            "uuid": "2f1e1d74-78f3-4759-96a4-1ff6bc409d91",
            "crypto": "invoice_prod_9d6b71764a1f20cfe851f00f57908e599439e7c548fa1eae8bc4f53b00e5f571a0e8923e725bae4a1a86e191cb7911b1e08ad8e3",
            "module": {
                "name": "default",
                "uuid": null
            },
            "hash": "3a58322928469be5f4d152af26ecd611123bca04c81a15f59b1a9c6b54600bed",
            "env": "prod",
            "version": "v2",
            "state": "success",
            "state_date": "2024-07-09 08:04:58",
            "amount_init": 3500,
            "amount": 3500,
            "client_pay_fee": true,
            "commission_amount": 87.5,
            "commission_rate": 2.5,
            "commission_fee": null,
            "amount_available": 3412.5,
            "currency": "xof",
            "channel": [],
            "description": "acture Client Mariam",
            "wpsecure": false,
            "wpsecure_validate": null,
            "items": [
                {
                    "name": "Boubou marocain",
                    "quantity": 1,
                    "price_unit": 3500,
                    "description": null,
                    "price_total": 3500
                }
            ],
            "custom_data": {
                "user_id": 33,
                "order_id": 365
            },
            "store": {
                "uuid": "af0169d8-fdb4-4df8-bf8e-6b16ab321379",
                "name": "WiniHost",
                "description": "WiniHost est un service qui offre tout ce qu'il faut pour lancer un site internet ou une application en ligne avec tous les standards de sécurité: nom de domaine gratuit, hébergement web, comptes mail, bases de données, CMS, etc...",
                "web_url": "https://www.winihost.com",
                "logo": "https://api-v2.winipayer.com/all/media/view/117c5a99-b6eb-4ada-8374-5bc716b370b0",
                "email": "[email protected]",
                "phone": "2250555800400",
                "country": "ci",
                "city": "Abidjan",
                "address": "Angré 9ème tranche, Immeuble Téré",
                "ipn_url": "https://pay.winihost.com/ipn"
            },
            "operator": "wave-cote-divoire",
            "operator_ref": "TBLBMKZHJVE",
            "reference": {
                "identifier": null,
                "name": null,
                "phone": null,
                "email": null
            },
            "customer_pay": {
                "name": "JARS T I",
                "phone": "+2250555800400",
                "email": null
            },
            "cancel_url": "https://tester.winipayer.com/cancel",
            "return_url": "https://tester.winipayer.com/return",
            "callback_url": "https://tester.winipayer.com/callback",
            "checkout_link": "https://checkout-v2.winipayer.com/process/tng/invoice_prod_9cb7961e9d04cd562e833c449fdfad78b545c4e3fb5ce9146bc86d46e452e448678cd4a7a44c674ffe0a1767eb89822a6f393ecc",
            "checkout_receipt": null,
            "ipn_call": null,
            "created_at": "2024-07-09 08:04:58",
            "expired_at": "2024-07-09 08:34:58"
        }
    },
    "errors": [],
    "messages": []
}

{info} La clé hash renvoyée par dans la réponse par WiniPayer est le hash256 du prod_private_key ou test private key de votre compte marchand en fonction de l'environnement (test ou prod) dans laquelle la facture a été génère. Cette {test|prod}_private_key est concaténé avec les clés uuid , crypto , amount et created_at avant le hashage. Ce hash vous permettra de vous assurer que les données que vous avez reçues proviennent de nos serveurs.

// Example PHP pour une facture générer en PROD
$generated_hash = hash('sha256', $prod_private_key . $uuid . $crypto . $amount . $created_at);

if($received_token === $generated_hash)
{
      // Valid transaction
}

Exemple de réponse expiré

{
    "success": false,
    "results": [],
    "errors": {
        "code": 3000,
        "key": "uuid",
        "msg": "Invalide or missing invoice"
    },
    "messages": []
}

Exemple de réponse échec

{
    "success": false,
    "results": [],
    "errors": {
        "code": 2000,
        "key": "X-Merchant-Token",
        "msg": "Invalid or missing X-Merchant-Token"
    },
    "messages": []
}

Paramètres Body supplémentaires

En plus des Paramètres Body de base pour la génération de liens de paiement, vous avez la possibilité d'ajouter des paramètres supplémentaires au besoin :

Paramètres Body	Type	Exemple
wpsecure	`boolean`	`true` Ce paramètre permet d'ajouter une couche de validation*
channel	`json`	`{"wave-cote-divoire", ...}` Permet de fixer les opérateurs à afficher au client
reference	`json`	`{"identifier":"AA256KL","name":"Koffi Charle","phone":"0555800400", "email":"[email protected]"}`
operator	`string`	`wave-cote-divoire` Permets de générer une session directement auprès de l'opérateur.
operator_input	`string`	`{"phone":"0555800400"}` la valeur de cette clé est dependant de l'opérateur

Information :

wpsecure : Ce paramètre permet d'ajouter une couche de validation supplémentaire.
Si la valeur vaut true alors un code à 9 chiffres (Ex: 653-987-167) est envoyé au client via le mail specifier dans le paramètre reference.email.
Le client devra apres validation du paiement communiquer ce code au marchand pour finaliser la transaccion.
Cas d'utilisation : Le code de validation peut être utilisé dans le cas d'une transaction entre un client qui commande un article sur internet et qui voudrai communiquer le code uniquement après réception et vérification du colis.

Introduction

Manager

API de paiement

API de transfert

SDK et Plugins

Ressources

Besoin d'aide

API de paiement Standard

Paramètre API Token

Générer un lien de paiement

1 - Endpoint API Standard

2 - Paramètres Body de base

Exemple de paramètre items

Exemple de requête cURL

Exemple de réponse succès

Exemple de réponse erreur

Portail de paiement (Checkout)

Vérifier un lien de paiement

Endpoint API de vérification

Paramètres Body

Exemple de réponse succès

Exemple de réponse expiré

Exemple de réponse échec

Paramètres Body supplémentaires