Ruby

Offisiell Ruby SDK for Cost+ betalingsgateway. Forenkler HPP (Hosted Payment Page) videresendingsflyten, HMAC-signering av innhold og webhook-verifisering.

Funksjoner

HMAC-SHA256 signaturgenerering og konstanttids-verifisering
Automatisk snake_case-kartlegging fra API til Ruby-vennlige OpenStruct-objekter
Webhook-parsing + API-basert ordreverifisering
Testet på tvers av Ruby 3.1, 3.2 og 3.3
Sinatra-basert demoforhandlerapp inkludert

Krav

Ruby 3.1 eller nyere
En Cost+ forhandlerkonto — dashboard.costplus.io

Installasjon

Legg til i Gemfile:

gem "nopayn"

Kjør deretter:

bundle install

Eller installer direkte:

gem install nopayn

Hurtigstart

1. Initialiser klienten

require "nopayn"

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

2. Opprett en betaling og videresend til 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 UUID

3. Håndter webhooken

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

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

Parameter	Type	Påkrevd	Standard
`api_key`	`String`	Ja	—
`merchant_id`	`String`	Ja	—
`base_url`	`String`	Nei	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Oppretter en ordre via POST /v1/orders/.

Parameter	Type	Påkrevd	Beskrivelse
`:amount`	`Integer`	Ja	Beløp i minste valutaenhet (øre/cent)
`:currency`	`String`	Ja	ISO 4217-kode (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Nei	Din interne ordrereferanse
`:description`	`String`	Nei	Ordrebeskrivelse
`:return_url`	`String`	Nei	Videresending etter vellykket betaling
`:failure_url`	`String`	Nei	Videresending ved avbrudd/utløp/feil
`:webhook_url`	`String`	Nei	Asynkrone statusendringsvarsler
`:locale`	`String`	Nei	HPP-språk (`en-GB`, `de-DE`, `nl-NL`, osv.)
`:payment_methods`	`Array<String>`	Nei	Filtrer HPP-metoder
`:expiration_period`	`String`	Nei	ISO 8601-varighet (`PT30M`)

Tilgjengelige betalingsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Henter ordredetaljer via GET /v1/orders/{id}/.

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

Utsteder en full eller delvis refusjon via POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Bekvemmelighetsmetode som oppretter en ordre og returnerer:

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`

Genererer en HMAC-SHA256 hex-signatur.

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

Konstanttids-verifisering av en HMAC-SHA256-signatur.

`client.verify_webhook(raw_body) -> OpenStruct`

Parser webhook-kroppen, kaller deretter GET /v1/orders/{id}/ for å verifisere faktisk status.

Frittstående HMAC-verktøy

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)

Feilhåndtering

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

Unntak	Forelder	Beskrivelse
`NoPayn::Error`	`StandardError`	Basisfeil for alle SDK-feil
`NoPayn::ApiError`	`NoPayn::Error`	HTTP-feil fra API-et
`NoPayn::WebhookError`	`NoPayn::Error`	Ugyldig webhook-innhold

Ordrestatuser

Status	Endelig?	Beskrivelse
`new`	Nei	Ordre opprettet
`processing`	Nei	Betaling pågår
`completed`	Ja	Betaling vellykket — lever varene
`cancelled`	Ja	Betaling avbrutt av kunden
`expired`	Ja	Betalingslenken utløp
`error`	Ja	Teknisk feil

Beste praksis for webhooks

Verifiser alltid via API-et — webhook-innholdet inneholder kun ordre-ID-en, aldri statusen. SDK-ens verify_webhook gjør dette automatisk.
Returner HTTP 200 for å bekrefte mottak. Enhver annen kode utløser opptil 10 nye forsøk (2 minutters mellomrom).
Implementer en reservepoller — for ordrer eldre enn 10 minutter som ikke har nådd en endelig status, poll get_order som sikkerhetsnett.
Vær idempotent — du kan motta samme webhook flere ganger.

Testkort

Bruk disse kortene i Cost+ testmodus (sandbox-nettsted):

Kort	Nummer	Merknader
Visa (vellykket)	`4111 1111 1111 1111`	Valgfritt CVV
Mastercard (vellykket)	`5544 3300 0003 7`	Valgfritt CVV
Visa (avvist)	`4111 1111 1111 1105`	Do Not Honor
Visa (utilstrekkelige midler)	`4111 1111 1111 1151`	Insufficient Funds

Bruk en hvilken som helst fremtidig utløpsdato og en hvilken som helst 3-sifret CVC.

Demoapp

En Sinatra-basert demoapp er inkludert i GitHub-repositoriet for testing av den fullstendige betalingsflyten.

Kundestøtte

Trenger du hjelp? Kontakt kundestøtteteamet vårt på support@costplus.io.

On this page