Transfers v2

Create and retrieve v2 transfers. A v2 transfer moves funds between two endpoints — a payment method, an account or a wallet — and every write carries an Idempotency-Key header.

The Transfers v2 object

Attributes
idstring

Unique identifier for the transfer.

objectstring

Object type identifier. Always transfer.

typeenum

What kind of movement this is. One of payment, payout, or account_transfer.

statusenum

The transfer's own status, summarizing its leg. reversed means a completed transfer was pulled back, as when a bank returns an ACH debit. One of pending, completed, failed, canceled, or reversed.

descriptionnullable string

The description you gave at creation.

amountdictionary

The amount you asked to move.

feedictionary

Fees taken from the amount.

net_amountdictionary

What reaches the destination: 0 until the transfer is completed, and 0 again once reversed.

sourcedictionary

Where the funds come from.

destinationdictionary

Where the funds go.

next_actiondictionary

Present when the payment is requires_3d_secure and a challenge is open. Omitted otherwise.

paymentdictionary

The payment leg. Present when type is payment.

payoutdictionary

The payout leg. Present when type is payout.

account_transferdictionary

The account transfer leg. Present when type is account_transfer.

referencenullable string

Your own reference for the transfer.

metadataobject

Key-value pairs you attached at creation.

livemodeboolean

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

createdinteger

Unix timestamp of when the transfer was created.

pending_atnullable integer

Unix timestamp of when the transfer became pending.

completed_atnullable integer

Unix timestamp of when the transfer completed.

failed_atnullable integer

Unix timestamp of when the transfer failed.

canceled_atnullable integer

Unix timestamp of when the transfer was canceled.

reversed_atnullable integer

Unix timestamp of when the transfer was reversed.

