Ruby

SDK oficial Ruby pentru gateway-ul de plăți Cost+. Simplifică fluxul de redirecționare HPP (pagina de plată găzduită), semnarea HMAC a payload-ului și verificarea webhook-urilor.

Funcționalități

• Generare semnătură HMAC-SHA256 și verificare cu timp constant
• Mapare automată snake_case din API la obiecte OpenStruct prietenoase Ruby
• Parsare webhook + verificare comenzi bazată pe API
• Testat pe Ruby 3.1, 3.2 și 3.3
• Aplicație demo de comerciant bazată pe Sinatra inclusă

Cerințe

• Ruby 3.1 sau mai nou
• Un cont de comerciant Cost+ — dashboard.costplus.io

Instalare

Adăugați în Gemfile:

gem "nopayn"

Apoi rulați:

bundle install

Sau instalați direct:

gem install nopayn

Pornire rapidă

1. Inițializați clientul

require "nopayn"

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

2. Creați o plată și redirecționați către 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. Gestionați webhook-ul

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

Referință API

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

client.create_order(params) -> OpenStruct

Creează o comandă prin POST /v1/orders/.

Metode de plată disponibile: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Preia detaliile comenzii prin GET /v1/orders/{id}/.

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

Emite o rambursare totală sau parțială prin POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) -> OpenStruct

Metodă de convenință care creează o comandă și returnează:

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

Generează o semnătură hex HMAC-SHA256.

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

Verificare cu timp constant a unei semnături HMAC-SHA256.

client.verify_webhook(raw_body) -> OpenStruct

Parsează corpul webhook-ului, apoi apelează GET /v1/orders/{id}/ pentru a verifica statusul real.

Utilitare HMAC independente

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)

Gestionarea erorilor

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

Statusuri comandă

Bune practici pentru webhook-uri

1. Verificați întotdeauna prin API — payload-ul webhook conține doar ID-ul comenzii, niciodată statusul. Metoda verify_webhook a SDK-ului face acest lucru automat.
2. Returnați HTTP 200 pentru a confirma recepția. Orice alt cod declanșează până la 10 reîncercări (la 2 minute distanță).
3. Implementați un poller de rezervă — pentru comenzile mai vechi de 10 minute care nu au ajuns la un status final, interogați get_order ca rețea de siguranță.
4. Fiți idempotent — puteți primi același webhook de mai multe ori.

Carduri de test

Folosiți aceste carduri în modul de test Cost+ (site web sandbox):

Folosiți orice dată de expirare viitoare și orice CVC de 3 cifre.

Aplicație demo

O aplicație demo bazată pe Sinatra este inclusă în depozitul GitHub pentru testarea fluxului complet de plată.

Suport

Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.