Cost+Docs

Ruby

Službeni Ruby SDK za Cost+ platni pristupnik

Službeni Ruby SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
  • Automatsko snake_case mapiranje iz API-ja u Ruby-friendly OpenStruct objekte
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Testirano na Ruby 3.1, 3.2 i 3.3
  • Sinatra-bazirana demo trgovačka aplikacija uključena

Zahtjevi

Instalacija

Dodajte u vaš Gemfile:

gem "nopayn"

Zatim pokrenite:

bundle install

Ili instalirajte izravno:

gem install nopayn

Brzi početak

1. Inicijalizirajte klijent

require "nopayn"

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

2. Stvorite plaćanje i preusmjerite 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. Obradite 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 referenca

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

ParametarTipObaveznoZadano
api_keyStringDa—
merchant_idStringDa—
base_urlStringNehttps://api.nopayn.co.uk

client.create_order(params) -> OpenStruct

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
:amountIntegerDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
:currencyStringDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringNeVaša interna referenca narudžbe
:descriptionStringNeOpis narudžbe
:return_urlStringNePreusmjeravanje nakon uspješnog plaćanja
:failure_urlStringNePreusmjeravanje pri poništenju/isteku/grešci
:webhook_urlStringNeAsinkrone obavijesti o promjeni statusa
:localeStringNeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
:payment_methodsArray<String>NeFiltriranje HPP načina
:expiration_periodStringNeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

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

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) -> OpenStruct

Praktična metoda koja stvara narudžbu i vraća:

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

Generira HMAC-SHA256 heksadecimalni potpis.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.

client.verify_webhook(raw_body) -> OpenStruct

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.

Samostalni HMAC alati

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)

Rukovanje greškama

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
IznimkaRoditeljOpis
NoPayn::ErrorStandardErrorBazna greška za sve SDK greške
NoPayn::ApiErrorNoPayn::ErrorHTTP greška iz API-ja
NoPayn::WebhookErrorNoPayn::ErrorNevaljani webhook podaci

Statusi narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov verify_webhook to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte get_order kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Sinatra-bazirana demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page