PaymentKit

gem "payment_kit"

require "payment_kit"

PaymentKit.configure do |config|
  config.secret_key = ENV.fetch("PAYMENT_KIT_SECRET_KEY") # st_prod_...
  config.account_id = ENV.fetch("PAYMENT_KIT_ACCOUNT_ID") # acc_prod_...
end

client = PaymentKit::Client.new

customer = client.create_customer(
  email: "customer@example.com",
  first_name: "Jane",
  last_name: "Smith",
  business_name: "Acme Inc"
)

puts customer["id"] # => "cus_prod_..."

PaymentKit.configure do |config|
  config.secret_key      = ENV.fetch("PAYMENT_KIT_SECRET_KEY")
  config.account_id      = ENV.fetch("PAYMENT_KIT_ACCOUNT_ID")
  config.signing_secret  = ENV["PAYMENT_KIT_SIGNING_SECRET"] # optional, for webhooks
  config.api_host        = "https://app.paymentkit.com/api"  # default
  config.open_timeout    = 10                                # seconds, default
  config.read_timeout    = 30                                # seconds, default
  config.max_retries     = 2                                 # default
end

PaymentKit.reset_configuration!

# Production-style
PaymentKit.configure do |c|
  c.secret_key = "st_prod_..."
  c.account_id = "acc_prod_abc"
end
# => https://app.paymentkit.com/api/acc_prod_abc

# Custom host
PaymentKit.configure do |c|
  c.secret_key = "st_prod_..."
  c.account_id = "acc_prod_abc"
  c.api_host   = "https://app.paymentkit.com/api"
end

# Full override (useful in tests)
client = PaymentKit::Client.new(
  secret_key: "st_test",
  base_url: "https://api.test/acc"
)

client = PaymentKit::Client.new(
  secret_key: ENV.fetch("PAYMENT_KIT_SECRET_KEY"),
  account_id: ENV.fetch("PAYMENT_KIT_ACCOUNT_ID"),
  open_timeout: 5,
  read_timeout: 20,
  max_retries: 3
)

client.base_url
# => "https://app.paymentkit.com/api/acc_prod_..."

# config/initializers/payment_kit.rb
PaymentKit.configure do |config|
  config.secret_key     = Rails.application.credentials.dig(:payment_kit, :secret_key)
  config.account_id     = Rails.application.credentials.dig(:payment_kit, :account_id)
  config.signing_secret = Rails.application.credentials.dig(:payment_kit, :signing_secret)
end

client = PaymentKit::Client.new

customer = client.create_customer(
  email: "customer@example.com",
  first_name: "Jane",
  last_name: "Smith",
  business_name: "Acme Inc",
  phone: "+15550100",
  billing_email: "ap@acme.test",
  currency: "USD",
  language: "en",
  address: { line1: "1 Market St", city: "San Francisco", country: "US", postal_code: "94105" },
  tax_ids: ["EU372009832"],
  metadata: { plan_tier: "enterprise" }
)

customer = client.retrieve_customer("cus_123")

# PUT — only the fields you send are changed
customer = client.update_customer("cus_123",
  email: "new@example.com",
  metadata: { plan_tier: "pro" }
)

customers = client.list_customers(limit: 50)  # auto-paginated Array

# Make the customer's USD balance exactly 5000 atoms ($50.00)
balance = client.set_credit_balance("cus_123", amount_atom: 5000, currency: "USD")
# => { "amount_atom" => 5000, "currency" => "USD" }

note = client.create_credit_note(
  "cus_123",
  {
    amount_atom: 2500,
    currency: "USD",
    reason: "manual_adjustment",
    memo: "Goodwill credit for billing error",
    invoice_id: "inv_123"   # optional; otherwise a paid companion invoice is created
  },
  idempotency_key: "credit-overcharge-918"
)

notes = client.list_credit_notes("cus_123", currency: "USD")

# Deprecated; identical to set_credit_balance("cus_123", ...)
client.create_balance_transaction("cus_123", amount_atom: 5000, currency: "USD")

subscription = client.create_subscription(
  customer_id: "cus_123",
  currency: "USD",
  billing_interval: "month",          # day | week | month | year
  billing_interval_count: 1,
  period_start: "2026-02-01T00:00:00Z",
  collection_method: "charge_automatically",  # or send_invoice
  processor_id: "proc_live_abc",      # falls back to the account default
  items: [
    { price_id: "price_monthly_pro", quantity: 1 },
    { price_id: "price_addon_seats", quantity: 5 }
  ],
  trial_start: "2026-02-01T00:00:00Z",
  trial_end: "2026-02-15T00:00:00Z",
  net_d: 30,                          # payment terms in days
  coupon_id: "coup_welcome20",
  total_billing_cycles: 12            # auto-cancel after N cycles
)

