Ruby

Oficjalny SDK Ruby dla bramki płatności Cost+. Upraszcza przepływ przekierowań HPP (hostowanej strony płatności), podpisywanie HMAC i weryfikację webhooków.

Funkcje

Generowanie podpisów HMAC-SHA256 i weryfikacja w stałym czasie
Automatyczne mapowanie snake_case z API do przyjaznych dla Ruby obiektów OpenStruct
Parsowanie webhooków + weryfikacja zamówienia przez API
Testowany na Ruby 3.1, 3.2 i 3.3
Dołączona aplikacja demonstracyjna oparta na Sinatra

Wymagania

Ruby 3.1 lub nowszy
Konto sprzedawcy Cost+ — dashboard.costplus.io

Instalacja

Dodaj do Gemfile:

gem "nopayn"

Następnie uruchom:

bundle install

Lub zainstaluj bezpośrednio:

gem install nopayn

Szybki start

1. Zainicjalizuj klienta

require "nopayn"

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

2. Utwórz płatność i przekieruj na HPP

result = nopayn.generate_payment_url(
  amount:            1295,           # 12,95 EUR w centach
  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"
)

# Przekieruj klienta
# result.order_url   → HPP (klient wybiera metodę płatności)
# result.payment_url → bezpośredni link do metody płatności pierwszej transakcji
# result.signature   → HMAC-SHA256 do weryfikacji
# result.order_id    → UUID zamówienia NoPayn

3. Obsłuż webhook

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

  verified = nopayn.verify_webhook(raw_body)

  puts verified.order.status  # "completed", "cancelled", itp.
  puts verified.is_final      # true gdy zamówienie się nie zmieni

  if verified.order.status == "completed"
    # Zrealizuj zamówienie
  end

  status 200
end

Dokumentacja API

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

Parametr	Typ	Wymagany	Domyślnie
`api_key`	`String`	Tak	—
`merchant_id`	`String`	Tak	—
`base_url`	`String`	Nie	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Tworzy zamówienie przez POST /v1/orders/.

Parametr	Typ	Wymagany	Opis
`:amount`	`Integer`	Tak	Kwota w najmniejszej jednostce waluty (centy)
`:currency`	`String`	Tak	Kod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Nie	Twoja wewnętrzna referencja zamówienia
`:description`	`String`	Nie	Opis zamówienia
`:return_url`	`String`	Nie	Przekierowanie po pomyślnej płatności
`:failure_url`	`String`	Nie	Przekierowanie przy anulowaniu/wygaśnięciu/błędzie
`:webhook_url`	`String`	Nie	Asynchroniczne powiadomienia o zmianie statusu
`:locale`	`String`	Nie	Język HPP (`en-GB`, `de-DE`, `nl-NL`, itp.)
`:payment_methods`	`Array<String>`	Nie	Filtruj metody HPP
`:expiration_period`	`String`	Nie	Czas trwania ISO 8601 (`PT30M`)

Dostępne metody płatności: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Pobiera szczegóły zamówienia przez GET /v1/orders/{id}/.

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

Dokonuje pełnego lub częściowego zwrotu przez POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Metoda pomocnicza, która tworzy zamówienie i zwraca:

result.order_id     # UUID zamówienia NoPayn
result.order_url    # URL HPP
result.payment_url  # Bezpośredni URL płatności (pierwsza transakcja)
result.signature    # HMAC-SHA256 z amount:currency:order_id
result.order        # Pełny obiekt zamówienia OpenStruct

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

Generuje podpis HMAC-SHA256 w formacie hex.

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

Weryfikacja HMAC-SHA256 w stałym czasie.

`client.verify_webhook(raw_body) -> OpenStruct`

Parsuje treść webhooka, następnie wywołuje GET /v1/orders/{id}/, aby zweryfikować rzeczywisty status.

Samodzielne narzędzia HMAC

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)

Obsługa błędów

begin
  nopayn.create_order(amount: 100, currency: "EUR")
rescue NoPayn::ApiError => e
  puts e.status_code  # 401, 400, itp.
  puts e.error_body   # Surowa odpowiedź błędu API
rescue NoPayn::Error => e
  puts e.message      # Błąd sieci lub parsowania
end

Wyjątek	Rodzic	Opis
`NoPayn::Error`	`StandardError`	Bazowy błąd dla wszystkich błędów SDK
`NoPayn::ApiError`	`NoPayn::Error`	Błąd HTTP z API
`NoPayn::WebhookError`	`NoPayn::Error`	Nieprawidłowa treść webhooka

Statusy zamówień

Status	Końcowy?	Opis
`new`	Nie	Zamówienie utworzone
`processing`	Nie	Płatność w toku
`completed`	Tak	Płatność zakończona sukcesem — wydaj towar
`cancelled`	Tak	Płatność anulowana przez klienta
`expired`	Tak	Link płatności wygasł
`error`	Tak	Błąd techniczny

Najlepsze praktyki dotyczące webhooków

Zawsze weryfikuj przez API — treść webhooka zawiera tylko identyfikator zamówienia, nigdy status. verify_webhook SDK robi to automatycznie.
Zwracaj HTTP 200, aby potwierdzić odbiór. Każdy inny kod powoduje do 10 ponowień (co 2 minuty).
Zaimplementuj zapasowe odpytywanie — dla zamówień starszych niż 10 minut, które nie osiągnęły końcowego statusu, odpytuj get_order jako zabezpieczenie.
Bądź idempotentny — możesz otrzymać ten sam webhook wielokrotnie.

Karty testowe

Użyj tych kart w trybie testowym Cost+ (strona testowa):

Karta	Numer	Uwagi
Visa (sukces)	`4111 1111 1111 1111`	Dowolny CVV
Mastercard (sukces)	`5544 3300 0003 7`	Dowolny CVV
Visa (odrzucona)	`4111 1111 1111 1105`	Do Not Honor
Visa (brak środków)	`4111 1111 1111 1151`	Insufficient Funds

Użyj dowolnej przyszłej daty ważności i dowolnego 3-cyfrowego CVC.

Aplikacja demonstracyjna

Aplikacja demonstracyjna oparta na Sinatra jest dołączona w repozytorium GitHub do testowania pełnego przepływu płatności.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

On this page