Charge Intent
A ChargeIntent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one ChargeIntent for each order or customer session in your system. You can reference the ChargeIntent later to see the history of payment attempts for a particular session.
A ChargeIntent 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 ChargeIntent object
Attributes
Unique identifier for the object.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Status of this ChargeIntent, 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 ChargeIntent. 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).
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 ChargeIntent.
ID of the Customer this ChargeIntent belongs to, if one exists.
ID of the payment method used in this ChargeIntent.
Shipping information for this ChargeIntent.
City, district, suburb, town, or village.
Two-letter country code (ISO 3166-1 alpha-2).
State, county, province, or region.
ZIP or postal code.
Address line 1 (e.g., street, PO Box, or company name).
Address line 2 (e.g., apartment, suite, unit, or building).
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,
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
}
Create a ChargeIntent
Creates a ChargeIntent object.
After the ChargeIntent 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 ChargeIntent 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 ChargeIntent. 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 ChargeIntent belongs to, if one exists.
Payment methods attached to other Customers cannot be used with this ChargeIntent.
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 ChargeIntent.
Set to true to attempt to confirm this ChargeIntent immediately. This parameter defaults to false. When creating and confirming a ChargeIntent 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.
Controls when the funds will be captured from the customer's account.
Default value. Frame automatically captures funds when the customer authorizes the payment.
Place a hold on the funds when the customer authorizes the payment, but don't capture the funds until later.
If provided, this hash will be used to create a Customer. The new Customer will appear in the customer property on the ChargeIntent.
The customer's full name or business name.
The customer's email address.
If provided, this hash will be used to create a PaymentMethod. The new PaymentMethod will appear in the payment_method property on the ChargeIntent.
Indicates that you intend to make future payments with this ChargeIntent's payment method. If you provide a Customer with the ChargeIntent, you can use this parameter to attach the payment method to the Customer.
The type of the PaymentMethod. We only accept card at the moment.
The card number, as a string without any separators.
Two-digit number representing the card's expiration month.
The last two-digit number representing the card's expiration year.
The card's CVC. It is highly recommended to always include this value.
Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.
City, district, suburb, town, or village.
Two-letter country code (ISO 3166-1 alpha-2).
State, county, province, or region.
ZIP or postal code.
Address line 1 (e.g., street, PO Box, or company name).
Address line 2 (e.g., apartment, suite, unit, or building).
Returns
Returns a ChargeIntent 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
}'
{
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"currency": "usd",
"latest_charge": null,
"customer": {...},
"payment_method": {...},
"shipping": null,
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
}
Update a ChargeIntent
Updates properties on a ChargeIntent object without confirming.
Depending on which properties you update, you might need to confirm the ChargeIntent again. For example, updating the payment_method always requires you to confirm the ChargeIntent 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 ChargeIntent. 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 ChargeIntent belongs to, if one exists.
Payment methods attached to other Customers cannot be used with this ChargeIntent.
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 ChargeIntent.
Set to true to attempt to confirm this ChargeIntent immediately. This parameter defaults to false. When creating and confirming a ChargeIntent 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.
Returns
Returns a ChargeIntent object.
COMING SOON
Retrieve a ChargeIntent
Retrieves the details of a ChargeIntent that has previously been created.
Parameters
No parameters.
Returns
Returns a ChargeIntent 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,
"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 50.
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 ChargeIntent 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,
"status": "incomplete",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 2000,
"created": 1721010605,
"livemode": false
},
{...},
{...}
]
}
Cancel a ChargeIntent
You can cancel a ChargeIntent 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 ChargeIntent and any operations on the ChargeIntent fail with an error.
Parameters
No parameters.
Returns
Returns a ChargeIntent object if the cancellation succeeds. Returns an error if the ChargeIntent 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,
"status": "canceled",
"description": "Payment",
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721024039,
"livemode": false
}
Confirm a ChargeIntent
Confirm that your customer intends to pay with current or provided payment method. Upon confirmation, the ChargeIntent will attempt to initiate a payment.
Parameters
No parameters.
Returns
Returns the resulting ChargeIntent 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,
"status": "succeeded",
"description": "Payment",
"authorization_mode": "manual",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721020087,
"livemode": false
}
Capture a ChargeIntent
Capture the funds of an existing uncaptured ChargeIntent.
Parameters
The amount to capture from the ChargeIntent in cents.
Returns
Returns a ChargeIntent object with status="succeeded" if the ChargeIntent 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,
"status": "succeeded",
"description": "Payment",
"authorization_mode": "manual",
"failure_description": null,
"object": "charge_intent",
"amount": 4000,
"created": 1721021625,
"livemode": false
}