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
- Ruby 3.1 ali novejši
- Trgovski račun Cost+ — dashboard.costplus.io
Namestitev
Dodajte v vaš Gemfile:
gem "nopayn"Nato zaženite:
bundle installAli namestite neposredno:
gem install nopaynHitri 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čila3. 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
endAPI referenca
NoPayn::Client.new(api_key:, merchant_id:, base_url:)
| Parameter | Tip | Obvezno | Privzeto |
|---|---|---|---|
api_key | String | Da | — |
merchant_id | String | Da | — |
base_url | String | Ne | https://api.nopayn.co.uk |
client.create_order(params) → OpenStruct
Ustvari naročilo prek POST /v1/orders/.
| Parameter | Tip | Obvezno | Opis |
|---|---|---|---|
:amount | Integer | ja | Znesek v manjši enoti ISO 4217 valute (na primer centi za EUR) |
:currency | String | Da | Koda ISO 4217 (EUR, GBP, USD, NOK, SEK) |
:merchant_order_id | String | Ne | Vaša interna referenca naročila |
:description | String | Ne | Opis naročila |
:return_url | String | Ne | Preusmeritev po uspešnem plačilu |
:failure_url | String | Ne | Preusmeritev ob preklicu/poteku/napaki |
:webhook_url | String | Ne | Asinhrona obvestila o spremembi statusa |
:locale | String | Ne | Jezik HPP (en-GB, de-DE, nl-NL itd.) |
:payment_methods | Array<String> | Ne | Filtriraj metode HPP |
:expiration_period | String | Ne | Trajanje 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 OpenStructclient.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| Izjema | Nadrazred | Opis |
|---|---|---|
NoPayn::Error | StandardError | Osnovna napaka za vse SDK napake |
NoPayn::ApiError | NoPayn::Error | HTTP napaka iz API-ja |
NoPayn::WebhookError | NoPayn::Error | Neveljaven koristni podatek webhook-a |
Statusi naročil
| Status | Končni? | Opis |
|---|---|---|
new | Ne | Naročilo ustvarjeno |
processing | Ne | Plačilo v teku |
completed | Da | Plačilo uspešno — dostavite blago |
cancelled | Da | Plačilo preklicano s strani stranke |
expired | Da | Plačilna povezava je potekla |
error | Da | Tehnična napaka |
Najboljše prakse za webhook-e
- Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev
verify_webhookto naredi samodejno. - Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
- Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte
get_orderkot varnostno mrežo. - Bodite idempotentni — isti webhook lahko prejmete večkrat.
Testne kartice
Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):
| Kartica | Številka | Opombe |
|---|---|---|
| Visa (uspeh) | 4111 1111 1111 1111 | Katerikoli CVV |
| Mastercard (uspeh) | 5544 3300 0003 7 | Katerikoli CVV |
| Visa (zavrnjena) | 4111 1111 1111 1105 | Zavrnitev |
| Visa (nezadostna sredstva) | 4111 1111 1111 1151 | Nezadostna 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.