Cost+Docs

Ruby

Oficialne Ruby SDK pre platobnu branu Cost+

Oficialne Ruby SDK pre platobnu branu Cost+. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.

Funkcie

  • HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case
  • Automaticke mapovanie snake_case z API na Ruby-friendly OpenStruct objekty
  • Parsovanie webhookov + overovanie objednavok na zaklade API
  • Testovane na Ruby 3.1, 3.2 a 3.3
  • Sinatra demo obchodnicka aplikacia zahrnuta

Poziadavky

Instalacia

Pridajte do vasho Gemfile:

gem "nopayn"

Potom spustite:

bundle install

Alebo nainštalujte priamo:

gem install nopayn

Rychly start

1. Inicializacia klienta

require "nopayn"

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

2. Vytvorenie platby a presmerovanie na HPP

result = nopayn.generate_payment_url(
  amount:            1295,           # €12,95 v centoch
  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"
)

# Presmerujte zakaznika
# result.order_url   → HPP (zakaznik si vyberie platobnu metodu)
# result.payment_url → priamy odkaz na platobnu metodu prvej transakcie
# result.signature   → HMAC-SHA256 na overenie
# result.order_id    → NoPayn UUID objednavky

3. Spracovanie webhooku

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

  verified = nopayn.verify_webhook(raw_body)

  puts verified.order.status  # "completed", "cancelled", atd.
  puts verified.is_final      # true, ked sa objednavka uz nezmeni

  if verified.order.status == "completed"
    # Vybavte objednavku
  end

  status 200
end

API referencia

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

ParameterTypPovinnePredvolene
api_keyStringAno--
merchant_idStringAno--
base_urlStringNiehttps://api.nopayn.co.uk

client.create_order(params) -> OpenStruct

Vytvori objednavku cez POST /v1/orders/.

ParameterTypPovinnePopis
:amountIntegeránoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
:currencyStringAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringNieVasa interna referencia objednavky
:descriptionStringNiePopis objednavky
:return_urlStringNiePresmerovanie po uspesnej platbe
:failure_urlStringNiePresmerovanie pri zruseni/exspiracii/chybe
:webhook_urlStringNieAsynchronne notifikacie o zmene stavu
:localeStringNieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
:payment_methodsArray<String>NieFilter platobnych metod HPP
:expiration_periodStringNieISO 8601 trvanie (PT30M)

Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.

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

Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) -> OpenStruct

Pomocna metoda, ktora vytvori objednavku a vrati:

result.order_id     # NoPayn UUID objednavky
result.order_url    # HPP URL
result.payment_url  # Priama platobna URL (prva transakcia)
result.signature    # HMAC-SHA256 z amount:currency:order_id
result.order        # Uplny objekt objednavky OpenStruct

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

Generuje HMAC-SHA256 hex podpis.

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

Overovanie HMAC-SHA256 podpisu v konstantnom case.

client.verify_webhook(raw_body) -> OpenStruct

Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu.

Samostatne HMAC nastroje

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)

Spracovanie chyb

begin
  nopayn.create_order(amount: 100, currency: "EUR")
rescue NoPayn::ApiError => e
  puts e.status_code  # 401, 400, atd.
  puts e.error_body   # Surova API chybova odpoved
rescue NoPayn::Error => e
  puts e.message      # Sietova alebo parsovania chyba
end
VynimkaRodicPopis
NoPayn::ErrorStandardErrorZakladna chyba pre vsetky SDK chyby
NoPayn::ApiErrorNoPayn::ErrorHTTP chyba z API
NoPayn::WebhookErrorNoPayn::ErrorNeplatny payload webhooku

Stavy objednavok

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK verify_webhook to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte get_order ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient Funds

Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.

Demo aplikacia

Demo aplikacia na baze Sinatra je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu.

Podpora

Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.

On this page