Cost+Docs

Ruby

Uradni Ruby SDK za plačilni prehod Cost+

Uradni Ruby SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.

Lastnosti

  • HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
  • Samodejno preslikavanje snake_case iz API-ja v Ruby-prijazne OpenStruct objekte
  • Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
  • Testirano na Ruby 3.1, 3.2 in 3.3
  • Vključena Sinatra predstavitvena trgovska aplikacija

Zahteve

Namestitev

Dodajte v vaš Gemfile:

gem "nopayn"

Nato zaženite:

bundle install

Ali namestite neposredno:

gem install nopayn

Hitri začetek

1. Inicializirajte odjemalca

require "nopayn"

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

2. Ustvarite plačilo in preusmerite 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"
)

# Preusmerite stranko
# result.order_url   → HPP (stranka izbere plačilno metodo)
# result.payment_url → neposredna povezava do plačilne metode prve transakcije
# result.signature   → HMAC-SHA256 za preverjanje
# result.order_id    → NoPayn UUID naročila

3. Obdelajte 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"
    # Izpolnite naročilo
  end

  status 200
end

API referenca

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

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

client.create_order(params) → OpenStruct

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
:amountIntegerjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
:currencyStringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringNeVaša interna referenca naročila
:descriptionStringNeOpis naročila
:return_urlStringNePreusmeritev po uspešnem plačilu
:failure_urlStringNePreusmeritev ob preklicu/poteku/napaki
:webhook_urlStringNeAsinhrona obvestila o spremembi statusa
:localeStringNeJezik HPP (en-GB, de-DE, nl-NL itd.)
:payment_methodsArray<String>NeFiltriraj metode HPP
:expiration_periodStringNeTrajanje ISO 8601 (PT30M)

Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) → OpenStruct

Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.

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

Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) → OpenStruct

Priročna metoda, ki ustvari naročilo in vrne:

result.order_id     # NoPayn UUID naročila
result.order_url    # HPP URL
result.payment_url  # Neposredni plačilni URL (prva transakcija)
result.signature    # HMAC-SHA256 od amount:currency:order_id
result.order        # Celoten objekt naročila OpenStruct

client.generate_signature(amount, currency, order_id) → String

Generira HMAC-SHA256 šestnajstiški podpis.

client.verify_signature(amount, currency, order_id, signature) → Boolean

Preverjanje HMAC-SHA256 podpisa s konstantnim časom.

client.verify_webhook(raw_body) → OpenStruct

Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.

Samostojne HMAC pripomočke

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)

Obravnava napak

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
IzjemaNadrazredOpis
NoPayn::ErrorStandardErrorOsnovna napaka za vse SDK napake
NoPayn::ApiErrorNoPayn::ErrorHTTP napaka iz API-ja
NoPayn::WebhookErrorNoPayn::ErrorNeveljaven koristni podatek webhook-a

Statusi naročil

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev verify_webhook to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte get_order kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna sredstva

Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.

Predstavitvena aplikacija

Predstavitvena aplikacija na osnovi Sinatra je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.

Podpora

Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.

On this page