Charge Intent
A Charge Intent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one Charge Intent for each order or customer session in your system. You can reference the Charge Intent later to see the history of payment attempts for a particular session.
A Charge Intent transitions through multiple statuses throughout its lifetime as it interfaces with Frame.js to perform authentication flows and ultimately creates at most one successful charge.
The Charge Intent object
Attributes
Unique identifier for the object.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Status of this Charge Intent, one of incomplete, pending, canceled, refunded, reversed, failed, disputed, or succeeded.
An arbitrary string attached to the object. Often useful for displaying to users.
Amount intended to be collected by this Charge Intent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00, a zero-decimal currency).
Amount that has been captured from this Charge Intent. A positive integer representing how much has been captured in the smallest currency unit (e.g., 100 cents equals $1.00).
Amount that has been voided from this Charge Intent. A positive integer representing how much has been voided in the smallest currency unit (e.g., 100 cents equals $1.00).
The client secret of this Charge Intent. Used for client-side retrieval using a publishable key.
Use the client_secret to complete payments from your frontend with Frame.js. Never store, log, or expose this value to anyone other than the customer. Always use HTTPS on pages that include the client secret.
See our docs to accept a payment for proper client_secret handling.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
The latest charge attempt of this Charge Intent.
ID of the Customer this Charge Intent belongs to, if one exists.
ID of the payment method used in this Charge Intent.
ID of the invoice associated with this Charge Intent.
ID of the subscription associated with this Charge Intent.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Shipping information for this Charge Intent.
String representing the object's type. Objects of the same type share the same value.
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was last updated. Measured in seconds since the Unix epoch.
{
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"currency": "usd",
"latest_charge": null,
"customer": {
"id": "235978d1-9081-45ce-a57d-e0a9659e8880",
"created": 1721007463,
"shipping_address": null,
"updated": 1721007463,
"livemode": false,
"name": "Amb. Gilberto Nitzsche",
"phone": "+13159403449",
"email": "gilberto+amb.+nitzsche@gmail.com",
"description": null,
"object": "customer",
"metadata": [],
"billing_address": null
},
"payment_method": {
"id": "6c99a959-da90-4f18-a93f-9fd7a8080c17",
"customer": null,
"billing": null,
"type": "card",
"object": "payment_method",
"created": 1721009419,
"updated": 1721009419,
"livemode": false,
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "29",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"shipping": null,
"metadata": {},
"client_secret": "ci_a70cd72f-e74a-40f2-96a2-3f60714aac4a_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"subscription": null,
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"amount_captured": 0,
"amount_voided": 0,
"invoice": null,
"created": 1721010605,
"updated": 1721010605,
"livemode": false
}
Create a Charge Intent
Creates a Charge Intent object.
After the Charge Intent is created, attach a payment method and confirm to continue the payment. When you use confirm=true during creation, it's equivalent to creating and confirming the Charge Intent in the same call. You can use any parameters available in the confirm API when you supply confirm=true.
Parameters
Amount intended to be collected by this Charge Intent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00, a zero-decimal currency).
Three-letter ISO currency code, in lowercase. Must be a supported currency.
ID of the Customer this Charge Intent belongs to, if one exists.
Payment methods attached to other Customers cannot be used with this Charge Intent.
An arbitrary string attached to the object. Often useful for displaying to users.
ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this Charge Intent.
Set to true to attempt to confirm this Charge Intent immediately. This parameter defaults to false. When creating and confirming a Charge Intent at the same time, you can also provide the parameters available in the Confirm API.
Email address to send the receipt to. If you specify receipt_email for a payment in live mode, you send a receipt regardless of your email settings.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Controls when the funds will be captured from the customer's account.
If provided, this hash will be used to create a Customer. The new Customer will appear in the customer property on the Charge Intent.
If provided, this hash will be used to create a PaymentMethod. The new PaymentMethod will appear in the payment_method property on the Charge Intent.
Use this to provide configurations that are specific to the payment method being used in this Charge Intent.
An array of promotion codes to apply to this Charge Intent to apply discounts.
Returns
Returns a Charge Intent object.
curl --request POST \
--url https://api.framepayments.com/v1/charge_intents \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2000,
"currency": "usd",
"customer": "235978d1-9081-45ce-a57d-e0a9659e8880",
"description": "Payment",
"payment_method": "6c99a959-da90-4f18-a93f-9fd7a8080c17",
"confirm": false,
"promotion_codes": ["SUMMER2024"]
}'
{
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"currency": "usd",
"latest_charge": null,
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_a70cd72f-e74a-40f2-96a2-3f60714aac4a_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
}
Update a Charge Intent
Updates properties on a Charge Intent object without confirming.
Depending on which properties you update, you might need to confirm the Charge Intent again. For example, updating the payment_method always requires you to confirm the Charge Intent again. If you prefer to update and confirm at the same time, we recommend updating properties through the confirm API instead.
Parameters
Amount intended to be collected by this Charge Intent. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00, a zero-decimal currency).
ID of the Customer this Charge Intent belongs to, if one exists.
Payment methods attached to other Customers cannot be used with this Charge Intent.
An arbitrary string attached to the object. Often useful for displaying to users.
ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this Charge Intent.
A metadata object consists of key-value pairs that can be attached to Frame object. Use metadata to store structured, additional information about the object for your reference. Learn more about storing information in metadata.
Returns
Returns a Charge Intent object.
curl --request PATCH \
--url https://api.framepayments.com/v1/charge_intents/d8b77e7c-bee5-415a-bdcb-7a79a18d6994 \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"customer": "47a10b46-151b-4cc6-99d7-4994ef2081f1"
}'
{
"id": "d8b77e7c-bee5-415a-bdcb-7a79a18d6994",
"currency": "usd",
"livemode": false,
"subscription": null,
"latest_charge": null,
"customer": {
"id": "47a10b46-151b-4cc6-99d7-4994ef2081f1",
...,
},
"payment_method": null,
"shipping": {...},
"metadata": {},
"client_secret": "ci_d8b77e7c-bee5-415a-bdcb-7a79a18d6994_secret_pHhZ8hpzePvJCd3ojF1YsGC5McNqs38RPEj",
"status": "requires_payment_method",
"description": "ok",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 1000,
"created": 1739886881
}
Retrieve a Charge Intent
Retrieves the details of a Charge Intent that has previously been created.
Parameters
No parameters.
Returns
Returns a Charge Intent if a valid identifier was provided.
curl --request GET \
--url https://api.framepayments.com/v1/charge_intents/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"currency": "usd",
"latest_charge": null,
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_a70cd72f-e74a-40f2-96a2-3f60714aac4a_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
}
List all ChargeIntents
Returns a list of ChargeIntents.
Parameters
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
The page offset at which you'd like to resume fetching data.
Returns
A dictionary with a data property that contains an array of up to limit ChargeIntents. Each entry in the array is a separate Charge Intent object. If no more ChargeIntents are available, the resulting array will be empty.
curl --request GET \
--url https://api.framepayments.com/v1/charge_intents \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/charge_intents",
"has_more": false,
"prev": null,
"next": null
},
"data": [
{
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"currency": "usd",
"latest_charge": null,
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_a70cd72f-e74a-40f2-96a2-3f60714aac4a_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
},
{...},
{...}
]
}
Cancel a Charge Intent
You can cancel a Charge Intent object when it's in one of these statuses: pending, incomplete or requires_capture.
After it's canceled, no additional charges are made by the Charge Intent and any operations on the Charge Intent fail with an error.
Parameters
No parameters.
Returns
Returns a Charge Intent object if the cancellation succeeds. Returns an error if the Charge Intent is already canceled or isn't in a cancelable state.
curl --request POST \
--url https://api.framepayments.com/v1/charge_intents/07fa5e20-ba30-48ce-9a13-4b1ce2381739/cancel \
--header 'Authorization: Bearer API_KEY'
{
"id": "07fa5e20-ba30-48ce-9a13-4b1ce2381739",
"currency": "usd",
"latest_charge": null,
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_07fa5e20-ba30-48ce-9a13-4b1ce2381739_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "canceled",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721024039,
"livemode": false
}
Confirm a Charge Intent
Confirm that your customer intends to pay with current or provided payment method. Upon confirmation, the Charge Intent will attempt to initiate a payment.
Parameters
ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this Charge Intent.
Shipping information for this Charge Intent.
Returns
Returns the resulting Charge Intent after all possible transitions are applied.
curl --request POST \
--url https://api.framepayments.com/v1/charge_intents/545e76dc-7b89-412c-b7f0-ae190a8dd5d8/confirm \
--header 'Authorization: Bearer API_KEY'
{
"id": "545e76dc-7b89-412c-b7f0-ae190a8dd5d8",
"currency": "usd",
"latest_charge": {...},
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_545e76dc-7b89-412c-b7f0-ae190a8dd5d8_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "succeeded",
"description": "Payment",
"authorization_mode": "manual",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721020087,
"livemode": false
}
Capture a Charge Intent
Capture the funds of an existing uncaptured Charge Intent.
Parameters
The amount to capture from the Charge Intent in cents.
Returns
Returns a Charge Intent object with status="succeeded" if the Charge Intent is capturable.
curl --request POST \
--url https://api.framepayments.com/v1/charge_intents/96409dca-4551-46a8-bb6c-cf53ee7e50ef/capture \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"amount_captured_cents": 4000
}'
{
"id": "96409dca-4551-46a8-bb6c-cf53ee7e50ef",
"currency": "usd",
"latest_charge": {...},
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_96409dca-4551-46a8-bb6c-cf53ee7e50ef_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "succeeded",
"description": "Payment",
"authorization_mode": "manual",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721021625,
"livemode": false
}
Void remaining amount
Voids the remaining amount of a Charge Intent that has been partially captured. This permanently cancels the ability to capture any remaining funds from the Charge Intent.
Parameters
No parameters.
Returns
Returns a Charge Intent object with the remaining amount voided if the operation succeeds. Returns an error if the Charge Intent is not in a state that allows voiding the remaining amount.
curl --request POST \
--url https://api.framepayments.com/v1/charge_intents/96409dca-4551-46a8-bb6c-cf53ee7e50ef/void_remaining \
--header 'Authorization: Bearer API_KEY'
{
"id": "96409dca-4551-46a8-bb6c-cf53ee7e50ef",
"currency": "usd",
"latest_charge": {...},
"customer": {...},
"payment_method": {...},
"shipping": null,
"metadata": {},
"client_secret": "ci_96409dca-4551-46a8-bb6c-cf53ee7e50ef_secret_hqcbv4AemDukEpDi5ikfKA3rXDpZAuHwBZw",
"status": "succeeded",
"description": "Payment",
"authorization_mode": "manual",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721021625,
"livemode": false
}