Payriff Ruby SDK

# Gemfile
gem "payriff"

require "payriff"

payriff = Payriff::Client.new(app_key: ENV.fetch("PAYRIFF_APP_KEY"))

order = payriff.orders.create(
  amount: "10.00",
  description: "Order #1001",
  callback_url: "https://shop.example/payriff/callback",
  request_rrn: "order-1001"
)

# Send the customer to the hosted payment page
redirect_to order.payment_url, allow_other_host: true

payriff = Payriff::Client.new(app_key: ENV.fetch("PAYRIFF_APP_KEY"), region: :saudi)

created = payriff.orders.create(
  amount: "25.00",
  currency: "AZN",            # default: the region currency
  operation: "PRE_AUTH",      # default PURCHASE
  language: "AZ",
  description: "Booking #77",
  callback_url: "https://shop.example/payriff/callback",
  metadata: { "bookingId" => "77" }
)

info = payriff.orders.get(created.order_id)
by_ref = payriff.orders.get_by_request_rrn("order-1001")   # the request_rrn you sent on create

payriff.orders.complete(created.order_id, amount: "25.00")
payriff.orders.refund(created.order_id, amount: "5.00", refund_reason: "Partial return")
payriff.orders.expire(created.order_id)                    # cancel an unpaid order

receipt_pdf = payriff.orders.download_receipt(created.order_id)

charge = payriff.payments.auto_pay(
  card_uuid: saved_card_uuid,
  amount: "9.99",
  description: "Monthly subscription",
  request_rrn: "sub-2026-10"
)

session = payriff.cards.save(
  customer_ref: "customer-42",
  callback_url: "https://shop.example/payriff/card-saved",
  idempotency_key: SecureRandom.uuid
)
# Redirect the customer to session.payment_url to verify the card.

details = payriff.cards.get_save(session.card_save_id)
if details.status == "VERIFIED"
  card_uuid = details.card_uuid   # store it; use with auto_pay
end

cards = payriff.cards.list("customer-42")
payriff.cards.delete(cards.first.card_uuid)

page = payriff.transactions.list(
  status: "APPROVED",
  from: Date.new(2026, 9, 1),    # Date, Time or "YYYY-MM-DD"
  to: "2026-09-30",
  page: 0,
  size: 20                       # server maximum is 20
)

page.content.each { |tx| puts "#{tx.order_id} #{tx.amount}" }

payriff = Payriff::Client.new(app_key: ENV.fetch("PAYRIFF_APP_KEY"), merchant_id: ENV.fetch("PAYRIFF_MERCHANT_ID"))

masked_name = payriff.payouts.check_cardholder("4169741330151979")   # e.g. "J*** D**"

payout = payriff.payouts.create(
  transfer_amount: "50.00",      # minimum 1
  description: "Refund for order #1001",
  full_name: "JOHN DOE",
  fin_code: "1AB2C3D",
  card_pan: "4169741330151979",
  request_rrn: "payout-1001",
  idempotency_key: "payout-1001"
)

status = payriff.payouts.get_by_request_rrn("payout-1001")
history = payriff.payouts.list(status: "SUCCESS")
receipt = payriff.payouts.download_receipt("payout-1001")

invoice = payriff.invoices.create(
  amount: "15.00",
  full_name: "JOHN DOE",
  phone_number: "+994501234567",
  description: "Consultation",
  expire_date: Time.now + 7 * 24 * 3600,
  send_sms: true
)

link = invoice.payment_url   # share with the customer
details = payriff.invoices.get(invoice.invoice_uuid)

class PayriffCallbacksController < ApplicationController
  skip_forgery_protection

  def create
    notified = Payriff.parse_order_callback(request.raw_post)   # also accepts a parsed Hash

    # Callbacks are not signed: confirm the state with Payriff before fulfilling.
    confirmed = PAYRIFF.orders.get(notified.order_id)
    if confirmed.payment_status == "APPROVED"
      # fulfil the order (make this idempotent: the same callback can arrive more than once)
    end
    head :ok
  end
end

begin
  payriff.orders.refund(order_id)
rescue Payriff::ValidationError => e
  Rails.logger.warn("Refund rejected: #{e.message} (#{e.code})")
rescue Payriff::ConnectionError
  # Outcome unknown: check payriff.orders.get(order_id) before retrying
rescue Payriff::Error => e
  Rails.logger.error("Payriff error #{e.code} response_id=#{e.response_id}")
end