Transfer

A Transfer is the atomic record of a single money movement — a charge against a Payment Instrument, a refund (reversal), a settlement, or a fee. If you have used Stripe, this is the equivalent of a Charge plus a PaymentIntent collapsed into one object: there is no separate "intent" step, and the same shape covers debits, credits, refunds, and disputes via the type field. Most production integrations create Transfers indirectly through Checkout / Embedded Checkout / Subscriptions; the direct client.createTransfer API is for headless server-to-server charges against an already-saved Payment Instrument.

Lifecycle

1. Created — PENDING. client.createTransfer({ amount, currency, source }) (or any checkout flow) submits the charge to the processor.
2. Authorized → captured — the processor authorizes the funding source. For card transfers Easy Labs auto-captures; the state moves to SUCCEEDED when funds clear, or FAILED with a failure_code / failure_message.
3. Settled — once ready_to_settle_at is in the past, the Transfer is included in the next merchant Settlement. Funds appear in the merchant payout.
4. Reversed (refunded) — calling client.createRefund(transferId, { refund_amount }) produces a child Transfer with type: "REVERSAL" and parent_transfer pointing back at the original. The original Transfer's state becomes REVERSED once fully reversed.
5. Disputed — if the buyer initiates a chargeback, a dispute.created webhook fires and a separate Transfer with type: "DISPUTE" is created to hold the disputed amount.

Webhooks: payment.created and payment.updated track the canonical state transitions. refund.created / refund.updated fire on reversals.

Relationships

A Transfer has one source (a Payment Instrument ID), one merchant_identity (the Customer being charged), and optionally one parent_transfer (for reversals). Each Order embeds at most one Transfer. Disputes reference Transfers by ID.

Fields that matter

• id (string) — pass to getTransfer, createRefund, or as transferId for dispute lookups.
• amount, amount_requested, currency — the captured amount, the originally requested amount, and ISO currency. Amounts are in the smallest unit (cents for USD).
• state ("PENDING" | "SUCCEEDED" | "FAILED" | "REVERSED" | "CANCELED" | "UNKNOWN") — terminal states are SUCCEEDED, FAILED, REVERSED, CANCELED.
• type ("DEBIT" | "CREDIT" | "REVERSAL" | "DISPUTE" | "FEE" | "ADJUSTMENT" | "RESERVE" | "SETTLEMENT" | "UNKNOWN") — what kind of money movement this is. Filter on type === "DEBIT" for buyer charges.
• failure_code, failure_message — populated when state === "FAILED". Surface these to the buyer for retry-friendly errors (insufficient funds, declined, etc.).
• parent_transfer (string | null) — set on reversals to the original Transfer's ID.
• fee (number) — Easy Labs / network fee for this Transfer in the smallest unit.
• ready_to_settle_at (string) — ISO timestamp when this Transfer is eligible for the next settlement.

Related

• API reference
• Guide: Accept a card payment
• Guide: Issue a refund