Ruby

Oficialus Ruby SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.

Savybės

HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
Automatinis snake_case atitikimas iš API į Ruby draugiškus OpenStruct objektus
Webhook analizė + API pagrįstas užsakymo patikrinimas
Testuota Ruby 3.1, 3.2 ir 3.3 versijose
Sinatra pagrįsta demonstracinė prekybininko programa įtraukta

Reikalavimai

Ruby 3.1 arba naujesnė
Cost+ prekybininko paskyra — dashboard.costplus.io

Diegimas

Pridėkite prie savo Gemfile:

gem "nopayn"

Tada paleiskite:

bundle install

Arba įdiekite tiesiogiai:

gem install nopayn

Greitas startas

1. Inicializuokite klientą

require "nopayn"

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

2. Sukurkite mokėjimą ir nukreipkite į 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. Apdorokite Webhook

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 nuoroda

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

Parametras	Tipas	Privalomas	Numatytasis
`api_key`	`String`	Taip	—
`merchant_id`	`String`	Taip	—
`base_url`	`String`	Ne	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Sukuria užsakymą per POST /v1/orders/.

Parametras	Tipas	Privalomas	Aprašymas
`:amount`	`Integer`	Taip	Suma mažiausiu valiutos vienetu (centais)
`:currency`	`String`	Taip	ISO 4217 kodas (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Ne	Jūsų vidinis užsakymo nuorodos ID
`:description`	`String`	Ne	Užsakymo aprašymas
`:return_url`	`String`	Ne	Nukreipimas po sėkmingo mokėjimo
`:failure_url`	`String`	Ne	Nukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju
`:webhook_url`	`String`	Ne	Asinchroniniai būsenos pakeitimo pranešimai
`:locale`	`String`	Ne	HPP kalba (`en-GB`, `de-DE`, `nl-NL` ir kt.)
`:payment_methods`	`Array<String>`	Ne	Filtruoti HPP mokėjimo būdus
`:expiration_period`	`String`	Ne	ISO 8601 trukmė (`PT30M`)

Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Gauna užsakymo detales per GET /v1/orders/{id}/.

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

Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Patogus metodas, kuris sukuria užsakymą ir grąžina:

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`

Generuoja HMAC-SHA256 hex parašą.

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

Pastovaus laiko HMAC-SHA256 parašo patikrinimas.

`client.verify_webhook(raw_body) -> OpenStruct`

Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną.

Atskiros HMAC priemonės

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)

Klaidų tvarkymas

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

Išimtis	Tėvinė	Aprašymas
`NoPayn::Error`	`StandardError`	Bazinė klaida visiems SDK klaidoms
`NoPayn::ApiError`	`NoPayn::Error`	HTTP klaida iš API
`NoPayn::WebhookError`	`NoPayn::Error`	Netinkamas webhook turinys

Užsakymo būsenos

Būsena	Galutinė?	Aprašymas
`new`	Ne	Užsakymas sukurtas
`processing`	Ne	Mokėjimas vykdomas
`completed`	Taip	Mokėjimas sėkmingas — pristatykite prekes
`cancelled`	Taip	Mokėjimas atšauktas kliento
`expired`	Taip	Mokėjimo nuorodos laikas baigėsi
`error`	Taip	Techninė klaida

Webhook geriausios praktikos

Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK verify_webhook tai atlieka automatiškai.
Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite get_order kaip saugos tinklą.
Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.

Testinės kortelės

Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):

Kortelė	Numeris	Pastabos
Visa (sėkminga)	`4111 1111 1111 1111`	Bet koks CVV
Mastercard (sėkminga)	`5544 3300 0003 7`	Bet koks CVV
Visa (atmesta)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepakankamos lėšos)	`4111 1111 1111 1151`	Insufficient Funds

Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.

Demonstracinė programa

Sinatra pagrįsta demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui.

Palaikymas

Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.

On this page