API Reference

Payment Intents

A Payment Intent is an object that represents your intention to collect payment from a customer, tracking the lifecycle of the payment process from creation to completion. It is a central part of the PaymentKit API, guiding you through the necessary steps to confirm and capture a payment.
Most integrations will use a Checkout Session to create and handle Payment Intents automatically. However, you can use this API for more direct control over the payment lifecycle.
The Payment Intent Lifecycle#A Payment Intent progresses through various statuses as it moves from creation to completion. Understanding this flow is key to managing payments effectively.

The Payment Intent Object#The PaymentIntent object contains detailed information about a transaction. Here are some of its key attributes:
Attribute
Type
Description
id
string
Unique identifier for the Payment Intent, prefixed with pi_.
amount
string
The amount intended to be collected.
currency_id
string
The three-letter ISO currency code (or custom currency ID).
customer_id
string
ID of the Customer this Payment Intent belongs to, if one exists.
status
string
The current status of the Payment Intent. Can be requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded.
capture_method
string
Defines how the payment is captured. Can be automatic (captured immediately after confirmation) or manual (requires a separate capture call).
confirmation_method
string
Defines how the payment is confirmed. Can be automatic (confirmed immediately when a payment method is attached) or manual (requires a separate confirmation call).
last_payment_error
object
The last payment error encountered, if any. Contains details about the failure.
metadata
object
A set of key-value pairs that you can attach to an object.
created_at
Date
The timestamp when the Payment Intent was created.
Create a Payment Intent#Creates a new Payment Intent.
Parameters
Name
Type
Description
amount
string
Required. The transaction amount as a string.
currency_id
string
Required. The currency of the payment.
customer_id
string
Optional. The ID of the customer associated with this payment.
description
string
Optional. An arbitrary string attached to the object.
payment_method_id
string
Optional. The ID of the PaymentMethod to attach to this PaymentIntent.
payment_method_types
string[]
Optional. The list of payment method types (e.g., 'stripe', 'arcblock') that this PaymentIntent is allowed to use. Defaults to your account's default payment methods.
capture_method
string
Optional. Controls when the funds will be captured. Can be automatic (default) or manual.
metadata
Record<string, any>
Optional. A set of key-value pairs to store additional information.
Returns
Returns the created PaymentIntent object.
Example
async function createPaymentIntent() {
  try {
    const paymentIntent = await payment.paymentIntents.create({
      amount: '2000',
      currency_id: 'usd',
      payment_method_types: ['stripe'],
      description: 'Charge for services rendered',
    });
    console.log('Payment Intent created:', paymentIntent);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

createPaymentIntent();Example Response
{
  "id": "pi_1J2a3b4c5d6e7f8g",
  "livemode": false,
  "description": "Charge for services rendered",
  "amount": "2000",
  "amount_received": "0",
  "amount_capturable": "0",
  "currency_id": "usd",
  "customer_id": null,
  "payment_method_id": null,
  "status": "requires_payment_method",
  "capture_method": "automatic",
  "confirmation_method": "automatic",
  "payment_method_types": [
    "stripe"
  ],
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Payment Intent#Retrieves the details of an existing Payment Intent.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the Payment Intent to retrieve.
Returns
Returns the PaymentIntent object, with some fields expanded into full objects.
Example
async function retrievePaymentIntent(id) {
  try {
    const paymentIntent = await payment.paymentIntents.retrieve(id);
    console.log('Retrieved Payment Intent:', paymentIntent.status);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

retrievePaymentIntent('pi_1J2a3b4c5d6e7f8g');Example Response
{
  "id": "pi_1J2a3b4c5d6e7f8g",
  "livemode": false,
  "description": "Charge for services rendered",
  "amount": "2000",
  "status": "succeeded",
  "currency_id": "usd",
  "customer_id": "cus_a1b2c3d4e5f6",
  // ... other fields
}Update a Payment Intent#Updates properties on a Payment Intent object. You can update details like metadata or description.
Parameters
Name
Type
Description
id
string
Required. The ID of the Payment Intent to update.
data
object
Required. An object containing the fields to update.
Updatable Fields in data
Name
Type
Description
description
string
An arbitrary string attached to the object.
metadata
Record<string, any>
A set of key-value pairs to store additional information.
receipt_email
string
The email address that the receipt for a successful payment will be sent to.
Returns
Returns the updated PaymentIntent object.
Example
async function updatePaymentIntent(id) {
  try {
    const paymentIntent = await payment.paymentIntents.update(id, {
      metadata: { order_id: '6735' }
    });
    console.log('Payment Intent updated:', paymentIntent.metadata);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

updatePaymentIntent('pi_1J2a3b4c5d6e7f8g');Example Response
{
  "id": "pi_1J2a3b4c5d6e7f8g",
  "metadata": {
    "order_id": "6735"
  },
  // ... other fields
}List all Payment Intents#Returns a paginated list of your Payment Intents. The list can be filtered by various parameters.
Parameters
Name
Type
Description
status
string
Optional. Only return Payment Intents with the given status.
invoice_id
string
Optional. Only return Payment Intents for the given invoice.
customer_id
string
Optional. Only return Payment Intents for the given customer.
metadata.{key}
string
Optional. Filter by custom metadata fields.
page
number
Optional. The page number for pagination.
pageSize
number
Optional. The number of items per page (default: 20).
order
string
Optional. Sort order (e.g., 'created_at:DESC').
Returns
A paginated object containing a list of PaymentIntent objects and the total count.
Example
async function listSuccessfulPayments() {
  try {
    const paymentIntents = await payment.paymentIntents.list({
      status: 'succeeded',
      pageSize: 10
    });
    console.log(`Found ${paymentIntents.count} successful payments.`);
    paymentIntents.list.forEach(pi => console.log(pi.id));
  } catch (error) {
    console.error('Error:', error.message);
  }
}

listSuccessfulPayments();Example Response
{
  "count": 42,
  "list": [
    {
      "id": "pi_1J2a3b4c5d6e7f8g",
      "status": "succeeded",
      "amount": "2000",
      // ... other fields
    },
    {
      "id": "pi_zY9x8w7v6u5t4s3r",
      "status": "succeeded",
      "amount": "5000",
      // ... other fields
    }
  ]
}Search Payment Intents#Performs a free-text search for Payment Intents based on a query string.
Parameters
Name
Type
Description
query
string
Required. The search query.
page
number
Optional. The page number for pagination.
pageSize
number
Optional. The number of items per page (default: 20).
Returns
A paginated object containing a list of matching PaymentIntent objects and the total count.
Example
async function searchPayments(query) {
  try {
    const results = await payment.paymentIntents.search({ query: query });
    console.log(`Found ${results.count} results for '${query}'.`);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

searchPayments('order_id:6735');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "pi_1J2a3b4c5d6e7f8g",
      "status": "succeeded",
      "metadata": {
        "order_id": "6735"
      },
      // ... other fields
    }
  ]
}Refund a Payment Intent#Creates a Refund object for a charged Payment Intent. This can be a full or partial refund.
Parameters
Name
Type
Description
id
string
Required. The ID of the Payment Intent to refund.
data
object
Required. An object containing refund details.
Fields in data
Name
Type
Description
amount
string
Optional. The amount to refund. If not provided, a full refund is issued.
reason
string
Optional. The reason for the refund. Can be duplicate, fraudulent, or requested_by_customer.
description
string
Optional. An internal note about the refund.
Returns
Returns an expanded Refund object.
Example
async function refundPayment(id) {
  try {
    const refund = await payment.paymentIntents.refund(id, {
      amount: '500',
      reason: 'requested_by_customer',
      description: 'Customer requested partial refund.'
    });
    console.log('Refund processed:', refund.id);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

refundPayment('pi_1J2a3b4c5d6e7f8g');Example Response
{
  "id": "re_a1b2c3d4e5f6g7h8",
  "amount": "500",
  "currency_id": "usd",
  "payment_intent_id": "pi_1J2a3b4c5d6e7f8g",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "created_at": "2023-10-27T12:00:00.000Z",
  // ... other fields
}
Now that you understand how to manage the payment lifecycle with Payment Intents, you may want to explore the Refunds API in more detail or learn about creating reusable Payment Links.

Attribute	Type	Description
`id`	`string`	Unique identifier for the Payment Intent, prefixed with `pi_`.
`amount`	`string`	The amount intended to be collected.
`currency_id`	`string`	The three-letter ISO currency code (or custom currency ID).
`customer_id`	`string`	ID of the Customer this Payment Intent belongs to, if one exists.
`status`	`string`	The current status of the Payment Intent. Can be `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `requires_capture`, `canceled`, or `succeeded`.
`capture_method`	`string`	Defines how the payment is captured. Can be `automatic` (captured immediately after confirmation) or `manual` (requires a separate capture call).
`confirmation_method`	`string`	Defines how the payment is confirmed. Can be `automatic` (confirmed immediately when a payment method is attached) or `manual` (requires a separate confirmation call).
`last_payment_error`	`object`	The last payment error encountered, if any. Contains details about the failure.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`created_at`	`Date`	The timestamp when the Payment Intent was created.

Name	Type	Description
`amount`	`string`	Required. The transaction amount as a string.
`currency_id`	`string`	Required. The currency of the payment.
`customer_id`	`string`	Optional. The ID of the customer associated with this payment.
`description`	`string`	Optional. An arbitrary string attached to the object.
`payment_method_id`	`string`	Optional. The ID of the PaymentMethod to attach to this PaymentIntent.
`payment_method_types`	`string[]`	Optional. The list of payment method types (e.g., `'stripe'`, `'arcblock'`) that this PaymentIntent is allowed to use. Defaults to your account's default payment methods.
`capture_method`	`string`	Optional. Controls when the funds will be captured. Can be `automatic` (default) or `manual`.
`metadata`	`Record<string, any>`	Optional. A set of key-value pairs to store additional information.

Name	Type	Description
`id`	`string`	Required. The ID of the Payment Intent to update.
`data`	`object`	Required. An object containing the fields to update.

Name	Type	Description
`status`	`string`	Optional. Only return Payment Intents with the given status.
`invoice_id`	`string`	Optional. Only return Payment Intents for the given invoice.
`customer_id`	`string`	Optional. Only return Payment Intents for the given customer.
`metadata.{key}`	`string`	Optional. Filter by custom metadata fields.
`page`	`number`	Optional. The page number for pagination.
`pageSize`	`number`	Optional. The number of items per page (default: 20).
`order`	`string`	Optional. Sort order (e.g., `'created_at:DESC'`).

Name	Type	Description
`query`	`string`	Required. The search query.
`page`	`number`	Optional. The page number for pagination.
`pageSize`	`number`	Optional. The number of items per page (default: 20).

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Payment Intents

The Payment Intent Lifecycle#

The Payment Intent Object#

Create a Payment Intent#

Retrieve a Payment Intent#

Update a Payment Intent#

List all Payment Intents#

Search Payment Intents#

Refund a Payment Intent#

Prices

Payment Currencies

Name	Type	Description
`description`	`string`	An arbitrary string attached to the object.
`metadata`	`Record<string, any>`	A set of key-value pairs to store additional information.
`receipt_email`	`string`	The email address that the receipt for a successful payment will be sent to.

Name	Type	Description
`amount`	`string`	Optional. The amount to refund. If not provided, a full refund is issued.
`reason`	`string`	Optional. The reason for the refund. Can be `duplicate`, `fraudulent`, or `requested_by_customer`.
`description`	`string`	Optional. An internal note about the refund.