Transfers

Create and retrieve transfers. Transfers move funds between your platform and connected accounts.

The Transfer object

Attributes
idstring

Unique identifier for the transfer.

objectstring

Object type identifier. Always transfer.

statusenum

Current status. One of pending, incomplete, requires_account_or_customer, requires_payment_method, requires_confirmation, requires_3d_secure, requires_capture, processing, succeeded, failed, expired, canceled, reversed, refunded, or disputed.

amountinteger

Requested transfer amount in the smallest currency unit (e.g. cents). 10000 represents $100.00.

currencystring

Three-letter ISO currency code in uppercase (e.g. USD).

platform_feeinteger

Fee earned by the platform on this transfer, in cents.

frame_feeinteger

Frame's processing fee for this transfer, in cents.

total_feesinteger

Sum of platform_fee and frame_fee in cents.

gross_amountinteger

Gross transaction amount in cents. For charge flows in add_on mode this is the grossed-up amount; otherwise equals amount.

net_amountinteger

Amount received by the payee in cents after fees.

descriptionnullable string

Optional description provided at creation.

failure_reasonnullable string

Human-readable reason when status is failed. null otherwise.

charge_intentnullable string

ID of the associated charge intent for charge flows. null for payout flows.

payoutnullable string

ID of the associated payout for payout flows. null for charge flows.

billing_agreementnullable string

ID of the billing agreement used to calculate fees.

client_secretnullable string

Client secret for deferred-confirm flows. null for standard payout flows.

accountstring

ID of the account associated with this transfer.

account_idstring

ID of the account associated with this transfer.

source_payment_methoddictionary

The payment method charged in charge flows. null for payout flows.

destination_payment_methoddictionary

The payment method funds are sent to in payout flows. null when omitted in charge flows.

metadataobject

Key-value pairs attached to the transfer for your own reference.

livemodeboolean

true if the transfer exists in live mode, false for test mode.

createdinteger

Unix timestamp of when the transfer was created.

THE TRANSFER OBJECT
{
  "id": "e36c1cc2-d9f0-44db-a522-12b0aab990db",
  "object": "transfer",
  "status": "pending",
  "amount": 10000,
  "currency": "USD",
  "platform_fee": 100,
  "frame_fee": 15,
  "total_fees": 115,
  "gross_amount": 10000,
  "net_amount": 9885,
  "description": "Weekly payout",
  "failure_reason": null,
  "charge_intent": null,
  "payout": null,
  "billing_agreement": "b37da62b-c233-4358-967a-7910656fb94f",
  "client_secret": null,
  "account": "c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d",
  "account_id": "c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d",
  "source_payment_method": {
    "id": "2a769159-83b7-4b78-8a07-3e5891a414d2",
    "object": "payment_method",
    "type": "card",
    "status": "active",
    "livemode": false,
    "created": 1773398080,
    "updated": 1773398080
  },
  "destination_payment_method": {
    "id": "2a769159-83b7-4b78-8a07-3e5891a414d2",
    "object": "payment_method",
    "type": "ach",
    "status": "active",
    "livemode": false,
    "created": 1773398080,
    "updated": 1773398080
  },
  "metadata": {},
  "livemode": false,
  "created": 1773415510
}

List transfer billing agreements

Returns a paginated list of transfer billing agreements for the authenticated merchant.

Query parameters
pageintegeroptional
per_pageintegeroptional

Max 100

Returns

Billing agreements retrieved

GET/v1/transfer_billing_agreements
curl --request GET \
  --url https://api.framepayments.com/v1/transfer_billing_agreements \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/transfer_billing_agreements",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "7367161c-d1f0-43a9-a8f7-64efc42019ce",
      "status": "pending",
      "category": "charge",
      "effective_date": "2026-06-10T18:24:51.458Z",
      "object": "transfer_billing_agreement",
      "account_id": null,
      "created": 1781115891,
      "updated": 1781115891,
      "fee_plan": {
        "id": "92557df0-f6b7-494f-813e-c174b557f483",
        "name": "Standard Platform Fee",
        "fee_application_mode": "deduct",
        "object": "transfer_fee_plan",
        "created": 1781115891,
        "updated": 1781115891,
        "items": []
      }
    },
    {
      "id": "403695a4-76d9-47c2-a586-a012f3d664a6",
      "status": "active",
      "category": "payout",
      "effective_date": "2026-06-10T18:24:51.435Z",
      "object": "transfer_billing_agreement",
      "account_id": null,
      "created": 1781115891,
      "updated": 1781115891,
      "fee_plan": {
        "id": "05086203-7bc9-46cf-bca1-d330f4f4a178",
        "name": "Standard Platform Fee",
        "fee_application_mode": "deduct",
        "object": "transfer_fee_plan",
        "created": 1781115891,
        "updated": 1781115891,
        "items": []
      }
    },
    {
      "id": "b39e850a-3a18-43c2-839b-0f65b59a9dc2",
      "status": "active",
      "category": "charge",
      "effective_date": "2026-06-10T18:24:51.429Z",
      "object": "transfer_billing_agreement",
      "account_id": null,
      "created": 1781115891,
      "updated": 1781115891,
      "fee_plan": {
        "id": "05086203-7bc9-46cf-bca1-d330f4f4a178",
        "name": "Standard Platform Fee",
        "fee_application_mode": "deduct",
        "object": "transfer_fee_plan",
        "created": 1781115891,
        "updated": 1781115891,
        "items": []
      }
    }
  ]
}