subscription  = client.retrieve_subscription("sub_123")
subscriptions = client.list_subscriptions(customer_id: "cus_123")

# Cancel at period end (and undo it) via the base update endpoint
client.update_subscription("sub_123", cancel_at_period_end: true)
client.update_subscription("sub_123", cancel_at_period_end: false)

client.update_subscription_items("sub_123",
  {
    proration_behavior: "always_invoice",
    items: [
      { id: "si_plan", price_id: "price_monthly_pro", quantity: 2 }
    ]
  },
  idempotency_key: "seat-change-42-v3"
)

# Immediate cancel. refund_option: none | full | prorated | cancel_unpaid
client.cancel_subscription("sub_123", refund_option: "prorated")

# Calculate the refund without executing
preview = client.cancel_subscription("sub_123", refund_option: "prorated", is_preview: true)

# Cancel on a specific date instead, then undo it
client.schedule_cancellation("sub_123", cancel_at: "2026-06-01T00:00:00Z", refund_option: "none")
client.cancel_scheduled_cancellation("sub_123")

# Pause now, or at period end. pause_for_cycles and resumption_date are
# mutually exclusive ways to schedule the auto-resume.
client.pause_subscription("sub_123", pause_behavior: "pause_immediately", pause_for_cycles: 2)
client.pause_subscription("sub_123", pause_behavior: "pause_at_end")
client.cancel_scheduled_pause("sub_123")   # removes a pending pause_at_end

client.resume_subscription("sub_123")
client.renew_subscription("sub_123")

client.reschedule_billing("sub_123",
  next_billing_date: "2026-03-15T00:00:00Z",
  create_proration: true,
  is_preview: false
)

# Cancels a scheduled (period-end) plan change before it executes
client.cancel_pending_change("sub_123")

request = client.create_change_request("sub_123",
  reason: "Upgrade to annual plan",
  expires_in_hours: 24
)

# Append item, coupon and balance changes. Callable repeatedly; each call
# appends. Doing this on a `ready` request reverts it to `draft`.
client.add_change_request_changes("sub_123", request["id"],
  item_changes: [
    { action: "update", item_id: "si_monthly_plan", price_id: "price_annual_plan" },
    { action: "add", price_id: "price_addon_support", quantity: 1, apply_at_end: false },
    { action: "drop", item_id: "si_legacy_addon" }
  ],
  coupon_changes: [
    { action: "add", coupon_id: "coup_welcome20" }
  ],
  trial_behavior: "preserve"   # or end_now
)

# Pure computation: returns proration amounts and the execution plan, → ready
preview = client.preview_change_request("sub_123", request["id"])
preview["preview"]["invoice_total_atom"]

# Charge-first execution. A decline raises PaymentKit::CardError (402).
client.apply_change_request("sub_123", request["id"],
  idempotency_key: "cr-#{request["id"]}"
)

request = client.retrieve_change_request("sub_123", request["id"])
active  = client.active_change_request("sub_123")   # nil when none is pending
client.cancel_change_request("sub_123", request["id"])

client.apply_subscription_changes("sub_123",
  {
    item_changes: [
      { action: "update", item_id: "si_monthly_plan", price_id: "price_annual_plan" }
    ],
    reason: "Upgrade to annual plan",
    payment_method_id: "pm_123"
  },
  idempotency_key: "upgrade-#{user_id}-v1"
)

client.change_plan("sub_123",
  reason: "Billing interval change to year",
  proration_behavior: "always_invoice",
  effective_at: "immediate",
  items: [
    { action: "update", subscription_item_id: "si_plan",
      new_price_id: "price_annual_plan", quantity: 1 }
  ]
)

invoice = client.create_invoice(
  customer_id: "cus_123",
  currency: "USD",
  issued_at: "2026-02-01T00:00:00Z",
  description: "Setup fee — Enterprise onboarding",
  collection_method: "charge_automatically",
  items: [
    { description: "Enterprise onboarding", quantity: 1, amount: 500.00 },
    { description: "Custom integration", quantity: 4, unit_amount: 150.00 },
    { price_id: "price_support_plan", quantity: 1 }
  ]
)

# Draft → Open: locks amounts, optionally generates the PDF and emails it
invoice = client.finalize_invoice(invoice["id"])

