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
- Ruby 3.1 ili noviji
- Cost+ trgovački račun — dashboard.costplus.io
Instalacija
Dodajte u vaš Gemfile:
gem "nopayn"Zatim pokrenite:
bundle installIli instalirajte izravno:
gem install nopaynBrzi 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 UUID3. 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
endAPI referenca
NoPayn::Client.new(api_key:, merchant_id:, base_url:)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
api_key | String | Da | — |
merchant_id | String | Da | — |
base_url | String | Ne | https://api.nopayn.co.uk |
client.create_order(params) -> OpenStruct
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
:amount | Integer | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
:currency | String | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
:merchant_order_id | String | Ne | Vaša interna referenca narudžbe |
:description | String | Ne | Opis narudžbe |
:return_url | String | Ne | Preusmjeravanje nakon uspješnog plaćanja |
:failure_url | String | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
:webhook_url | String | Ne | Asinkrone obavijesti o promjeni statusa |
:locale | String | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
:payment_methods | Array<String> | Ne | Filtriranje HPP načina |
:expiration_period | String | Ne | ISO 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 OpenStructclient.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| Iznimka | Roditelj | Opis |
|---|---|---|
NoPayn::Error | StandardError | Bazna greška za sve SDK greške |
NoPayn::ApiError | NoPayn::Error | HTTP greška iz API-ja |
NoPayn::WebhookError | NoPayn::Error | Nevaljani webhook podaci |
Statusi narudžbe
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
verify_webhookto radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
get_orderkao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient 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.