API de paiement Express

• Paramètre API Token
• Générer un lien de paiement
• Portail de paiement (Checkout)
• Vérifier un lien de paiement

{warning} À la différence de l'API de paiement Standard, l'API de paiement Express demande moins de configuration et de paramètre pour générer un lien de paiement.
NB : L'objectif est de générer rapidement des liens de paiement avec la référence (Uuid) du compte marchand.

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. La Référence (Uuid) du compte marchand est disponible sur la page de detail de chaque compte marchand dans votre Manager.

{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 Express

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

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

2 - Paramètres Body de base

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

Exemple de requête cURL

curl --location 'https://api-v2.winipayer.com/checkout/express/create' \
--header 'X-Merchant-uuid: af0169d8-fdb4-4df8-af8e-6b16af3213790' \
--form 'env="prod"' \
--form 'amount="100"' \
--form 'client_pay_fee="true"'

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": "5010eec1-2678-51db-b0f9-e4ac8c6d5988",
        "crypto": "invoice_prod_ce2c813e152363b5702042af105665834c700ebfd9daa4485e99bfe94b4df3a0e5228fde1ed1bad414b2a3f018ab9b9e3fbe74cf",
        "env": "prod",
        "amount": 100,
        "operator": null,
        "operator_process": null,
        "operator_message": null,
        "checkout_process": "https://checkout-v2.winipayer.com/process/tng/invoice_prod_ce2c813e152363b5702042af105665834c700ebfd9daa4485e99bfe94b4df3a0e5228fde1ed1bad414b2a3f018ab9b9e3fbe74cf",
        "expired_at": "2024-07-10 13:09:28"
    },
    "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/express/detail/:crypto

Attention !

• :crypto remplacer cette clé par la valeur de la clé crypto de la facture :

Exemple: https://api-v2.winipayer.com/checkout/express/detail/invoice_prod_ce2c813e152363b5702042af105665834c700ebfd9daa4485e99bfe94b4df3a0e5228fde1ed1bad414b2a3f018ab9b9e3fbe74cf

Paramètres Body

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

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": null,
            "wpsecure": false,
            "wpsecure_validate": null,
            "items": [],
            "custom_data": [],
            "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": "TBLBCKZHJVE",
            "reference": [],
            "customer_pay": {
                "name": "JARS T I",
                "phone": "+2250555800400",
                "email": null
            },
            "cancel_url": "https://checkout-v2.winipayer.com/page/cancel",
            "return_url": "https://checkout-v2.winipayer.com/page/return",
            "callback_url": "https://checkout-v2.winipayer.com/page/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": []
}