Ruby

Ametlik Ruby SDK Cost+ makselüüsi jaoks. Lihtsustab HPP (hostitud makselehe) ümbersuunamise voogu, HMAC andmete allkirjastamist ja veebihaagi kontrollimist.

Funktsioonid

HMAC-SHA256 allkirja genereerimine ja konstantse aja kontrollimine
Automaatne snake_case vastendamine API-st Ruby-sõbralikeks OpenStruct objektideks
Veebihaagi parsimine + API-põhine tellimuse kontrollimine
Testitud Ruby 3.1, 3.2 ja 3.3 peal
Sinatral põhinev demo-kaupmehe rakendus kaasas

Nõuded

Ruby 3.1 või uuem
Cost+ kaupmehe konto — dashboard.costplus.io

Paigaldamine

Lisage oma Gemfile'i:

gem "nopayn"

Seejärel käivitage:

bundle install

Või paigaldage otse:

gem install nopayn

Kiirstart

1. Kliendi initsialiseerimine

require "nopayn"

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

2. Makse loomine ja HPP-le suunamine

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. Veebihaagi käsitlemine

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 viide

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

Parameeter	Tüüp	Kohustuslik	Vaikeväärtus
`api_key`	`String`	Jah	—
`merchant_id`	`String`	Jah	—
`base_url`	`String`	Ei	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Loob tellimuse päringuga POST /v1/orders/.

Parameeter	Tüüp	Kohustuslik	Kirjeldus
`:amount`	`Integer`	Jah	Summa väikseimas valuutaühikus (sendid)
`:currency`	`String`	Jah	ISO 4217 kood (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Ei	Teie sisemine tellimuse viide
`:description`	`String`	Ei	Tellimuse kirjeldus
`:return_url`	`String`	Ei	Ümbersuunamine pärast edukat makset
`:failure_url`	`String`	Ei	Ümbersuunamine tühistamise/aegumise/vea korral
`:webhook_url`	`String`	Ei	Asünkroonsed olekumuutuse teavitused
`:locale`	`String`	Ei	HPP keel (`en-GB`, `de-DE`, `nl-NL` jne)
`:payment_methods`	`Array<String>`	Ei	HPP meetodite filtreerimine
`:expiration_period`	`String`	Ei	ISO 8601 kestvus (`PT30M`)

Saadaolevad makseviisid: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Pärib tellimuse üksikasjad päringuga GET /v1/orders/{id}/.

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

Teeb täieliku või osalise tagasimakse päringuga POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Abimeetod, mis loob tellimuse ja tagastab:

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`

Genereerib HMAC-SHA256 hex allkirja.

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

Konstantse aja HMAC-SHA256 allkirja kontrollimine.

`client.verify_webhook(raw_body) -> OpenStruct`

Parsib veebihaagi keha, seejärel kutsub GET /v1/orders/{id}/, et kontrollida tegelikku olekut.

Eraldiseisvad HMAC utiliidid

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)

Veakäsitlus

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

Erand	Vanem	Kirjeldus
`NoPayn::Error`	`StandardError`	Baasviga kõigi SDK vigade jaoks
`NoPayn::ApiError`	`NoPayn::Error`	HTTP viga API-st
`NoPayn::WebhookError`	`NoPayn::Error`	Vigane veebihaagi andmepakk

Tellimuse olekud

Olek	Lõplik?	Kirjeldus
`new`	Ei	Tellimus loodud
`processing`	Ei	Makse pooleli
`completed`	Jah	Makse edukas — tarnige kaup
`cancelled`	Jah	Makse tühistatud kliendi poolt
`expired`	Jah	Makselink aegunud
`error`	Jah	Tehniline tõrge

Veebihaagi parimad tavad

Kontrollige alati API kaudu — veebihaagi andmed sisaldavad ainult tellimuse ID-d, mitte kunagi olekut. SDK verify_webhook teeb seda automaatselt.
Tagastage HTTP 200 kättesaamise kinnitamiseks. Iga muu kood käivitab kuni 10 korduskatset (2 minuti vahega).
Rakendage varuküsitleja — tellimuste jaoks, mis on vanemad kui 10 minutit ja pole jõudnud lõppolekusse, küsitlege get_order turvavõrguna.
Olge idempotentne — võite sama veebihaagi saada mitu korda.

Testkaardid

Kasutage neid kaarte Cost+ testrežiimis (liivakasti veebileht):

Kaart	Number	Märkused
Visa (edukas)	`4111 1111 1111 1111`	Suvaline CVV
Mastercard (edukas)	`5544 3300 0003 7`	Suvaline CVV
Visa (keeldutud)	`4111 1111 1111 1105`	Do Not Honor
Visa (ebapiisav saldo)	`4111 1111 1111 1151`	Insufficient Funds

Kasutage suvalist tulevast aegumiskuupäeva ja suvalist 3-kohalist CVC-d.

Demorakendus

Sinatral põhinev demorakendus on kaasas GitHub hoidlas täieliku maksevoo testimiseks.

Tugi

Vajate abi? Võtke ühendust meie tugimeeskonnaga aadressil support@costplus.io.

On this page