Python

SDK officiel Python pour la passerelle de paiement Cost+. Simplifie le flux de redirection HPP (page de paiement hébergée), la signature de payload HMAC et la vérification des webhooks.

Fonctionnalités

• Dépendances minimales — uniquement requests
• Annotations de type complètes et types de retour en dataclasses gelées
• Génération de signature HMAC-SHA256 et vérification en temps constant
• Analyse des webhooks + vérification des commandes via l'API
• Testé sur Python 3.10, 3.11 et 3.12

Prérequis

• Python 3.10 ou ultérieur
• Un compte marchand Cost+ — dashboard.costplus.io

Installation

pip install nopayn-sdk

Démarrage rapide

1. Initialiser le client

from nopayn import NoPaynClient

client = NoPaynClient(
    api_key="your-api-key",
    merchant_id="your-project",
)

2. Créer un paiement et rediriger vers la HPP

result = client.generate_payment_url(
    amount=1295,             # €12.95 in cents
    currency="EUR",
    merchant_order_id="ORDER-001",
    description="Premium Widget",
    return_url="https://shop.example.com/success",
    failure_url="https://shop.example.com/failure",
    webhook_url="https://shop.example.com/webhook",
    locale="en-GB",
    expiration_period="PT30M",
)

# Redirect the customer
# result.order_url   → HPP (customer picks payment method)
# result.payment_url → direct link to the first transaction's payment method
# result.signature   → HMAC-SHA256 for verification
# result.order_id    → NoPayn order UUID

3. Gérer le webhook (exemple Flask)

@app.route("/webhook", methods=["POST"])
def webhook():
    verified = client.verify_webhook(request.get_data(as_text=True))

    print(verified.order.status)  # 'completed', 'cancelled', etc.
    print(verified.is_final)      # True when the order won't change

    if verified.order.status == "completed":
        # Fulfil the order
        pass

    return "", 200

Référence API

NoPaynClient(api_key, merchant_id, base_url?)

client.create_order(**kwargs) -> Order

Crée une commande via POST /v1/orders/.

Méthodes de paiement disponibles : credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Récupère les détails de la commande via GET /v1/orders/{id}/.

client.create_refund(order_id, amount, description?) -> Refund

Effectue un remboursement total ou partiel via POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Méthode utilitaire qui crée une commande et renvoie :

PaymentUrlResult(
    order_id="...",       # NoPayn order UUID
    order_url="...",      # HPP URL
    payment_url="...",    # Direct payment URL (first transaction)
    signature="...",      # HMAC-SHA256 of amount:currency:order_id
    order=Order(...),     # Full order object
)

client.generate_signature(amount, currency, order_id) -> str

Génère une signature HMAC-SHA256 hexadécimale.

client.verify_signature(amount, currency, order_id, signature) -> bool

Vérification en temps constant d'une signature HMAC-SHA256.

client.verify_webhook(raw_body) -> VerifiedWebhook

Analyse le corps du webhook, puis appelle GET /v1/orders/{id}/ pour vérifier le statut réel.

Utilitaires HMAC autonomes

from nopayn import generate_signature, verify_signature

sig = generate_signature("your-api-key", 1295, "EUR", "order-uuid")
ok = verify_signature("your-api-key", 1295, "EUR", "order-uuid", sig)

Types de données

Toutes les réponses API sont renvoyées sous forme de dataclasses gelées :

Gestion des erreurs

from nopayn import ApiError, NoPaynError, WebhookError

try:
    client.create_order(amount=100, currency="EUR")
except ApiError as exc:
    print(exc.status_code)  # 401, 400, etc.
    print(exc.error_body)   # Raw API error response
except NoPaynError as exc:
    print(exc)              # Network or parsing error

Statuts des commandes

Bonnes pratiques pour les webhooks

1. Vérifiez toujours via l'API — le payload du webhook contient uniquement l'identifiant de la commande, jamais le statut. Le verify_webhook() du SDK le fait automatiquement.
2. Renvoyez HTTP 200 pour accuser réception. Tout autre code déclenche jusqu'à 10 tentatives (espacées de 2 minutes).
3. Implémentez un polling de secours — pour les commandes de plus de 10 minutes qui n'ont pas atteint un statut final, interrogez get_order() comme filet de sécurité.
4. Soyez idempotent — vous pouvez recevoir le même webhook plusieurs fois.

Cartes de test

Utilisez ces cartes en mode test Cost+ (site web sandbox) :

Utilisez n'importe quelle date d'expiration future et n'importe quel CVC à 3 chiffres.

Application de démonstration

Une application de démonstration basée sur Flask est incluse dans le dépôt GitHub pour tester le flux de paiement complet.

Support

Besoin d'aide ? Contactez notre équipe de support à support@costplus.io.