Transfers

A transfer is a single charge against a payment instrument — the API primitive behind one-off payments and the source of refunds via the reversals sub-resource.

Accessed via client.transfers.

Methods

`create(amount:, currency:, source:, tags: nil)`

POST /transfer. amount is in minor units (cents). source is a payment-instrument ID.

transfer = client.transfers.create(
  amount:   1_500,
  currency: "USD",
  source:   "pi_…",
  tags:     { order_id: "ord_…" }
)

`update(id, **body)`

PATCH /transfer/:id. Used primarily to mutate tags.

client.transfers.update("tr_…", tags: { reconciled: true })

`retrieve(id)`

GET /transfer/:id.

client.transfers.retrieve("tr_…")

`list(limit: nil, offset: nil, ids: nil)`

GET /transfer.

client.transfers.list(limit: 100)

`create_refund(transfer_id, refund_amount:, tags: nil)`

POST /transfer/:id/reversals. Issues a refund against an existing transfer. refund_amount is in minor units; pass the full transfer amount for a complete refund or a smaller value for a partial refund.

client.transfers.create_refund(
  "tr_…",
  refund_amount: 500,
  tags:          { reason: "duplicate_charge" }
)

Object shape

:id, :amount, :currency, :source, :state, :created_at, :tags, … plus a :reversals collection that grows as refunds are issued.

Examples

Charge a customer's default card

instruments = client.customers.payment_instruments(customer[:id])[:data] || []
default     = instruments.find { |pi| pi[:default] } || instruments.first
raise "no instrument on file" unless default

client.transfers.create(amount: 2_500, currency: "USD", source: default[:id])

Full refund

charge = client.transfers.retrieve("tr_…")
client.transfers.create_refund(charge[:id], refund_amount: charge[:amount])

Partial refund

client.transfers.create_refund("tr_…", refund_amount: 500)

Transfers

On this page