# Attempts collection; finalizes the invoice first when still draft.
# A decline raises PaymentKit::CardError and leaves the invoice payable.
result = client.pay_invoice(invoice["id"], payment_method_id: "pm_123")
result["invoice_status"] # => "paid"

invoice  = client.retrieve_invoice("inv_123", expand: "custom_fields")
invoices = client.list_invoices(customer_id: "cus_123", status: "open")

# Poll while status is "generating"
pdf = client.retrieve_invoice_pdf("inv_123")
pdf["pdf_url"] if pdf["status"] == "available"

client.void_invoice("inv_123")

# Only permitted from OPEN or PAST_DUE; other states return 422
client.mark_invoice_uncollectible("inv_123")

result = client.bill_pending_items(
  {
    customer_id: "cus_123",       # required
    subscription_id: "sub_123",   # optional narrowing
    currency: "USD",
    collection_method: "charge_automatically",
    description: "July usage",
    tax_amount_atom: 0
  },
  idempotency_key: "bill-cus_123-2026-07"
)

result["invoices"].each { |inv| puts "#{inv["currency"]}: #{inv["items_swept"]} items" }

# With a catalog price
item = client.create_invoice_item(
  customer_id: "cus_123",
  subscription_id: "sub_123",
  price_id: "price_sms_usage",
  quantity: 150,
  description: "SMS charges — July 2026 (150 messages)"
)

# With a custom amount
item = client.create_invoice_item(
  customer_id: "cus_123",
  subscription_id: "sub_123",
  amount: 75.00,
  description: "Custom setup fee"
)

item  = client.retrieve_invoice_item(item["id"])
item  = client.update_invoice_item(item["id"], quantity: 200, description: "SMS charges — revised")
items = client.list_invoice_items(subscription_id: "sub_123", status: "floating")

intent = client.create_payment_intent(
  customer_id: "cus_123",
  amount_atom: 2500,
  currency: "USD",
  payment_method_id: "pm_123",
  processor_id: "proc_live_abc",
  metadata: { order_id: "ord_9" }
)

intent  = client.retrieve_payment_intent("pi_123", expand: "checkout_attempt")
intents = client.list_payment_intents(customer_id: "cus_123", limit: 50)

refunds  = client.list_refunds_by_intent("pi_123")
attempts = client.list_attempts_by_intent("pi_123")

pm = client.create_payment_method(customer_id: "cus_123", provider_type: "card")
pm = client.retrieve_payment_method("pm_123")
pm = client.update_payment_method("pm_123", metadata: { label: "primary" })

# Documented way to take a card out of use (PUT is_active: false)
client.deactivate_payment_method("pm_123")

# Outright delete. PaymentKit documents deletion only on the customer-portal
# surface, so if your account returns 404/405 use deactivate_payment_method.
client.detach_payment_method("pm_123")

session = client.create_checkout_session(
  customer_id: "cus_123",                       # optional; pre-fills the customer
  line_items: [{ price_id: "price_123", quantity: 1 }],
  success_url: "https://example.com/success",
  return_url: "https://example.com/cancel",
  expires_in_hours: 24,
  promotion_code: "LAUNCH20",
  custom_fields: { internal_ref: "ord_9" }
)

session["secure_token"]

session = client.retrieve_checkout_session(session["id"])

product  = client.create_product(
  name: "Pro plan",
  description: "Everything in Starter, plus priority support",
  is_active: true,
  metadata: { tier: "pro" }
)

product  = client.retrieve_product("prod_123")
product  = client.update_product("prod_123", is_active: false, default_price_id: "price_123")
products = client.list_products(limit: 50)
prices   = client.list_product_prices("prod_123")

price = client.create_price(
  product_id: "prod_123",
  currency: "USD",
  unit_amount_atom: 2500,
  pricing_type: "recurring",
  billing_scheme: "per_unit",
  recurring_interval: "month",
  recurring_interval_count: 1,
  trial_days: 14
)

price  = client.retrieve_price("price_123")
prices = client.list_prices(limit: 50)

products = client.list_products(limit: 50)
products.each { |product| puts product["id"] }

# Filters are forwarded as query params
invoices = client.list_invoices(customer_id: "cus_123", status: "open")

PaymentKit.configure do |config|
  config.signing_secret = ENV.fetch("PAYMENT_KIT_SIGNING_SECRET") # whsec_...
  # or multiple secrets (tried in order):
  # config.signing_secrets = [ENV["PAYMENT_KIT_SIGNING_SECRET"], ENV["PAYMENT_KIT_SIGNING_SECRET_OLD"]]
