Transfers

A transfer is any movement of funds on Frame. Charging a card, paying out to a bank account, settling between accounts on your platform — all of those are transfers. One primitive, two flows.

How it works

Frame models every money movement as a Transfer. The shape of a transfer — what gets charged, where the funds land — is determined by which payment methods you attach to it:

  • Provide a source payment method (card or ACH) and Frame pulls funds from it. This is the charge flow — the everyday "accept a payment" case.
  • Provide only a destination payment method (bank account or debit card) and Frame pushes funds to it. This is the payout flow — disbursing to your sellers, contractors, or end users.
  • Provide both, and you've described an account-to-account flow on your platform.

Transfers are created synchronously: the API call returns a transfer object with a status the moment it lands. For charge flows the processor responds in-line, so most transfers reach a terminal status by the time you read the response. Payout flows settle asynchronously — the processor needs to confirm — so payouts start in pending and transition once the network responds. Either way, the Transfer is the durable record of the intent and the outcome.

Lifecycle

A transfer's status walks through these states:

  • pending — the transfer is created and waiting on the processor. Payouts dwell here; most charges pass through quickly.
  • succeeded — funds have moved. This is the terminal success state.
  • failed — the processor declined or the move could not be completed. See failure_reason for the specific cause.
  • reversed — a previously succeeded transfer was undone by a processor-side reversal during settlement (rare; distinct from refunds, which are separate Refund records).
  • canceled — the transfer was canceled before processing began.

Status transitions are one-way for terminal states (succeeded, failed, canceled). A succeeded transfer can move to reversed if the processor reverses it during settlement, or to refunded if it's fully refunded — but in practice merchant-facing refund tracking happens on separate Refund records, not parent transfer state.

Relationships

A transfer is the verb; the rest of the platform supplies the nouns it acts on.

PaymentMethod is the source or destination of funds. A charge transfer reads from one; a payout transfer writes to one; an account-to-account transfer touches both.

Account owns the transfer on the platform side. Every transfer is attributed to an account so you can reconcile activity per seller, per merchant, per end user.

Refunds are separate records linked to the original transfer — they don't transition the parent's status by default. See refunds for the lifecycle on that side.

Gotchas

Symptom: you create a payout transfer and the response says pending — did it work? Why: payouts are asynchronous; the processor confirms over the network, not in-line with your API call. Fix: listen for the transfer.succeeded or transfer.failed webhook rather than inferring from the create response.

Symptom: the amount you charged the customer doesn't match the amount your seller received. Why: the billing agreement's fee_application_mode determines whether platform_fee and frame_fee are deducted from the charge, added on top, or absorbed by the merchant. Fix: check the merchant's billing agreement and use the accept-a-payment guide to see the modes side-by-side.

Symptom: you provided a source_payment_method_id and a destination_payment_method_id and the funds went somewhere you didn't expect. Why: the presence of those fields is what selects the flow — providing both means the funds are moving from one account on your platform to another, not from the card to your platform. Fix: set only the fields that describe the flow you actually want.

Reference

For the full API surface, see POST/v1/transfers and the rest of the Transfers resource.