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
- Ruby 3.1 alebo novsi
- Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
Pridajte do vasho Gemfile:
gem "nopayn"Potom spustite:
bundle installAlebo nainštalujte priamo:
gem install nopaynRychly 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 objednavky3. 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
endAPI referencia
NoPayn::Client.new(api_key:, merchant_id:, base_url:)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
api_key | String | Ano | -- |
merchant_id | String | Ano | -- |
base_url | String | Nie | https://api.nopayn.co.uk |
client.create_order(params) -> OpenStruct
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
:amount | Integer | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
:currency | String | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
:merchant_order_id | String | Nie | Vasa interna referencia objednavky |
:description | String | Nie | Popis objednavky |
:return_url | String | Nie | Presmerovanie po uspesnej platbe |
:failure_url | String | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
:webhook_url | String | Nie | Asynchronne notifikacie o zmene stavu |
:locale | String | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
:payment_methods | Array<String> | Nie | Filter platobnych metod HPP |
:expiration_period | String | Nie | ISO 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 OpenStructclient.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| Vynimka | Rodic | Popis |
|---|---|---|
NoPayn::Error | StandardError | Zakladna chyba pre vsetky SDK chyby |
NoPayn::ApiError | NoPayn::Error | HTTP chyba z API |
NoPayn::WebhookError | NoPayn::Error | Neplatny payload webhooku |
Stavy objednavok
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
verify_webhookto robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
get_orderako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient 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.