THE TRANSFERS V2 OBJECT
{
  "id": "e36c1cc2-d9f0-44db-a522-12b0aab990db",
  "object": "transfer",
  "type": "payment",
  "status": "pending",
  "description": "Order 42",
  "amount": {
    "value": 2500,
    "currency": "USD"
  },
  "fee": {
    "value": 2500,
    "currency": "USD"
  },
  "net_amount": {
    "value": 2500,
    "currency": "USD"
  },
  "source": {
    "payment_method": {
      "id": "c4d5e6f7-1234-5678-abcd-9e0a1b2c3d4e",
      "object": "payment_method",
      "type": "card",
      "status": "active",
      "created": 1721010605,
      "updated": 1721010605,
      "livemode": false,
      "customer_id": "235978d1-9081-45ce-a57d-e0a9659e8880",
      "account_id": null,
      "card": {
        "brand": "visa",
        "last_four": "4242",
        "exp_month": "12",
        "exp_year": "2027",
        "instant_available": true,
        "instant_unavailable_reason": null,
        "instant_steer_to": null,
        "wallet": {
          "type": "apple_pay",
          "dynamic_last4": "4242",
          "single_use": true,
          "consumed": false
        }
      },
      "ach": {
        "bank_name": "Chase",
        "last_four": "6789",
        "account_type": "checking",
        "routing_number": "110000000"
      },
      "billing": null,
      "verification": {
        "status": "requires_action",
        "card_verification_id": "9f8e7d6c-1234-5678-abcd-9e0a1b2c3d4e",
        "failure_reason": null,
        "next_action": {
          "type": "use_frame_sdk",
          "use_frame_sdk": {
            "source": "tds_session_1a2b3c",
            "directory_server_name": "visa",
            "challenge_url": null
          }
        }
      }
    },
    "account": {
      "id": "c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d",
      "object": "account",
      "type": "individual",
      "status": "active",
      "external_id": null,
      "profile": {
        "individual": {
          "email": "jenny.rosen@example.com",
          "name": {
            "first_name": "Jenny",
            "last_name": "Rosen"
          }
        }
      },
      "livemode": false,
      "created": 1745107200
    },
    "wallet": {
      "id": "g8h9i0j1-5678-9012-efab-3c4d5e6f7a8b",
      "object": "wallet"
    }
  },
  "destination": {
    "payment_method": {
      "id": "c4d5e6f7-1234-5678-abcd-9e0a1b2c3d4e",
      "object": "payment_method",
      "type": "card",
      "status": "active",
      "created": 1721010605,
      "updated": 1721010605,
      "livemode": false,
      "customer_id": "235978d1-9081-45ce-a57d-e0a9659e8880",
      "account_id": null,
      "card": {
        "brand": "visa",
        "last_four": "4242",
        "exp_month": "12",
        "exp_year": "2027",
        "instant_available": true,
        "instant_unavailable_reason": null,
        "instant_steer_to": null,
        "wallet": {
          "type": "apple_pay",
          "dynamic_last4": "4242",
          "single_use": true,
          "consumed": false
        }
      },
      "ach": {
        "bank_name": "Chase",
        "last_four": "6789",
        "account_type": "checking",
        "routing_number": "110000000"
      },
      "billing": null,
      "verification": {
        "status": "requires_action",
        "card_verification_id": "9f8e7d6c-1234-5678-abcd-9e0a1b2c3d4e",
        "failure_reason": null,
        "next_action": {
          "type": "use_frame_sdk",
          "use_frame_sdk": {
            "source": "tds_session_1a2b3c",
            "directory_server_name": "visa",
            "challenge_url": null
          }
        }
      }
    },
    "account": {
      "id": "c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d",
      "object": "account",
      "type": "individual",
      "status": "active",
      "external_id": null,
      "profile": {
        "individual": {
          "email": "jenny.rosen@example.com",
          "name": {
            "first_name": "Jenny",
            "last_name": "Rosen"
          }
        }
      },
      "livemode": false,
      "created": 1745107200
    },
    "wallet": {
      "id": "g8h9i0j1-5678-9012-efab-3c4d5e6f7a8b",
      "object": "wallet"
    }
  },
  "next_action": {
    "type": "use_frame_sdk",
    "use_frame_sdk": {
      "source": "tds_session_1a2b3c",
      "directory_server_name": "visa",
      "challenge_url": null
    }
  },
  "payment": {
    "status": "pending",
    "authorization_mode": "automatic",
    "receipt_email": "jenny.rosen@example.com",
    "statement_descriptor": "FRAME STORE",
    "product_id": "7a9c6b1d-2e4f-4a5b-8c7d-9e0f1a2b3c4d",
    "payment_link_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "subscription_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "invoice_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
    "cart_data": {
      "sku": "hat"
    },
    "amount_authorized": {
      "value": 2500,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 2500,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 2500,
      "currency": "USD"
    },
    "failure_code": "insufficient_funds",
    "failure_reason": "The customer's account has insufficient funds to cover this payment.",
    "shipping": {
      "name": "Jenny Rosen",
      "carrier": "usps",
      "tracking_number": "1Z999AA10123456784",
      "address": {
        "line_1": "600 California St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94108",
        "country": "US"
      }
    }
  },
  "payout": {
    "status": "pending",
    "rail": "ach",
    "speed": "standard",
    "failure_code": "no_account",
    "failure_reason": "The bank account could not be located."
  },
  "account_transfer": {
    "status": "pending",
    "failure_code": "processing_error",
    "failure_reason": "An error occurred while processing the transfer."
  },
  "reference": "ord_123",
  "metadata": {
    "order": "42"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": 1745107200,
  "completed_at": null,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": null
}

List transfers

Returns a paginated list of your transfers, newest first, each with its payment, payout or account_transfer leg. A key lists only the transfers of its own mode.

Query parameters
pageintegeroptional

Page number for pagination. Defaults to 1.

per_pageintegeroptional

Number of results per page. Defaults to 10, maximum 100.

Returns

A paginated list of transfers.

GET/v2/transfers
curl --request GET \
  --url https://api.framepayments.com/v2/transfers \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v2/transfers",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "status": "completed",
      "description": "Order 42",
      "object": "transfer",
      "type": "payment",
      "amount": {
        "value": 2500,
        "currency": "USD"
      },
      "fee": {
        "value": 0,
        "currency": "USD"
      },
      "net_amount": {
        "value": 2500,
        "currency": "USD"
      },
      "livemode": false,
      "created": 1745107200,
      "pending_at": null,
      "completed_at": 1745107200,
      "failed_at": null,
      "canceled_at": null,
      "reversed_at": null,
      "reference": null,
      "metadata": {},
      "source": {
        "payment_method": {
          "id": "00000000-0000-4000-8000-000000000002",
          "account_id": "00000000-0000-4000-8000-000000000003",
          "billing": null,
          "type": "ach",
          "object": "payment_method",
          "created": 1745107200,
          "updated": 1745107200,
          "livemode": false,
          "status": "active",
          "verification": {
            "status": "not_required",
            "card_verification_id": null,
            "failure_reason": null,
            "next_action": null
          },
          "ach": {
            "account_type": "checking",
            "bank_name": "Bank of America",
            "routing_number": "110000000",
            "last_four": "6789"
          }
        },
        "account": {
          "id": "00000000-0000-4000-8000-000000000003",
          "status": "active",
          "external_id": null,
          "object": "account",
          "type": "individual",
          "created": 1745107200,
          "livemode": false,
          "profile": {
            "individual": {
              "email": "marica_rodriguez@bernier.example",
              "ssn_last_four": null,
              "name": {
                "first_name": "Cleotilde",
                "middle_name": null,
                "last_name": "Wisoky",
                "suffix": null
              },
              "phone": {
                "number": null,
                "country_code": null
              },
              "address": null,
              "birthdate": null
            }
          }
        }
      },
      "destination": {
        "account": {
          "id": "00000000-0000-4000-8000-000000000004",
          "status": "active",
          "external_id": null,
          "object": "account",
          "type": "business",
          "created": 1745107200,
          "livemode": false,
          "profile": null
        }
      },
      "payment": {
        "status": "succeeded",
        "statement_descriptor": "frame",
        "amount_authorized": {
          "value": 0,
          "currency": "USD"
        },
        "amount_captured": {
          "value": 2500,
          "currency": "USD"
        },
        "amount_refunded": {
          "value": 0,
          "currency": "USD"
        }
      }
    }
  ]
}

