Cost+Docs

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 UUID

3. Обработка на уебхука

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 справочник

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

ПараметърТипЗадължителенПо подразбиране
api_keyStringДа—
merchant_idStringДа—
base_urlStringНеhttps://api.nopayn.co.uk

client.create_order(params) -> OpenStruct

Създава поръчка чрез POST /v1/orders/.

ПараметърТипЗадължителенОписание
:amountIntegerдаСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
:currencyStringДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
:merchant_order_idStringНеВаш вътрешен идентификатор на поръчка
:descriptionStringНеОписание на поръчката
:return_urlStringНеПренасочване след успешно плащане
:failure_urlStringНеПренасочване при отказ/изтичане/грешка
:webhook_urlStringНеАсинхронни известия за промяна на статуса
:localeStringНеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
:payment_methodsArray<String>НеФилтриране на HPP методи
:expiration_periodStringНе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 OpenStruct

client.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::ErrorStandardErrorБазова грешка за всички SDK грешки
NoPayn::ApiErrorNoPayn::ErrorHTTP грешка от API-то
NoPayn::WebhookErrorNoPayn::ErrorНевалидни данни от уебхук

Статуси на поръчки

СтатусФинален?Описание
newНеПоръчката е създадена
processingНеПлащането е в ход
completedДаПлащането е успешно — доставете стоката
cancelledДаПлащането е отменено от клиента
expiredДаЛинкът за плащане е изтекъл
errorДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. verify_webhook на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с get_order като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):

КартаНомерБележки
Visa (успех)4111 1111 1111 1111Произволен CVV
Mastercard (успех)5544 3300 0003 7Произволен CVV
Visa (отхвърлена)4111 1111 1111 1105Do Not Honor
Visa (недостатъчни средства)4111 1111 1111 1151Insufficient Funds

Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.

Демо приложение

Демо приложение, базирано на Sinatra, е включено в GitHub хранилището за тестване на пълния поток на плащане.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page