Ruby

Oficiální Ruby SDK pro platební bránu Cost+. Zjednodušuje tok přesměrování HPP (Hosted Payment Page), HMAC podepisování payloadu a ověřování webhooků.

Funkce

Generování podpisů HMAC-SHA256 a ověřování s konstantním časem
Automatické mapování snake_case z API do Ruby-friendly OpenStruct objektů
Parsování webhooků + ověřování objednávek přes API
Testováno na Ruby 3.1, 3.2 a 3.3
Sinatra demo aplikace pro obchodníky součástí balení

Požadavky

Ruby 3.1 nebo novější
Obchodní účet Cost+ — dashboard.costplus.io

Instalace

Přidejte do Gemfile:

gem "nopayn"

Poté spusťte:

bundle install

Nebo nainstalujte přímo:

gem install nopayn

Rychlý start

1. Inicializace klienta

require "nopayn"

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

2. Vytvoření platby a přesměrování na 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. Zpracování webhooku

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 reference

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

Parametr	Typ	Povinné	Výchozí
`api_key`	`String`	Ano	—
`merchant_id`	`String`	Ano	—
`base_url`	`String`	Ne	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Vytvoří objednávku přes POST /v1/orders/.

Parametr	Typ	Povinné	Popis
`:amount`	`Integer`	Ano	Částka v nejmenší měnové jednotce (centy)
`:currency`	`String`	Ano	ISO 4217 kód (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Ne	Vaše interní reference objednávky
`:description`	`String`	Ne	Popis objednávky
`:return_url`	`String`	Ne	Přesměrování po úspěšné platbě
`:failure_url`	`String`	Ne	Přesměrování při zrušení/vypršení/chybě
`:webhook_url`	`String`	Ne	Asynchronní notifikace o změně stavu
`:locale`	`String`	Ne	Jazyk HPP (`en-GB`, `de-DE`, `nl-NL` atd.)
`:payment_methods`	`Array<String>`	Ne	Filtr metod HPP
`:expiration_period`	`String`	Ne	ISO 8601 doba trvání (`PT30M`)

Dostupné platební metody: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Načte detaily objednávky přes GET /v1/orders/{id}/.

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

Provede úplnou nebo částečnou refundaci přes POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Pohodlná metoda, která vytvoří objednávku a vrátí:

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`

Generuje HMAC-SHA256 hex podpis.

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

Ověření HMAC-SHA256 podpisu s konstantním časem.

`client.verify_webhook(raw_body) -> OpenStruct`

Parsuje tělo webhooku a poté zavolá GET /v1/orders/{id}/ pro ověření skutečného stavu.

Samostatné HMAC utility

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)

Zpracování chyb

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

Výjimka	Rodič	Popis
`NoPayn::Error`	`StandardError`	Základní chyba pro všechny chyby SDK
`NoPayn::ApiError`	`NoPayn::Error`	HTTP chyba z API
`NoPayn::WebhookError`	`NoPayn::Error`	Neplatný webhookový payload

Stavy objednávek

Stav	Konečný?	Popis
`new`	Ne	Objednávka vytvořena
`processing`	Ne	Platba probíhá
`completed`	Ano	Platba úspěšná — doručte zboží
`cancelled`	Ano	Platba zrušena zákazníkem
`expired`	Ano	Platební odkaz vypršel
`error`	Ano	Technická chyba

Osvědčené postupy pro webhooky

Vždy ověřte přes API — webhookový payload obsahuje pouze ID objednávky, nikdy stav. Metoda verify_webhook SDK to dělá automaticky.
Vraťte HTTP 200 jako potvrzení přijetí. Jakýkoli jiný kód spustí až 10 opakování (po 2 minutách).
Implementujte záložní polling — pro objednávky starší než 10 minut, které nedosáhly konečného stavu, dotazujte get_order jako záchrannou síť.
Buďte idempotentní — stejný webhook můžete obdržet vícekrát.

Testovací karty

Tyto karty použijte v testovacím režimu Cost+ (sandbox web):

Karta	Číslo	Poznámky
Visa (úspěch)	`4111 1111 1111 1111`	Libovolné CVV
Mastercard (úspěch)	`5544 3300 0003 7`	Libovolné CVV
Visa (zamítnuto)	`4111 1111 1111 1105`	Do Not Honor
Visa (nedostatek prostředků)	`4111 1111 1111 1151`	Insufficient Funds

Použijte libovolné budoucí datum platnosti a libovolný 3místný CVC.

Demo aplikace

Demo aplikace založená na Sinatře je součástí GitHub repozitáře pro testování celého platebního toku.

Podpora

Potřebujete pomoc? Obraťte se na náš tým podpory na support@costplus.io.

On this page