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
idstring

Unique identifier for the object.

currencystring

Three-letter ISO currency code, in lowercase. Must be a supported currency.

statusenum

Status of this ChargeIntent, one of incomplete, pending, canceled, refunded, reversed, failed, disputed, or succeeded.

descriptionnullable string

An arbitrary string attached to the object. Often useful for displaying to users.

amountpositive integer

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).

livemodeboolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

latest_chargenullable dictionary

The latest charge attempt of this ChargeIntent.

customernullable string

ID of the Customer this ChargeIntent belongs to, if one exists.

payment_methodnullable string

ID of the payment method used in this ChargeIntent.

shippingnullable dictionary

Shipping information for this ChargeIntent.

citynullable string

City, district, suburb, town, or village.

countrynullable string

Two-letter country code (ISO 3166-1 alpha-2).

statenullable string

State, county, province, or region.

postal_codenullable string

ZIP or postal code.

line_1nullable string

Address line 1 (e.g., street, PO Box, or company name).

line_2nullable string

Address line 2 (e.g., apartment, suite, unit, or building).

objectstring

String representing the object's type. Objects of the same type share the same value.

createdtimestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

updatedtimestamp

Time at which the object was last updated. Measured in seconds since the Unix epoch.

THE CHARGE INTENT OBJECT
{
  "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
amountREQUIREDpositive integer

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).

currencyREQUIREDstring

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customerstring

ID of the Customer this ChargeIntent belongs to, if one exists.

Payment methods attached to other Customers cannot be used with this ChargeIntent.

descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

payment_methodstring

ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this ChargeIntent.

confirmboolean

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.

receipt_emailstring

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.

authorization_modeenum

Controls when the funds will be captured from the customer's account.

automaticstring

Default value. Frame automatically captures funds when the customer authorizes the payment.

manualstring

Place a hold on the funds when the customer authorizes the payment, but don't capture the funds until later.

customer_datadictionary

If provided, this hash will be used to create a Customer. The new Customer will appear in the customer property on the ChargeIntent.

nameREQUIREDstring

The customer's full name or business name.

emailREQUIREDstring

The customer's email address.

payment_method_datadictionary

If provided, this hash will be used to create a PaymentMethod. The new PaymentMethod will appear in the payment_method property on the ChargeIntent.

attachboolean

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.

typeREQUIREDenum

The type of the PaymentMethod. We only accept card at the moment.

card_numberREQUIREDstring

The card number, as a string without any separators.

exp_monthREQUIREDstring

Two-digit number representing the card's expiration month.

exp_yearREQUIREDstring

The last two-digit number representing the card's expiration year.

cvcREQUIREDstring

The card's CVC. It is highly recommended to always include this value.

billingdictionary

Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

citynullable string

City, district, suburb, town, or village.

countrynullable string

Two-letter country code (ISO 3166-1 alpha-2).

statenullable string

State, county, province, or region.

postal_codenullable string

ZIP or postal code.

line_1nullable string

Address line 1 (e.g., street, PO Box, or company name).

line_2nullable string

Address line 2 (e.g., apartment, suite, unit, or building).

Returns

Returns a ChargeIntent object.

POST/v1/charge_intents
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
}'
RESPONSE
{
  "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
amountinteger

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).

currencystring

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customerstring

ID of the Customer this ChargeIntent belongs to, if one exists.

Payment methods attached to other Customers cannot be used with this ChargeIntent.

descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

payment_methodstring

ID of the payment method (a PaymentMethod, Card, or compatible Source object) to attach to this ChargeIntent.

confirmboolean

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.

receipt_emailstring

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.

GET/v1/charge_intents/:id
curl --request GET \
  --url https://api.framepayments.com/v1/charge_intents/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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
per_pageinteger

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.

pageinteger

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.

GET/v1/charge_intents
curl --request GET \
  --url https://api.framepayments.com/v1/charge_intents \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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.

POST/charge_intents/:id/cancel
curl --request POST \
  --url https://api.framepayments.com/v1/charge_intents/07fa5e20-ba30-48ce-9a13-4b1ce2381739/cancel \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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.

POST/charge_intents/:id/confirm
curl --request POST \
  --url https://api.framepayments.com/v1/charge_intents/545e76dc-7b89-412c-b7f0-ae190a8dd5d8/confirm \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "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
amount_captured_centsREQUIREDinteger

The amount to capture from the ChargeIntent in cents.

Returns

Returns a ChargeIntent object with status="succeeded" if the ChargeIntent is capturable.

POST/charge_intents/:id/capture
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
}'
RESPONSE
{
  "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
}