Create transfer

Creates a transfer. A payment transfer debits its source: a saved payment method by payment_method_id, an account's default one by account_id, or an inline payment_method. Without a destination the funds settle to your platform's own account.

A bank account source makes an ACH payment: USD only, with no destination and no authorization_mode. It answers 201 with status: pending and settles asynchronously, so follow it through the transfer.payment.* webhook events or by polling the transfer.

Repeating an Idempotency-Key with the same body replays the original response with Idempotent-Replay: true; repeating it with a different body answers 400.

A checkout session minted with a locked amount (Authorization: Bearer chk_sess_…) can create a payment for its account. The amount must match the locked amount, and the source must belong to that account. Capture, void, refund, update, and list stay on the secret key. A session minted without an amount cannot move money.

Header parameters
Idempotency-Keystring

A unique key for this write, at most 255 characters. Reuse it to replay the same response safely.

Body parameters
amountdictionary

The amount to move.

sourcedictionary

Where the funds come from. Exactly one of its keys.

destinationdictionaryoptional

Where the funds go. A payment defaults to your platform's own account; a payout names a payment method with a rail and speed.

confirmboolean

false leaves the payment in requires_confirmation for the confirm endpoint.

authorization_modeenumoptional

Required for a card payment. manual holds the authorization for the capture endpoint. One of automatic or manual.

descriptionstringoptional

A description for your own records.

referencestringoptional

Your own reference for the transfer.

receipt_emailstringoptional

Email address to send the receipt to.

statement_descriptorstringoptional

Text for the customer's statement, 5 to 22 characters.

product_idstringoptional

ID of the product being paid for.

payment_link_idstringoptional

ID of the payment link the payment came from.

subscription_idstringoptional

ID of the subscription being billed.

invoice_idstringoptional

ID of the invoice being settled.

shippingobjectoptional

Shipping details: the address fields plus name, phone, carrier and tracking_number.

account_fundingdictionaryoptional

