client.payments.create_by_token(card_token: 'tok_abc', amount: 500_000, invoice_id: 'ORD-1')
client.holds.capture(hold_id, amount: 300_000)
client.cards.create_binding_link

rescue Multicard::InsufficientFundsError  # not enough funds
rescue Multicard::CardExpiredError         # card expired
rescue Multicard::DebitUnknownError        # need to poll for status
rescue Multicard::NetworkError             # timeout / connection lost

gem 'multicard'

require 'multicard'

client = Multicard::Client.new(
  application_id: ENV['MULTICARD_APPLICATION_ID'],
  secret: ENV['MULTICARD_SECRET'],
  store_id: 123  # default register ID
)

# Create a hosted checkout invoice
invoice = client.invoices.create(
  amount: 500_000,          # 5,000 UZS in tiyin
  invoice_id: 'ORD-001',
  callback_url: 'https://example.com/webhooks/multicard'
)

# Redirect user to payment page
invoice.data[:checkout_url]

Multicard.configure do |config|
  config.application_id = ENV['MULTICARD_APPLICATION_ID']
  config.secret = ENV['MULTICARD_SECRET']
  config.base_url = 'https://api.multicard.uz'  # default
  config.timeout = 30                            # default (seconds)
  config.open_timeout = 10                       # default (seconds)
  config.logger = Logger.new($stdout)            # optional
  config.store_id = 123                          # default store/register ID
end

# Then create clients without repeating credentials:
client = Multicard::Client.new

client = Multicard::Client.new(
  application_id: 'other_app_id',
  secret: 'other_secret',
  store_id: 456
)

# Create invoice
invoice = client.invoices.create(
  amount: 500_000,
  invoice_id: 'ORD-001',
  callback_url: 'https://example.com/cb',
  return_url: 'https://example.com/success',
  description: 'Order payment'
)
invoice.data[:checkout_url]  # redirect user here

# Get invoice info
info = client.invoices.retrieve('ORD-001')

# Cancel unpaid invoice
client.invoices.cancel('ORD-001')

# Quick Pay (Payme, Click, Uzum QR)
client.invoices.quick_pay(invoice_id: 'ORD-001', service: 'payme')

payment = client.payments.create_by_token(
  card_token: 'tok_abc',
  amount: 500_000,
  invoice_id: 'ORD-001',
  callback_url: 'https://example.com/cb'
)

payment = client.payments.create_by_card(
  card_number: '8600123456781234',
  card_expiry: '1228',
  amount: 500_000,
  invoice_id: 'ORD-002'
)

payment = client.payments.create_wallet(
  service: 'payme',  # or 'click', 'uzum', etc.
  amount: 300_000,
  invoice_id: 'ORD-003'
)

payment = client.payments.create_split(
  card_token: 'tok_abc',
  amount: 500_000,
  invoice_id: 'ORD-004',
  split: [
    { type: 'account', amount: 400_000, details: 'Store share', recipient: 'uuid-1' },
    { type: 'wallet', amount: 100_000, details: 'Platform fee' }
  ]
)

client.payments.confirm('payment-uuid', otp_code: '123456')

# Full refund
client.payments.refund('payment-uuid')

# Partial refund
client.payments.partial_refund('payment-uuid', amount: 100_000)

client.payments.send_fiscal_link('payment-uuid', fiscal_url: 'https://ofd.uz/receipt/123')

client.payments.create_by_token(
  card_token: 'tok_abc',
  amount: 500_000,
  invoice_id: 'ORD-005',
  ofd: [
    { name: 'Product', price: 500_000, qty: 1, vat: 12,
      tin: '123456789', mxik: '10202001001000000', package_code: '1508574' }
  ]
)

# Get binding link
link = client.cards.create_binding_link
# Redirect user to: link.data[:url]

# Check status (polling)
status = client.cards.binding_status(link.data[:session_id])
status.data[:token]  # card token when bound

# Send OTP
client.cards.add(card_number: '8600123456781234', card_expiry: '1228')

# Confirm with OTP
result = client.cards.confirm_binding(otp_code: '123456')
result.data[:token]

# Get card info
card = client.cards.retrieve('card_token')

# Check card number
client.cards.check('8600123456781234')

# Verify ownership (PINFL)
client.cards.verify_pinfl(token: 'card_token', pinfl: '12345678901234')

# Unbind card
client.cards.revoke('card_token')

# Create hold
hold = client.holds.create(
  card_token: 'tok_abc',
  amount: 500_000,
  invoice_id: 'HOLD-001'
)

# Confirm hold (block funds)
client.holds.confirm(hold.data[:id], otp_code: '123456')

# Capture full amount
client.holds.capture(hold.data[:id])

# Capture partial amount
client.holds.capture(hold.data[:id], amount: 300_000)

# Cancel hold (release funds)
client.holds.cancel(hold.data[:id])

# Check hold status
client.holds.retrieve(hold.data[:id])

# Create payout
payout = client.payouts.create(card_number: '8600999988887777', amount: 100_000)

# Confirm payout
client.payouts.confirm(payout.data[:id])

# Check status
client.payouts.retrieve(payout.data[:id])

# Payment registry
client.registry.payments(date_from: '2025-01-01', date_to: '2025-01-31')

# Payout history
client.registry.payouts

# Application info
client.registry.application_info

# Merchant banking details
client.registry.merchant_details

# In your webhook controller:
def multicard_callback
  params = request.params.symbolize_keys

  unless Multicard::Signature.verify(params, secret: ENV['MULTICARD_SECRET'])
    head :unauthorized
    return
  end

  payment = client.payments.retrieve(params[:uuid])
  # Process payment...
  head :ok
end

begin
  client.payments.create_by_token(
    card_token: 'tok_abc',
    amount: 500_000,
    invoice_id: 'ORD-001'
  )
rescue Multicard::CardNotFoundError => e
  # Card token is invalid or revoked
rescue Multicard::InsufficientFundsError => e
  # Not enough funds on the card
rescue Multicard::CardExpiredError => e
  # Card has expired
rescue Multicard::DebitUnknownError => e
  # Unknown debit status - poll for result
  payment = client.payments.retrieve(e.response_body.dig(:data, :uuid))
rescue Multicard::InvalidFieldsError => e
  # Validation error - check e.error_details
rescue Multicard::AuthenticationError => e
  # Invalid credentials
rescue Multicard::NetworkError => e
  # Timeout or connection failure
rescue Multicard::ServerError => e
  # Multicard server error (5xx)
rescue Multicard::Error => e
  # Any other Multicard error
  e.http_status     # HTTP status code
  e.error_code      # Multicard error code string
  e.error_details   # Human-readable error description
  e.response_body   # Full response body hash
end