Ruby

Opinbert Ruby SDK fyrir greiðslugátt Cost+. Poenostavlja tok preusmeritve HPP (gostovane greiðslune strani), HMAC podpisovanje koristnih podatkov og staðfesting webhook-ov.

Eiginleikar

HMAC-SHA256 býr tilnje podpisov og staðfesting með konstantnim časom
Samodejno preslikavanje snake_case iz API-ja í Ruby-prijazne OpenStruct objekte
Razčlenjevanje webhook-ov + staðfesting pantana á osnovi API-ja
Prófað á Ruby 3.1, 3.2 og 3.3
Vključena Sinatra predstavitvena trgovska aplikacija

Kröfur

Ruby 3.1 eða nýrri
Söluaðilareikningur Cost+ — dashboard.costplus.io

Uppsetning

Dodajte í þinn Gemfile:

gem "nopayn"

Nato keyrðu:

bundle install

Ali settu upp neposredno:

gem install nopayn

Flýtiræsing

1. Frumstilltu biðlarann

require "nopayn"

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

2. Ustvarite greiðsla og preusmerite á HPP

result = nopayn.generate_payment_url(
  amount:            1295,           # €12.95 og 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 viðskiptavin
# result.order_url   → HPP (viðskiptavinur izbere greiðslumáta)
# result.payment_url → neposredna povezava do greiðslumátar prve transakcije
# result.signature   → HMAC-SHA256 til staðfesting
# result.order_id    → NoPayn UUID pantanir

3. Meðhöndlaðu 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"
    # Uppfylldu pöntunina
  end

  status 200
end

API tilvísun

`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`

Stofnar pöntun gegnum POST /v1/orders/.

Parameter	Tip	Obvezno	Opis
`:amount`	`Integer`	Da	Znesek í najmanjši valutni enoti (centi)
`:currency`	`String`	Da	Koda ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Ne	Vaša interna referenca pantanir
`:description`	`String`	Ne	Opis pantanir
`:return_url`	`String`	Ne	Preusmeritev eftir uspešnem greiðsluu
`: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`)

Tiltækir greiðslumátar: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) → OpenStruct`

Sækir upplýsingar pöntunar gegnum GET /v1/orders/{id}/.

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

Gefðu út fulla eða hluta endurgreiðslu gegnum POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) → OpenStruct`

Þægileg aðferð, ki ustvari pöntun og vrne:

result.order_id     # NoPayn UUID pantanir
result.order_url    # HPP URL
result.payment_url  # Neposredni greiðsluni URL (prva transakcija)
result.signature    # HMAC-SHA256 od amount:currency:order_id
result.order        # Celoten objekt pantanir OpenStruct

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

Býr til HMAC-SHA256 šestnajstiški podpis.

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

Staðfesting HMAC-SHA256 podpisa með konstantnim časom.

`client.verify_webhook(raw_body) → OpenStruct`

Greinir telo webhook-a, nato poklief GET /v1/orders/{id}/ til staðfesting dejanskega statusa.

Sjálfstæð HMAC tól

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)

Villum meðhöndlun

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 til öll SDK napake
`NoPayn::ApiError`	`NoPayn::Error`	HTTP napaka iz API-ja
`NoPayn::WebhookError`	`NoPayn::Error`	Neveljaven koristni podatek webhook-a

Statusi pantana

Status	Končni?	Opis
`new`	Ne	Pöntun ustvarjeno
`processing`	Ne	Greiðsla í teku
`completed`	Da	Greiðsla uspešno — dostavite blago
`cancelled`	Da	Greiðsla preklicano með strani viðskiptavinar
`expired`	Da	Plačilna povezava er potekla
`error`	Da	Tehnična napaka

Bestu venjur fyrir webhook-a

Vedno preverite gegnum API-ja — koristni podatki webhook-a vsebujejo aðeins ID pantanir, nikoli statusa. SDK-jev verify_webhook to naredi samodejno.
Vrnite HTTP 200 til potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
Implementirajte rezervno poizvedovanje — til pantanir, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte get_order kot varnostno mrežo.
Vertu idempotent — isti webhook lahþegar prejmete večkrat.

Prófunarkort

Uporabite te kartice í testnem načinu Cost+ (vefsíðu sandboxa):

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 og katerokoli 3-mestno CVC kodo.

Sýnisforrit

Sýnisforrit á osnovi Sinatra er vključena í GitHub repozitorij til testiranje celotnega greiðslunega toka.

Aðstoð

Þarftu aðstoð? Hafðu samband við þjónustudeild okkar á support@costplus.io.

On this page