Who the cardholder is funding. Omit it when the cardholder funds their own account. When present, recipient is required. Merchants never send CR or the scheme account-type codes; Frame sends those to Visa only for a Visa purchase at MCC 6051. Not returned on the transfer.

cart_dataobjectoptional

The cart being paid for, up to 32 KB of JSON.

metadataobjectoptional

Key-value pairs to attach to the transfer.

Returns

Returns the transfer object.

POST/v2/transfers
curl --request POST \
  --url https://api.framepayments.com/v2/transfers \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Idempotency-Key: <value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": {
    "value": 2500,
    "currency": "usd"
  },
  "source": {
    "payment_method_id": "2a769159-83b7-4b78-8a07-3e5891a414d2",
    "account_id": "c1a4a27f-d6e4-46e2-9557-fd5faaa31e7d"
  },
  "confirm": true
}'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "fee": {
    "value": 0,
    "currency": "USD"
  },
  "type": "payment",
  "amount": {
    "value": 2500,
    "currency": "USD"
  },
  "object": "transfer",
  "source": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000002",
      "type": "individual",
      "object": "account",
      "status": "active",
      "created": 1745107200,
      "profile": {
        "individual": {
          "name": {
            "suffix": null,
            "last_name": "Carter",
            "first_name": "Lizzie",
            "middle_name": null
          },
          "email": "gabriele.rohan@roob.example",
          "phone": {
            "number": null,
            "country_code": null
          },
          "address": null,
          "birthdate": null,
          "ssn_last_four": null
        }
      },
      "livemode": false,
      "external_id": null
    },
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000003",
      "ach": {
        "bank_name": "Bank of America",
        "last_four": "6789",
        "account_type": "checking",
        "routing_number": "110000000"
      },
      "type": "ach",
      "object": "payment_method",
      "status": "active",
      "billing": null,
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "account_id": "00000000-0000-4000-8000-000000000002",
      "verification": {
        "status": "not_required",
        "next_action": null,
        "failure_reason": null,
        "card_verification_id": null
      }
    }
  },
  "status": "pending",
  "created": 1745107200,
  "payment": {
    "status": "pending",
    "amount_captured": {
      "value": 0,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 0,
      "currency": "USD"
    },
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "statement_descriptor": "frame"
  },
  "livemode": false,
  "metadata": {},
  "failed_at": null,
  "reference": null,
  "net_amount": {
    "value": 0,
    "currency": "USD"
  },
  "pending_at": null,
  "canceled_at": null,
  "description": "Order 42",
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "type": "business",
      "object": "account",
      "status": "active",
      "created": 1745107200,
      "profile": null,
      "livemode": false,
      "external_id": null
    }
  },
  "reversed_at": null,
  "completed_at": null
}

Get transfer

Retrieves one transfer by ID with its current status and its payment, payout or account_transfer leg. A transfer that belongs to another platform or the other mode answers 404.

A checkout session with a locked amount can retrieve a transfer it created. Any other transfer answers 404. While the payment is requires_3d_secure, the response includes next_action.use_frame_sdk.source, the Evervault session id a client mounts.

Path parameters
idstring

Transfer ID

Returns

Returns the transfer object.

GET/v2/transfers/{id}
curl --request GET \
  --url https://api.framepayments.com/v2/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "completed",
  "description": "Order 42",
  "object": "transfer",
  "type": "payment",
  "amount": {
    "value": 2500,
    "currency": "USD"
  },
  "fee": {
    "value": 0,
    "currency": "USD"
  },
  "net_amount": {
    "value": 2500,
    "currency": "USD"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": null,
  "completed_at": 1745107200,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": null,
  "reference": null,
  "metadata": {},
  "source": {
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000002",
      "account_id": "00000000-0000-4000-8000-000000000003",
      "billing": null,
      "type": "ach",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "verification": {
        "status": "not_required",
        "card_verification_id": null,
        "failure_reason": null,
        "next_action": null
      },
      "ach": {
        "account_type": "checking",
        "bank_name": "Bank of America",
        "routing_number": "110000000",
        "last_four": "6789"
      }
    },
    "account": {
      "id": "00000000-0000-4000-8000-000000000003",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "individual",
      "created": 1745107200,
      "livemode": false,
      "profile": {
        "individual": {
          "email": "leonia.blick@walsh-conn.example",
          "ssn_last_four": null,
          "name": {
            "first_name": "Vania",
            "middle_name": null,
            "last_name": "Cummerata",
            "suffix": null
          },
          "phone": {
            "number": null,
            "country_code": null
          },
          "address": null,
          "birthdate": null
        }
      }
    }
  },
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "business",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "payment": {
    "status": "succeeded",
    "statement_descriptor": "frame",
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 2500,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 0,
      "currency": "USD"
    }
  }
}

