Ruby
Официално Ruby SDK за разплащателния шлюз Cost+
Официално Ruby SDK за разплащателния шлюз Cost+. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.
Характеристики
- HMAC-SHA256 генериране на подписи и верификация с постоянно време
- Автоматично snake_case съответствие от API към Ruby-friendly OpenStruct обекти
- Анализиране на уебхукове + верификация на поръчки, базирана на API
- Тествано с Ruby 3.1, 3.2 и 3.3
- Включено демо търговско приложение, базирано на Sinatra
Изисквания
- Ruby 3.1 или по-нова версия
- Търговски акаунт в Cost+ — dashboard.costplus.io
Инсталация
Добавете към вашия Gemfile:
gem "nopayn"След което изпълнете:
bundle installИли инсталирайте директно:
gem install nopaynБързо начало
1. Инициализиране на клиента
require "nopayn"
nopayn = NoPayn::Client.new(
api_key: "your-api-key",
merchant_id: "your-project"
)2. Създаване на плащане и пренасочване към 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 UUID3. Обработка на уебхука
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
endAPI справочник
NoPayn::Client.new(api_key:, merchant_id:, base_url:)
| Параметър | Тип | Задължителен | По подразбиране |
|---|---|---|---|
api_key | String | Да | — |
merchant_id | String | Да | — |
base_url | String | Не | https://api.nopayn.co.uk |
client.create_order(params) -> OpenStruct
Създава поръчка чрез POST /v1/orders/.
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
:amount | Integer | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
:currency | String | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
:merchant_order_id | String | Не | Ваш вътрешен идентификатор на поръчка |
:description | String | Не | Описание на поръчката |
:return_url | String | Не | Пренасочване след успешно плащане |
:failure_url | String | Не | Пренасочване при отказ/изтичане/грешка |
:webhook_url | String | Не | Асинхронни известия за промяна на статуса |
:locale | String | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
:payment_methods | Array<String> | Не | Филтриране на HPP методи |
:expiration_period | String | Не | ISO 8601 продължителност (PT30M) |
Налични методи на плащане: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> OpenStruct
Извлича детайли на поръчка чрез GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description: nil) -> OpenStruct
Издава пълно или частично възстановяване чрез POST /v1/orders/{id}/refunds/.
client.generate_payment_url(params) -> OpenStruct
Удобен метод, който създава поръчка и връща:
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 OpenStructclient.generate_signature(amount, currency, order_id) -> String
Генерира HMAC-SHA256 шестнадесетичен подпис.
client.verify_signature(amount, currency, order_id, signature) -> Boolean
Верификация с постоянно време на HMAC-SHA256 подпис.
client.verify_webhook(raw_body) -> OpenStruct
Анализира тялото на уебхука, след което извиква GET /v1/orders/{id}/, за да провери действителния статус.
Самостоятелни HMAC помощни функции
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)Обработка на грешки
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| Изключение | Родител | Описание |
|---|---|---|
NoPayn::Error | StandardError | Базова грешка за всички SDK грешки |
NoPayn::ApiError | NoPayn::Error | HTTP грешка от API-то |
NoPayn::WebhookError | NoPayn::Error | Невалидни данни от уебхук |
Статуси на поръчки
| Статус | Финален? | Описание |
|---|---|---|
new | Не | Поръчката е създадена |
processing | Не | Плащането е в ход |
completed | Да | Плащането е успешно — доставете стоката |
cancelled | Да | Плащането е отменено от клиента |
expired | Да | Линкът за плащане е изтекъл |
error | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
verify_webhookна SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
get_orderкато мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):
| Карта | Номер | Бележки |
|---|---|---|
| Visa (успех) | 4111 1111 1111 1111 | Произволен CVV |
| Mastercard (успех) | 5544 3300 0003 7 | Произволен CVV |
| Visa (отхвърлена) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (недостатъчни средства) | 4111 1111 1111 1151 | Insufficient Funds |
Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.
Демо приложение
Демо приложение, базирано на Sinatra, е включено в GitHub хранилището за тестване на пълния поток на плащане.
Поддръжка
Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.