Ruby

Offizielles Ruby SDK für das Cost+ Zahlungsgateway. Vereinfacht den HPP (Hosted Payment Page) Weiterleitungsablauf, die HMAC-Payload-Signierung und die Webhook-Verifizierung.

Funktionen

• HMAC-SHA256-Signaturgenerierung und zeitkonstante Verifizierung
• Automatisches snake_case-Mapping von der API zu Ruby-freundlichen OpenStruct-Objekten
• Webhook-Parsing + API-basierte Bestellungsverifizierung
• Getestet mit Ruby 3.1, 3.2 und 3.3
• Sinatra-basierte Demo-Merchant-App enthalten

Voraussetzungen

• Ruby 3.1 oder neuer
• Ein Cost+ Händlerkonto — dashboard.costplus.io

Installation

Zu Ihrem Gemfile hinzufügen:

gem "nopayn"

Dann ausführen:

bundle install

Oder direkt installieren:

gem install nopayn

Schnellstart

1. Client initialisieren

require "nopayn"

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

2. Zahlung erstellen und zur HPP weiterleiten

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. Webhook verarbeiten

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

API-Referenz

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

client.create_order(params) → OpenStruct

Erstellt eine Bestellung über POST /v1/orders/.

Verfügbare Zahlungsmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) → OpenStruct

Ruft Bestellungsdetails über GET /v1/orders/{id}/ ab.

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

Stellt eine vollständige oder teilweise Erstattung über POST /v1/orders/{id}/refunds/ aus.

client.generate_payment_url(params) → OpenStruct

Komfortmethode, die eine Bestellung erstellt und zurückgibt:

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

Generiert eine HMAC-SHA256-Hex-Signatur.

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

Zeitkonstante Verifizierung einer HMAC-SHA256-Signatur.

client.verify_webhook(raw_body) → OpenStruct

Parst den Webhook-Body und ruft dann GET /v1/orders/{id}/ auf, um den tatsächlichen Status zu verifizieren.

Eigenständige HMAC-Hilfsfunktionen

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)

Fehlerbehandlung

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

Bestellungsstatus

Webhook Best Practices

1. Immer über die API verifizieren — der Webhook-Payload enthält nur die Bestell-ID, niemals den Status. Die verify_webhook-Methode des SDK erledigt dies automatisch.
2. HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
3. Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben, get_order als Sicherheitsnetz abfragen.
4. Idempotent sein — Sie können denselben Webhook mehrfach erhalten.

Testkarten

Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):

Verwenden Sie ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.

Demo-App

Eine Sinatra-basierte Demo-App ist im GitHub-Repository enthalten, um den vollständigen Zahlungsablauf zu testen.

Support

Brauchen Sie Hilfe? Kontaktieren Sie unser Support-Team unter support@costplus.io.