Confirm transfer

Confirms a payment created with confirm: false, applying any properties in the body first. A payment that is not waiting in requires_confirmation answers 422, so a repeated confirm never debits twice.

The checkout session that created the transfer can confirm it. The browser sends no body. An open 3DS challenge stays requires_3d_secure. A finished challenge completes the payment.

Path parameters
idstring

Transfer ID

Body parameters
amountdictionaryoptional

A new amount.

sourcedictionaryoptional

A different payment method to debit.

descriptionstringoptional

A new description.

receipt_emailstringoptional

Email address to send the receipt to.

statement_descriptorstringoptional

Text for the customer's statement, 5 to 22 characters.

metadataobjectoptional

Key-value pairs to attach to the transfer.

Returns

Returns the transfer object.

POST/v2/transfers/{id}/confirm
curl --request POST \
  --url https://api.framepayments.com/v2/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/confirm \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "pending",
  "description": "Order 42",
  "object": "transfer",
  "type": "payment",
  "amount": {
    "value": 2500,
    "currency": "USD"
  },
  "fee": {
    "value": 0,
    "currency": "USD"
  },
  "net_amount": {
    "value": 0,
    "currency": "USD"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": null,
  "completed_at": null,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": null,
  "reference": null,
  "metadata": {},
  "source": {
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000002",
      "account_id": "00000000-0000-4000-8000-000000000003",
      "billing": null,
      "type": "ach",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "verification": {
        "status": "not_required",
        "card_verification_id": null,
        "failure_reason": null,
        "next_action": null
      },
      "ach": {
        "account_type": "checking",
        "bank_name": "Bank of America",
        "routing_number": "110000000",
        "last_four": "6789"
      }
    },
    "account": {
      "id": "00000000-0000-4000-8000-000000000003",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "individual",
      "created": 1745107200,
      "livemode": false,
      "profile": {
        "individual": {
          "email": "madeleine.gutkowski@anderson.example",
          "ssn_last_four": null,
          "name": {
            "first_name": "Scot",
            "middle_name": null,
            "last_name": "McLaughlin",
            "suffix": null
          },
          "phone": {
            "number": null,
            "country_code": null
          },
          "address": null,
          "birthdate": null
        }
      }
    }
  },
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "business",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "payment": {
    "status": "pending",
    "statement_descriptor": "frame",
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 0,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 0,
      "currency": "USD"
    }
  }
}

Refund transfer

Refunds a succeeded card payment, in full or for the amount given. An ACH payment cannot be refunded and answers 422.

Path parameters
idstring

Transfer ID

Body parameters
amountdictionaryoptional

The amount to refund. Defaults to everything captured.

Returns

Returns the transfer object.

POST/v2/transfers/{id}/refund
curl --request POST \
  --url https://api.framepayments.com/v2/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/refund \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "completed",
  "description": "Order 42",
  "object": "transfer",
  "type": "payment",
  "amount": {
    "value": 1000,
    "currency": "USD"
  },
  "fee": {
    "value": 74,
    "currency": "USD"
  },
  "net_amount": {
    "value": 926,
    "currency": "USD"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": null,
  "completed_at": 1745107200,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": null,
  "reference": null,
  "metadata": {},
  "source": {
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000002",
      "account_id": "00000000-0000-4000-8000-000000000003",
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "12",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242",
        "instant_available": false,
        "instant_unavailable_reason": "card_not_debit",
        "instant_steer_to": "bank_account"
      },
      "verification": {
        "status": "not_required",
        "card_verification_id": null,
        "failure_reason": null,
        "next_action": null
      }
    },
    "account": {
      "id": "00000000-0000-4000-8000-000000000003",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "individual",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "business",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "payment": {
    "status": "refunded",
    "authorization_mode": "automatic",
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 1000,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 1000,
      "currency": "USD"
    }
  }
}