Create a transfer billing agreement

Creates a transfer billing agreement, linking a fee plan to an account. Billing agreements determine which fee plan applies when transfers are made for or to a specific account. Provide either a charge or payout category to govern the corresponding transfer type.

Query parameters
transfer_fee_plan_idstringrequired

ID of the fee plan to apply

categorystringrequired

charge or payout

effective_datestringrequired

ISO 8601 date when this agreement takes effect

account_idstringoptional

Account to associate with this agreement

statusstringoptional

pending (default) or active

Returns

Billing agreement created

POST/v1/transfer_billing_agreements
curl --request POST \
  --url https://api.framepayments.com/v1/transfer_billing_agreements \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "e923d8ed-44d8-4189-ae13-891fb75d9e9c",
  "status": "pending",
  "category": "charge",
  "effective_date": "2026-06-10T18:24:51.623Z",
  "object": "transfer_billing_agreement",
  "account_id": null,
  "created": 1781115891,
  "updated": 1781115891,
  "fee_plan": {
    "id": "a3b8d0ed-cf85-4fad-9fb5-279b5abb6374",
    "name": "Standard Platform Fee",
    "fee_application_mode": "deduct",
    "object": "transfer_fee_plan",
    "created": 1781115891,
    "updated": 1781115891,
    "items": []
  }
}

Retrieve a transfer billing agreement

Retrieves a transfer billing agreement by ID, including the associated fee plan.

Path parameters
idstringrequired

Billing agreement ID

Returns

Billing agreement retrieved

GET/v1/transfer_billing_agreements/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/transfer_billing_agreements/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "1d3fd369-3446-414d-99bc-331612c79b53",
  "status": "pending",
  "category": "charge",
  "effective_date": "2026-06-10T18:24:51.773Z",
  "object": "transfer_billing_agreement",
  "account_id": null,
  "created": 1781115891,
  "updated": 1781115891,
  "fee_plan": {
    "id": "02bd87d6-21c0-4680-be9f-71c2b2d2b70b",
    "name": "Standard Platform Fee",
    "fee_application_mode": "deduct",
    "object": "transfer_fee_plan",
    "created": 1781115891,
    "updated": 1781115891,
    "items": []
  }
}

Update a transfer billing agreement

Updates a transfer billing agreement. Currently only the status can be updated.

Path parameters
idstringrequired

Billing agreement ID

Query parameters
statusstringrequired

New status: pending, active, or inactive

Returns

Billing agreement updated

PATCH/v1/transfer_billing_agreements/{id}
curl --request PATCH \
  --url https://api.framepayments.com/v1/transfer_billing_agreements/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "77f40d5b-a6d9-4057-8d0b-e79b83249372",
  "status": "pending",
  "category": "charge",
  "effective_date": "2026-06-10T18:24:51.959Z",
  "object": "transfer_billing_agreement",
  "account_id": null,
  "created": 1781115891,
  "updated": 1781115891,
  "fee_plan": {
    "id": "96122d1e-82b9-4910-ba45-724eb33b3b48",
    "name": "Standard Platform Fee",
    "fee_application_mode": "deduct",
    "object": "transfer_fee_plan",
    "created": 1781115891,
    "updated": 1781115891,
    "items": []
  }
}

List transfer fee plans

Returns a paginated list of transfer fee plans for the authenticated merchant.

Query parameters
pageintegeroptional
per_pageintegeroptional

Max 100

Returns

Fee plans retrieved

