Transfers

A Transfer is the SDK's term for a money movement — a charge against a saved payment instrument. Refunds are reversals on a transfer and live on this same resource (see Refunds for the recipe).

Namespace: client.transfers.

Amounts are integers in the smallest currency unit (e.g. cents for USD). amount=2500 + currency="USD" charges $25.00.

Methods

`create`

transfer = client.transfers.create(
    amount=2500,
    currency="USD",
    source="pi_abc",                       # payment instrument id
    tags={"order_id": "ord_123"},
    idempotency_key=f"charge-ord_123",
)

Returns: Transfer.

`update`

transfer = client.transfers.update(
    "tr_123",
    tags={"reconciled": True},
)

PATCHes any combination of writable fields (typically tags).

`retrieve`

transfer = client.transfers.retrieve("tr_123")

`list`

recent = client.transfers.list(limit=50)
batch  = client.transfers.list(ids=["tr_1", "tr_2"])

Returns list[Transfer]. See Pagination.

`create_refund`

reversal = client.transfers.create_refund(
    "tr_123",
    refund_amount=500,                     # partial — leave full transfer for $20
    tags={"reason": "broken_widget"},
    idempotency_key="refund-tr_123-1",
)

Returns the reversal as a Transfer object. Pass refund_amount equal to transfer.amount for a full refund. See the dedicated Refunds page for the full pattern.

Object shape

Transfer:

Field	Type
`id`	`str`
`type`	`str \| None`
`state`	`str \| None`
`amount`	`int \| None`
`amount_requested`	`int \| None`
`currency`	`str \| None`
`source`	`str \| None`
`destination`	`str \| None`
`fee`	`int \| None`
`failure_code`	`str \| None`
`failure_message`	`str \| None`
`tags`	`dict[str, Any] \| None`
`created_at`	`str \| None`
`updated_at`	`str \| None`

Examples

Idempotent charge per order

import uuid

def charge_order(order):
    return client.transfers.create(
        amount=order.total_cents,
        currency=order.currency,
        source=order.payment_instrument_id,
        tags={"order_id": order.id},
        idempotency_key=f"order-{order.id}-charge",
    )

Pull the most recent transfers for reconciliation

transfers = client.transfers.list(limit=100)
for t in transfers:
    if t.state == "FAILED":
        log.warning("failed: %s — %s", t.id, t.failure_message)

Transfers

On this page