Ruby

Virallinen Ruby SDK Cost+-maksuportille. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus
Automaattinen snake_case-muunnos API:sta Ruby-ystävällisiin OpenStruct-objekteihin
Webhook-jäsennys + API-pohjainen tilauksen vahvistus
Testattu Ruby 3.1-, 3.2- ja 3.3-versioilla
Sinatra-pohjainen demokauppiassovellus sisältyy

Vaatimukset

Ruby 3.1 tai uudempi
Cost+-kauppiastili — dashboard.costplus.io

Asennus

Lisää Gemfileesi:

gem "nopayn"

Suorita sitten:

bundle install

Tai asenna suoraan:

gem install nopayn

Pikaopas

1. Alusta asiakas

require "nopayn"

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

2. Luo maksu ja ohjaa HPP:hen

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. Käsittele 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
end

API-viite

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

Parametri	Tyyppi	Pakollinen	Oletus
`api_key`	`String`	Kyllä	—
`merchant_id`	`String`	Kyllä	—
`base_url`	`String`	Ei	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Luo tilauksen kutsulla POST /v1/orders/.

Parametri	Tyyppi	Pakollinen	Kuvaus
`:amount`	`Integer`	Kyllä	Summa pienimmässä valuuttayksikössä (senteissä)
`:currency`	`String`	Kyllä	ISO 4217 -koodi (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Ei	Oma sisäinen tilausviitteesi
`:description`	`String`	Ei	Tilauksen kuvaus
`:return_url`	`String`	Ei	Uudelleenohjaus onnistuneen maksun jälkeen
`:failure_url`	`String`	Ei	Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
`:webhook_url`	`String`	Ei	Asynkroniset tilanmuutosilmoitukset
`:locale`	`String`	Ei	HPP:n kieli (`en-GB`, `de-DE`, `nl-NL` jne.)
`:payment_methods`	`Array<String>`	Ei	Suodata HPP:n maksutapoja
`:expiration_period`	`String`	Ei	ISO 8601 -kesto (`PT30M`)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

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

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Apumetodi, joka luo tilauksen ja palauttaa:

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`

Luo HMAC-SHA256 hex-allekirjoituksen.

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

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus.

`client.verify_webhook(raw_body) -> OpenStruct`

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan.

Erilliset HMAC-apufunktiot

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)

Virheenkäsittely

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

Poikkeus	Ylätaso	Kuvaus
`NoPayn::Error`	`StandardError`	Perusvirhe kaikille SDK-virheille
`NoPayn::ApiError`	`NoPayn::Error`	HTTP-virhe API:sta
`NoPayn::WebhookError`	`NoPayn::Error`	Virheellinen webhook-data

Tilausten tilat

Tila	Lopullinen?	Kuvaus
`new`	Ei	Tilaus luotu
`processing`	Ei	Maksu käynnissä
`completed`	Kyllä	Maksu onnistui — toimita tavarat
`cancelled`	Kyllä	Asiakas peruutti maksun
`expired`	Kyllä	Maksulinkki vanheni
`error`	Kyllä	Tekninen virhe

Webhook-parhaat käytännöt

Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n verify_webhook tekee tämän automaattisesti.
Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa get_order turvavarana.
Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

Kortti	Numero	Huomautukset
Visa (onnistunut)	`4111 1111 1111 1111`	Mikä tahansa CVV
Mastercard (onnistunut)	`5544 3300 0003 7`	Mikä tahansa CVV
Visa (hylätty)	`4111 1111 1111 1105`	Do Not Honor
Visa (riittämätön kate)	`4111 1111 1111 1151`	Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Sinatra-pohjainen demosovellus sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page