Ruby

Hivatalos Ruby SDK a Cost+ fizetési átjáróhoz. Egyszerűsíti a HPP (tárolt fizetési oldal) átirányítási folyamatot, a HMAC adatcsomag-aláírást és a webhook ellenőrzést.

Funkciók

• HMAC-SHA256 aláírás generálás és állandó idejű ellenőrzés
• Automatikus snake_case leképezés az API-ról Ruby-barát OpenStruct objektumokra
• Webhook feldolgozás + API-alapú rendelés ellenőrzés
• Tesztelve Ruby 3.1, 3.2 és 3.3 verziókkal
• Sinatra-alapú demo kereskedői alkalmazás mellékelve

Követelmények

• Ruby 3.1 vagy újabb
• Cost+ kereskedői fiók — dashboard.costplus.io

Telepítés

Adja hozzá a Gemfile-hoz:

gem "nopayn"

Majd futtassa:

bundle install

Vagy telepítse közvetlenül:

gem install nopayn

Gyorsindítás

1. A kliens inicializálása

require "nopayn"

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

2. Fizetés létrehozása és átirányítás a HPP-re

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 kezelése

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-referencia

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

client.create_order(params) -> OpenStruct

Rendelést hoz létre a POST /v1/orders/ végponton.

Elérhető fizetési módok: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Rendelés részleteinek lekérdezése a GET /v1/orders/{id}/ végponton.

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

Teljes vagy részleges visszatérítés kiadása a POST /v1/orders/{id}/refunds/ végponton.

client.generate_payment_url(params) -> OpenStruct

Kényelmi metódus, amely rendelést hoz létre és visszaadja:

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

HMAC-SHA256 hex aláírást generál.

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

HMAC-SHA256 aláírás állandó idejű ellenőrzése.

client.verify_webhook(raw_body) -> OpenStruct

Feldolgozza a webhook törzset, majd meghívja a GET /v1/orders/{id}/ végpontot az aktuális állapot ellenőrzéséhez.

Önálló HMAC segédeszközök

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)

Hibakezelés

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

Rendelés állapotok

Webhook bevált gyakorlatok

1. Mindig ellenőrizze az API-n keresztül — a webhook adatcsomag csak a rendelés azonosítóját tartalmazza, soha nem az állapotot. Az SDK verify_webhook metódusa ezt automatikusan elvégzi.
2. Válaszoljon HTTP 200-zal a fogadás nyugtázásához. Bármely más kód legfeljebb 10 újrapróbálkozást vált ki (2 percenként).
3. Alkalmazzon tartalék lekérdezést — a 10 percnél régebbi, végleges állapotot még el nem ért rendelésekhez kérdezze le a get_order metódust biztonsági hálóként.
4. Legyen idempotens — ugyanazt a webhookot többször is megkaphatja.

Tesztkártyák

Használja ezeket a kártyákat Cost+ teszt módban (sandbox weboldal):

Használjon bármely jövőbeli lejárati dátumot és bármely 3 számjegyű CVC-t.

Demo alkalmazás

Egy Sinatra-alapú demo alkalmazás található a GitHub tárolóban a teljes fizetési folyamat teszteléséhez.

Támogatás

Segítségre van szüksége? Forduljon ügyfélszolgálatunkhoz: support@costplus.io.