Ruby and Rails SDK - OrsunPay

Use the orsunpay gem with Ruby 3.1 or later. For a Rails app, place the supplied SDK source under vendor/orsunpay, add it to your Gemfile, then run bundle install:

gem "orsunpay", path: "vendor/orsunpay"

Configure the merchant client

# config/initializers/orsunpay.rb
require "orsunpay"

Rails.application.config.x.orsunpay = OrsunPay::Client.new(
  base_url: ENV.fetch("ORSUNPAY_API_BASE_URL"),
  merchant_id: ENV.fetch("ORSUNPAY_MERCHANT_ID"),
  api_key: ENV.fetch("ORSUNPAY_API_KEY")
)

From a server-side service or job, look up the existing transaction with the original order ID:

client = Rails.application.config.x.orsunpay
result = client.retrieve_payment_by_order_id(order_id)
status = result.data.fetch("transaction").fetch("status")

For sale, payout, payment link and refund creation, persist the key with the order and pass it as idempotency_key:. Use decimal strings for amounts and store the returned IDs. Idempotency

Verify an incoming Rails webhook

Use the raw request body rather than Rails’ parsed parameters:

event = OrsunPay::Webhook.verify(
  request.raw_post,
  request.headers["OrsunPay-Signature"],
  secrets: [ENV.fetch("ORSUNPAY_WEBHOOK_SECRET")]
)
event_id = event.fetch("id")

Handle OrsunPay::SignatureError as a rejected delivery. On success, use the event ID to process the change exactly once before returning 2xx. Webhook delivery