Ruby

SDK officiel Ruby 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

• Génération de signature HMAC-SHA256 et vérification en temps constant
• Mappage automatique snake_case de l'API vers des objets Ruby OpenStruct
• Analyse des webhooks + vérification des commandes via l'API
• Testé sur Ruby 3.1, 3.2 et 3.3
• Application de démonstration Sinatra incluse

Prérequis

• Ruby 3.1 ou ultérieur
• Un compte marchand Cost+ — dashboard.costplus.io

Installation

Ajoutez à votre Gemfile :

gem "nopayn"

Puis exécutez :

bundle install

Ou installez directement :

gem install nopayn

Démarrage rapide

1. Initialiser le client

require "nopayn"

nopayn = NoPayn::Client.new(
  api_key:     "your-api-key",
  merchant_id: "your-project"
)

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

result = nopayn.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

post "/webhook" do
  request.body.rewind
  raw_body = request.body.read

  verified = nopayn.verify_webhook(raw_body)

  puts verified.order.status  # "completed", "cancelled", etc.
  puts verified.is_final      # true when the order won't change

  if verified.order.status == "completed"
    # Fulfil the order
  end

  status 200
end

Référence API

NoPayn::Client.new(api_key:, merchant_id:, base_url:)

client.create_order(params) → OpenStruct

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) → OpenStruct

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

client.create_refund(order_id, amount, description: nil) → OpenStruct

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

client.generate_payment_url(params) → OpenStruct

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

result.order_id     # NoPayn order UUID
result.order_url    # HPP URL
result.payment_url  # Direct payment URL (first transaction)
result.signature    # HMAC-SHA256 of amount:currency:order_id
result.order        # Full order OpenStruct

client.generate_signature(amount, currency, order_id) → String

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

client.verify_signature(amount, currency, order_id, signature) → Boolean

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

client.verify_webhook(raw_body) → OpenStruct

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

Utilitaires HMAC autonomes

require "nopayn"

sig = NoPayn::Signature.generate("your-api-key", 1295, "EUR", "order-uuid")
ok  = NoPayn::Signature.verify("your-api-key", 1295, "EUR", "order-uuid", sig)

Gestion des erreurs

begin
  nopayn.create_order(amount: 100, currency: "EUR")
rescue NoPayn::ApiError => e
  puts e.status_code  # 401, 400, etc.
  puts e.error_body   # Raw API error response
rescue NoPayn::Error => e
  puts e.message      # Network or parsing error
end

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 Sinatra 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.