Capture transfer

Captures a card payment authorized in manual mode, for the authorized amount or the smaller amount given. Any other payment, including every ACH payment, answers 422.

Path parameters
idstring

Transfer ID

Body parameters
amountdictionaryoptional

The amount to capture. Defaults to the whole authorization.

Returns

Returns the transfer object.

POST/v2/transfers/{id}/capture
curl --request POST \
  --url https://api.framepayments.com/v2/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/capture \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "completed",
  "description": "Order 42",
  "object": "transfer",
  "type": "payment",
  "amount": {
    "value": 1000,
    "currency": "USD"
  },
  "fee": {
    "value": 74,
    "currency": "USD"
  },
  "net_amount": {
    "value": 926,
    "currency": "USD"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": null,
  "completed_at": 1745107200,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": null,
  "reference": null,
  "metadata": {},
  "source": {
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000002",
      "account_id": "00000000-0000-4000-8000-000000000003",
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "12",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242",
        "instant_available": false,
        "instant_unavailable_reason": "card_not_debit",
        "instant_steer_to": "bank_account"
      },
      "verification": {
        "status": "not_required",
        "card_verification_id": null,
        "failure_reason": null,
        "next_action": null
      }
    },
    "account": {
      "id": "00000000-0000-4000-8000-000000000003",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "individual",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "business",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "payment": {
    "status": "succeeded",
    "authorization_mode": "manual",
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 1000,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 0,
      "currency": "USD"
    }
  }
}

Void transfer

Releases a card authorization that has not been captured: the payment becomes canceled and the transfer reversed. A payment in any other state, including every ACH payment, answers 422.

Path parameters
idstring

Transfer ID

Returns

Returns the transfer object.

POST/v2/transfers/{id}/void
curl --request POST \
  --url https://api.framepayments.com/v2/transfers/a70cd72f-e74a-40f2-96a2-3f60714aac4a/void \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "reversed",
  "description": "Order 42",
  "object": "transfer",
  "type": "payment",
  "amount": {
    "value": 1000,
    "currency": "USD"
  },
  "fee": {
    "value": 0,
    "currency": "USD"
  },
  "net_amount": {
    "value": 0,
    "currency": "USD"
  },
  "livemode": false,
  "created": 1745107200,
  "pending_at": null,
  "completed_at": null,
  "failed_at": null,
  "canceled_at": null,
  "reversed_at": 1745107200,
  "reference": null,
  "metadata": {},
  "source": {
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000002",
      "account_id": "00000000-0000-4000-8000-000000000003",
      "billing": null,
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "12",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242",
        "instant_available": false,
        "instant_unavailable_reason": "card_not_debit",
        "instant_steer_to": "bank_account"
      },
      "verification": {
        "status": "not_required",
        "card_verification_id": null,
        "failure_reason": null,
        "next_action": null
      }
    },
    "account": {
      "id": "00000000-0000-4000-8000-000000000003",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "individual",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "destination": {
    "account": {
      "id": "00000000-0000-4000-8000-000000000004",
      "status": "active",
      "external_id": null,
      "object": "account",
      "type": "business",
      "created": 1745107200,
      "livemode": false,
      "profile": null
    }
  },
  "payment": {
    "status": "canceled",
    "authorization_mode": "manual",
    "amount_authorized": {
      "value": 0,
      "currency": "USD"
    },
    "amount_captured": {
      "value": 0,
      "currency": "USD"
    },
    "amount_refunded": {
      "value": 0,
      "currency": "USD"
    }
  }
}
Frame Assistant

Ask anything about Frame's APIs and products