GET/v1/transfer_fee_plans
curl --request GET \
  --url https://api.framepayments.com/v1/transfer_fee_plans \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/transfer_fee_plans",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "b19cd75f-8502-47be-a515-e95e1f899478",
      "name": "Standard Platform Fee",
      "fee_application_mode": "deduct",
      "object": "transfer_fee_plan",
      "created": 1781115892,
      "updated": 1781115892,
      "items": []
    },
    {
      "id": "71e35cf1-94e8-40ae-bf3a-4e53d6629ac5",
      "name": "Standard Platform Fee",
      "fee_application_mode": "deduct",
      "object": "transfer_fee_plan",
      "created": 1781115892,
      "updated": 1781115892,
      "items": []
    }
  ]
}

Create a transfer fee plan

Creates a transfer fee plan defining how fees are calculated and applied to transfers. Fee plans are attached to billing agreements which associate them with specific accounts.

Query parameters
namestringrequired

Descriptive name

fee_application_modestringrequired

deduct, add_on, or absorb

Returns

Fee plan created

POST/v1/transfer_fee_plans
curl --request POST \
  --url https://api.framepayments.com/v1/transfer_fee_plans \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "c61fccd8-8d5e-4416-b51a-1a1e6368f73b",
  "name": "Standard Platform Fee",
  "fee_application_mode": "deduct",
  "object": "transfer_fee_plan",
  "created": 1781115892,
  "updated": 1781115892,
  "items": []
}

Retrieve a transfer fee plan

Retrieves a transfer fee plan by ID, including all fee line items.

Path parameters
idstringrequired

Fee plan ID

Returns

Fee plan retrieved

GET/v1/transfer_fee_plans/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/transfer_fee_plans/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "3f305daf-dbcc-4fce-9200-b7284239df08",
  "name": "Standard Platform Fee",
  "fee_application_mode": "deduct",
  "object": "transfer_fee_plan",
  "created": 1781115892,
  "updated": 1781115892,
  "items": []
}

List transfers

Returns all transfers for the authenticated merchant, ordered by most recently created. Results are scoped to the current environment (test vs. live mode).

Query parameters
pageintegeroptional

Page number.

per_pageintegeroptional

Number of results per page.

Returns

Returns a paginated list of transfer objects.

GET/v1/transfers
curl --request GET \
  --url https://api.framepayments.com/v1/transfers \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/transfers",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "173e4688-4c07-4a6d-9d68-1bf9fd756362",
      "status": "pending",
      "description": null,
      "failure_reason": null,
      "object": "transfer",
      "amount": 10000,
      "currency": "USD",
      "platform_fee": 100,
      "frame_fee": 15,
      "total_fees": 115,
      "gross_amount": 10000,
      "net_amount": 9885,
      "livemode": false,
      "created": 1781115892,
      "account": "5333ccdd-1a48-442e-ad6c-8812515e4f5a",
      "account_id": "5333ccdd-1a48-442e-ad6c-8812515e4f5a",
      "charge_intent": null,
      "payout": null,
      "billing_agreement": null,
      "client_secret": null,
      "metadata": {},
      "source_payment_method": {
        "id": "eeb7a703-31aa-4b64-a8f2-218a4422b10c",
        "customer_id": null,
        "account_id": null,
        "billing": null,
        "type": "card",
        "object": "payment_method",
        "created": 1781115892,
        "updated": 1781115892,
        "livemode": false,
        "status": "active",
        "card": {
          "brand": "visa",
          "exp_month": "02",
          "exp_year": "31",
          "issuer": null,
          "currency": null,
          "segment": null,
          "type": null,
          "last_four": "4242"
        }
      },
      "destination_payment_method": {
        "id": "bb8ec839-9240-4210-b38b-005eba60fc6e",
        "customer_id": null,
        "account_id": null,
        "billing": null,
        "type": "card",
        "object": "payment_method",
        "created": 1781115892,
        "updated": 1781115892,
        "livemode": false,
        "status": "active",
        "card": {
          "brand": "visa",
          "exp_month": "10",
          "exp_year": "31",
          "issuer": null,
          "currency": null,
          "segment": null,
          "type": null,
          "last_four": "4242"
        }
      }
    }
  ]
}

Create transfer

Creates a new transfer. Provide source_payment_method_id for inbound (charge) flows or destination_payment_method_id for outbound (payout) flows.

For charge flows, the source payment method is charged and the transfer moves to succeeded. For payout flows, the transfer starts as pending and transitions to processing, then succeeded or failed once the processor responds.

Body parameters
amountintegerrequired

Amount in the smallest currency unit (e.g. 10000 for $100.00). Must be greater than 0.

account_idstringrequired

ID of the account associated with the transfer.

currencystringoptional

ISO currency code (e.g. USD). Defaults to USD.

source_payment_method_idstringoptional