end

# Module-level accessors also work:
PaymentKit.signing_secret  = ENV.fetch("PAYMENT_KIT_SIGNING_SECRET")
PaymentKit.signing_secrets = [ENV["PAYMENT_KIT_SIGNING_SECRET"], ENV["PAYMENT_KIT_SIGNING_SECRET_OLD"]]

PaymentKit.subscribe "invoice.paid" do |event|
  # event is a Hash, e.g. { "id" => "evt_...", "type" => "invoice.paid", ... }
  # Prefer enqueueing work here; slow handlers delay the webhook HTTP response.
end

PaymentKit.subscribe "invoice.", InvoiceHandler.new  # prefix match; #call(event)
PaymentKit.all { |event| Rails.logger.info(event["type"]) }

PaymentKit.event_filter = lambda do |event|
  # return event to dispatch, or nil to ignore (still a successful verify path)
  event["type"] == "ping" ? nil : event
end

PaymentKit.configure do |config|          # settings
  config.secret_key = ENV.fetch("PAYMENT_KIT_SECRET_KEY")
end

PaymentKit.configure do                   # subscriber DSL
  subscribe("invoice.paid") { |event| InvoicePaidJob.perform_later(event["id"]) }
  all { |event| Rails.logger.info(event["type"]) }
end

payload   = request.body.read
signature = request.headers["X-Webhook-Signature"]

begin
  event = PaymentKit.process_webhook(payload, signature)
  # verified + instrumented; subscribers already ran
rescue PaymentKit::SignatureVerificationError
  head :unauthorized  # signature missing or invalid
rescue PaymentKit::InvalidRequestError
  head :bad_request   # verified, but the body is not JSON
end

event = client.verify_webhook(payload, signature)
# or:
event = PaymentKit::Webhook.construct_event(payload, signature, PaymentKit.signing_secrets)
PaymentKit.instrument(event)

# config/routes.rb
mount PaymentKit::Engine, at: "/payment_kit"

PaymentKit.event_retriever = lambda do |event|
  key = "payment_kit:webhook:#{event["id"]}"
  Sidekiq.redis { |r| r.set(key, "1", nx: true, ex: 3.days.to_i) } ? event : nil
end

PaymentKit.error_handler = ->(exception, _request) { Sentry.capture_exception(exception) }

PaymentKit.subscriber_error_handler = lambda do |exception, event|
  Sentry.capture_exception(exception, extra: { event_id: event["id"] })
end

begin
  client.create_subscription(params)
rescue PaymentKit::ConflictError => e
  retry if e.retryable? # e.g. error_code == "invoice_locked"
  warn "Conflict on invoice #{e.invoice_id}: #{e.message}"
rescue PaymentKit::CardError => e
  warn "Declined: #{e.message}"
rescue PaymentKit::InvalidRequestError => e
  warn "Bad request (#{e.status}): #{e.message} request_id=#{e.request_id}"
rescue PaymentKit::APIConnectionError => e
  warn "Network problem: #{e.message}"
rescue PaymentKit::Error => e
  warn "PaymentKit error: #{e.message}"
end

client.bill_pending_items(params, idempotency_key: "dispatch-#{user_id}-#{timestamp}")
client.update_subscription_items("sub_1", { items: [...], proration_behavior: "always_invoice" },
                                 idempotency_key: "plan-change-#{user_id}-#{version}")

client.create_customer(email: "a@b.com")
client.create_customer({ email: "a@b.com" }, idempotency_key: "signup-42")
client.create_customer(email: "a@b.com", idempotency_key: "signup-42")

PaymentKit::Instrumentation.subscribe(:request_end) do |event|
  StatsD.timing(
    "payment_kit.request",
    event.duration * 1000,
    tags: ["method:#{event.method}", "path:#{event.path}", "status:#{event.status}"]
  )
  Rails.logger.warn("PaymentKit retried #{event.path} #{event.num_retries}x") if event.num_retries.positive?
end

client.raw_request(:get, "/payment-links", params: { limit: 10 })
client.raw_request(:post, "/webhook-endpoints/we_1/roll-secret",
                   params: { ttl_seconds: 3600 }, idempotency_key: "roll-1")

client.raw_request(:get, "/billing-portal/token/#{token}/payment-methods",
                   account_scoped: false)

client = PaymentKit::Client.new(
  secret_key: "st_test",
  base_url: "https://api.test/acc"
)

# Example: inject responses by stubbing the private transport seam in unit tests
allow(client).to receive(:transport).and_return(fake_response)