Cost+Docs

Ruby

SDK oifigiúil Ruby do gheata íocaíochta Cost+

SDK oifigiúil Ruby do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.

Gnéithe

  • Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
  • Mapáil uathoibríoch snake_case ón API go réada OpenStruct atá cairdiúil do Ruby
  • Parsáil webhook + fíorú ordaithe bunaithe ar API
  • Tástáilte ar fud Ruby 3.1, 3.2, agus 3.3
  • Aip thaispeána Sinatra-bhunaithe san áireamh

Riachtanais

Suiteáil

Cuir le do Gemfile:

gem "nopayn"

Ansin rith:

bundle install

Nó suiteáil go díreach:

gem install nopayn

Mearthosnú

1. Túsaigh an Cliant

require "nopayn"

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

2. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an 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

Tagairt API

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

ParaiméadarCineálRiachtanachRéamhshocrú
api_keyStringTá--
merchant_idStringTá--
base_urlStringNílhttps://api.nopayn.co.uk

client.create_order(params) -> OpenStruct

Cruthaíonn ordú tríd an POST /v1/orders/.

ParaiméadarCineálRiachtanachCur Síos
:amountIntegerTáMéid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR)
:currencyStringTáCód ISO 4217 (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringNílDo thagairt inmheánach ordaithe
:descriptionStringNílCur síos ar an ordú
:return_urlStringNílAtreorú tar éis íocaíochta rathúla
:failure_urlStringNílAtreorú ar cheallú/éag/earráid
:webhook_urlStringNílFógraí athraithe stádais asincrónach
:localeStringNílTeanga HPP (en-GB, de-DE, nl-NL, srl.)
:payment_methodsArray<String>NílScag modhanna HPP
:expiration_periodStringNílFad ISO 8601 (PT30M)

Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> OpenStruct

Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.

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

Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.

client.generate_payment_url(params) -> OpenStruct

Modh áise a chruthaíonn ordú agus a sheolann ar ais:

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

Gineann síniú HMAC-SHA256 hex.

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

Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256.

client.verify_webhook(raw_body) -> OpenStruct

Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú.

Fóntais HMAC Neamhspleácha

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)

Láimhseáil Earráidí

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
EisceachtTuismitheoirCur Síos
NoPayn::ErrorStandardErrorBunearráid do gach earráid SDK
NoPayn::ApiErrorNoPayn::ErrorEarráid HTTP ón API
NoPayn::WebhookErrorNoPayn::ErrorSonraí webhook neamhbhailí

Stádais Ordaithe

StádasDeiridh?Cur Síos
newNílOrdú cruthaithe
processingNílÍocaíocht ar siúl
completedTáD'éirigh leis an íocaíocht -- seachaid na hearraí
cancelledTáCheal an custaiméir an íocaíocht
expiredTáD'éag an nasc íocaíochta
errorTáTeip theicniúil

Dea-Chleachtais Webhook

  1. Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann verify_webhook an SDK é seo go huathoibríoch.
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
  3. Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail get_order mar líontán sábháilteachta.
  4. Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.

Cártaí Tástála

Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):

CártaUimhirNótaí
Visa (rath)4111 1111 1111 1111Aon CVV
Mastercard (rath)5544 3300 0003 7Aon CVV
Visa (diúltaithe)4111 1111 1111 1105Do Not Honor
Visa (cistí neamhleor)4111 1111 1111 1151Insufficient Funds

Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.

Aip Thaispeána

Tá aip thaispeána Sinatra-bhunaithe san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil.

Tacaíocht

Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.

On this page