Required for charge flows. The payment method to charge. Omit for payout flows.

destination_payment_method_idstringoptional

Required for payout flows (must be ACH or debit card). Optional for charge flows — when provided, funds go to the account that owns the payment method; when omitted, funds go to the merchant.

descriptionstringoptional

Arbitrary description for your records.

metadataobjectoptional

Key-value pairs to attach to the transfer.

confirmbooleanoptional

Whether to immediately confirm the transfer. Defaults to true. Setting to false returns the transfer in requires_confirmation for later confirmation via POST /v1/transfers/:id/confirm. Only supported for charge-backed transfers.

promotion_codesarrayoptional

Promotion code identifiers to apply as discounts on the underlying charge. Only supported for charge-backed transfers (requires source_payment_method_id). Invalid codes are silently skipped; the transfer proceeds without their discount.

sonar_session_idstringoptional

Identifier for an existing fraud-evaluation session (also known as charge_session_id) to attach to the underlying charge. Only supported for charge-backed transfers (requires source_payment_method_id).

Returns

Returns the created transfer object.

POST/v1/transfers
curl --request POST \
  --url https://api.framepayments.com/v1/transfers \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 0,
  "account_id": null
}'
RESPONSE
{
  "id": "d9656de6-3dcc-4fea-8aa3-8bd041c5520f",
  "status": "pending",
  "description": null,
  "failure_reason": null,
  "object": "transfer",
  "amount": 10000,
  "currency": "USD",
  "platform_fee": 100,
  "frame_fee": 15,
  "total_fees": 115,
  "gross_amount": 10000,
  "net_amount": 9885,
  "livemode": false,
  "created": 1781115892,
  "account": "314fad50-4597-403a-8a08-4d24f4f8e71f",
  "account_id": "314fad50-4597-403a-8a08-4d24f4f8e71f",
  "charge_intent": null,
  "payout": null,
  "billing_agreement": null,
  "client_secret": null,
  "metadata": {},
  "source_payment_method": null,
  "destination_payment_method": {
    "id": "6b3fe88f-9379-4c2e-89a3-33f2a14fa87a",
    "customer_id": null,
    "account_id": null,
    "billing": null,
    "type": "card",
    "object": "payment_method",
    "created": 1781115892,
    "updated": 1781115892,
    "livemode": false,
    "status": "active",
    "card": {
      "brand": "visa",
      "exp_month": "01",
      "exp_year": "31",
      "issuer": null,
      "currency": null,
      "segment": null,
      "type": null,
      "last_four": "4242"
    }
  }
}

Get transfer

Retrieves the details of an existing transfer by its ID. Returns the transfer object if found.

Path parameters
idstringrequired

The ID of the transfer to retrieve.

Returns

Returns the transfer object.

GET/v1/transfers/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "3af2b1a9-be27-4d06-a20f-9cf544099847",
  "status": "pending",
  "description": null,
  "failure_reason": null,
  "object": "transfer",
  "amount": 10000,
  "currency": "USD",
  "platform_fee": 100,
  "frame_fee": 15,
  "total_fees": 115,
  "gross_amount": 10000,
  "net_amount": 9885,
  "livemode": false,
  "created": 1781115893,
  "account": "bb34d593-83c0-466d-9a88-fbc0b145e003",
  "account_id": "bb34d593-83c0-466d-9a88-fbc0b145e003",
  "charge_intent": null,
  "payout": null,
  "billing_agreement": null,
  "client_secret": null,
  "metadata": {},
  "source_payment_method": {
    "id": "b2aa8c8d-6e00-4db7-97f6-d50324744d65",
    "customer_id": null,
    "account_id": null,
    "billing": null,
    "type": "card",
    "object": "payment_method",
    "created": 1781115893,
    "updated": 1781115893,
    "livemode": false,
    "status": "active",
    "card": {
      "brand": "visa",
      "exp_month": "03",
      "exp_year": "31",
      "issuer": null,
      "currency": null,
      "segment": null,
      "type": null,
      "last_four": "4242"
    }
  },
  "destination_payment_method": {
    "id": "8d668278-19dd-4e6c-bbb7-283c4b61ca32",
    "customer_id": null,
    "account_id": null,
    "billing": null,
    "type": "card",
    "object": "payment_method",
    "created": 1781115893,
    "updated": 1781115893,
    "livemode": false,
    "status": "active",
    "card": {
      "brand": "visa",
      "exp_month": "11",
      "exp_year": "31",
      "issuer": null,
      "currency": null,
      "segment": null,
      "type": null,
      "last_four": "4242"
    }
  }
}