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
- Ruby 3.1 jew aktar tard
- Kont ta' kummerċjant Cost+ — dashboard.costplus.io
Installazzjoni
Żid mal-Gemfile tiegħek:
gem "nopayn"Imbagħad mexxi:
bundle installJew installa direttament:
gem install nopaynBidu 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 NoPayn3. 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
endReferenza tal-API
NoPayn::Client.new(api_key:, merchant_id:, base_url:)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
api_key | String | Iva | — |
merchant_id | String | Iva | — |
base_url | String | Le | https://api.nopayn.co.uk |
client.create_order(params) -> OpenStruct
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
:amount | Integer | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
:currency | String | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
:merchant_order_id | String | Le | Ir-referenza interna tal-ordni tiegħek |
:description | String | Le | Deskrizzjoni tal-ordni |
:return_url | String | Le | Redirect wara ħlas li rnexxielu |
:failure_url | String | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
:webhook_url | String | Le | Notifiki asinkroni ta' bidla fl-istatus |
:locale | String | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
:payment_methods | Array<String> | Le | Iffiltra l-metodi tal-HPP |
:expiration_period | String | Le | Tul 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-ordniclient.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 | Ġenitur | Deskrizzjoni |
|---|---|---|
NoPayn::Error | StandardError | Żball bażi għall-iżbalji kollha tal-SDK |
NoPayn::ApiError | NoPayn::Error | Żball HTTP mill-API |
NoPayn::WebhookError | NoPayn::Error | Payload tal-webhook invalidu |
Statuses tal-Ordni
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-
verify_webhooktal-SDK jagħmel dan awtomatikament. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta'
get_orderbħala xibka ta' sigurtà. - 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):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient 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.