Cost+Docs

Ruby

SDK uffiċjali ta' Ruby għall-gateway tal-ħlas Cost+

SDK uffiċjali ta' Ruby għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.

Karatteristiċi

  • Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
  • Mappa awtomatika ta' snake_case mill-API għal oġġetti OpenStruct kompatibbli ma' Ruby
  • Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
  • Ittestjat fuq Ruby 3.1, 3.2, u 3.3
  • App demo tal-kummerċjant bbażata fuq Sinatra inkluża

Rekwiżiti

Installazzjoni

Żid mal-Gemfile tiegħek:

gem "nopayn"

Imbagħad mexxi:

bundle install

Jew installa direttament:

gem install nopayn

Bidu Malajr

1. Inizjalizza l-Klijent

require "nopayn"

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

2. Oħloq Ħlas u Irridirezzjona lejn il-HPP

result = nopayn.generate_payment_url(
  amount:            1295,           # €12.95 f'ċenteżmi
  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"
)

# Irridirezzjona l-klijent
# result.order_url   → HPP (il-klijent jagħżel il-metodu ta' ħlas)
# result.payment_url → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
# result.signature   → HMAC-SHA256 għall-verifika
# result.order_id    → UUID tal-ordni NoPayn

3. Ittratta l-Webhook

post "/webhook" do
  request.body.rewind
  raw_body = request.body.read

  verified = nopayn.verify_webhook(raw_body)

  puts verified.order.status  # "completed", "cancelled", eċċ.
  puts verified.is_final      # true meta l-ordni ma tinbidilx aktar

  if verified.order.status == "completed"
    # Issodisfa l-ordni
  end

  status 200
end

Referenza tal-API

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

ParametruTipMeħtieġDefault
api_keyStringIva—
merchant_idStringIva—
base_urlStringLehttps://api.nopayn.co.uk

client.create_order(params) -> OpenStruct

Joħloq ordni permezz ta' POST /v1/orders/.

ParametruTipMeħtieġDeskrizzjoni
:amountIntegerIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
:currencyStringIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringLeIr-referenza interna tal-ordni tiegħek
:descriptionStringLeDeskrizzjoni tal-ordni
:return_urlStringLeRedirect wara ħlas li rnexxielu
:failure_urlStringLeRedirect fuq kanċellazzjoni/skadenza/żball
:webhook_urlStringLeNotifiki asinkroni ta' bidla fl-istatus
:localeStringLeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
:payment_methodsArray<String>LeIffiltra l-metodi tal-HPP
:expiration_periodStringLeTul ta' żmien ISO 8601 (PT30M)

Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.

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

Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) -> OpenStruct

Metodu ta' konvenjenza li joħloq ordni u jirritorna:

result.order_id     # UUID tal-ordni NoPayn
result.order_url    # URL tal-HPP
result.payment_url  # URL ta' ħlas dirett (l-ewwel tranżazzjoni)
result.signature    # HMAC-SHA256 ta' amount:currency:order_id
result.order        # OpenStruct sħiħ tal-ordni

client.generate_signature(amount, currency, order_id) -> String

Jiġġenera firma HMAC-SHA256 hex.

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

Verifika b'ħin kostanti ta' firma HMAC-SHA256.

client.verify_webhook(raw_body) -> OpenStruct

Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali.

Utilitajiet HMAC Standalone

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)

Trattar tal-Żbalji

begin
  nopayn.create_order(amount: 100, currency: "EUR")
rescue NoPayn::ApiError => e
  puts e.status_code  # 401, 400, eċċ.
  puts e.error_body   # Risposta ta' żball mhux ipproċessata tal-API
rescue NoPayn::Error => e
  puts e.message      # Żball tan-network jew tal-ipparsjar
end
EċċezzjoniĠeniturDeskrizzjoni
NoPayn::ErrorStandardErrorŻball bażi għall-iżbalji kollha tal-SDK
NoPayn::ApiErrorNoPayn::ErrorŻball HTTP mill-API
NoPayn::WebhookErrorNoPayn::ErrorPayload tal-webhook invalidu

Statuses tal-Ordni

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-verify_webhook tal-SDK jagħmel dan awtomatikament.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta' get_order bħala xibka ta' sigurtà.
  4. Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.

Karti tat-Test

Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient Funds

Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.

App Demo

App demo bbażata fuq Sinatra hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas.

Appoġġ

Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.

On this page