Ruby

Oficiālais Ruby SDK Cost+ maksājumu vārtejai. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.

Funkcijas

HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija
Automātiska snake_case kartēšana no API uz Ruby draudzīgiem OpenStruct objektiem
Webhook parsēšana + API bāzēta pasūtījuma verifikācija
Testēts Ruby 3.1, 3.2 un 3.3
Sinatra bāzēta demo tirgotāja lietotne iekļauta

Prasības

Ruby 3.1 vai jaunāka versija
Cost+ tirgotāja konts — dashboard.costplus.io

Instalācija

Pievienojiet savam Gemfile:

gem "nopayn"

Tad izpildiet:

bundle install

Vai instalējiet tieši:

gem install nopayn

Ātrais sākums

1. Inicializējiet klientu

require "nopayn"

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

2. Izveidojiet maksājumu un novirziet uz 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. Apstrādājiet 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 atsauce

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

Parametrs	Tips	Obligāts	Noklusējums
`api_key`	`String`	Jā	—
`merchant_id`	`String`	Jā	—
`base_url`	`String`	Nē	`https://api.nopayn.co.uk`

`client.create_order(params) -> OpenStruct`

Izveido pasūtījumu caur POST /v1/orders/.

Parametrs	Tips	Obligāts	Apraksts
`:amount`	`Integer`	Jā	Summa mazākajā valūtas vienībā (centos)
`:currency`	`String`	Jā	ISO 4217 kods (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`:merchant_order_id`	`String`	Nē	Jūsu iekšējā pasūtījuma atsauce
`:description`	`String`	Nē	Pasūtījuma apraksts
`:return_url`	`String`	Nē	Novirzīšana pēc veiksmīga maksājuma
`:failure_url`	`String`	Nē	Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
`:webhook_url`	`String`	Nē	Asinhroniem statusa izmaiņu paziņojumiem
`:locale`	`String`	Nē	HPP valoda (`en-GB`, `de-DE`, `nl-NL` utt.)
`:payment_methods`	`Array<String>`	Nē	Filtrēt HPP metodes
`:expiration_period`	`String`	Nē	ISO 8601 ilgums (`PT30M`)

Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.get_order(order_id) -> OpenStruct`

Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.

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

Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.

`client.generate_payment_url(params) -> OpenStruct`

Ērtuma metode, kas izveido pasūtījumu un atgriež:

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`

Ģenerē HMAC-SHA256 heksadecimālo parakstu.

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

Konstantā laika HMAC-SHA256 paraksta verifikācija.

`client.verify_webhook(raw_body) -> OpenStruct`

Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu.

Atsevišķās HMAC utilītas

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)

Kļūdu apstrāde

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

Izņēmums	Mantots no	Apraksts
`NoPayn::Error`	`StandardError`	Bāzes kļūda visām SDK kļūdām
`NoPayn::ApiError`	`NoPayn::Error`	HTTP kļūda no API
`NoPayn::WebhookError`	`NoPayn::Error`	Nederīgs webhook saturs

Pasūtījumu statusi

Statuss	Galīgs?	Apraksts
`new`	Nē	Pasūtījums izveidots
`processing`	Nē	Maksājums procesā
`completed`	Jā	Maksājums veiksmīgs — piegādājiet preci
`cancelled`	Jā	Maksājums atcelts klienta
`expired`	Jā	Maksājuma saites termiņš beidzies
`error`	Jā	Tehniska kļūme

Webhook labākā prakse

Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK verify_webhook to dara automātiski.
Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet get_order kā drošības tīklu.
Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.

Testa kartes

Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):

Karte	Numurs	Piezīmes
Visa (veiksmīgs)	`4111 1111 1111 1111`	Jebkurš CVV
Mastercard (veiksmīgs)	`5544 3300 0003 7`	Jebkurš CVV
Visa (noraidīts)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepietiekami līdzekļi)	`4111 1111 1111 1151`	Insufficient Funds

Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.

Demo lietotne

Sinatra bāzēta demo lietotne ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai.

Atbalsts

Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.

On this page