Payment Intents

A Payment Intent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process. It is a central object in the PaymentKit API, controlling the flow of funds from the customer to you. A Payment Intent can be associated with a Checkout Session for a user-facing payment flow or used directly for server-side operations.

This document details how to manage Payment Intent objects using the SDK.

The Payment Intent Object#

A Payment Intent object contains detailed information about a transaction. When expanded, it can also include related objects.

Object Properties

Property	Type	Description
id	string	Unique identifier for the object.
status	string	The status of the payment intent. Possible values are requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded.
amount	string	The amount intended to be collected.
amount_received	string	The amount received so far.
currency_id	string	The ID of the currency for this payment.
customer_id	string	The ID of the Customer this Payment Intent is for, if one exists.
invoice_id	string	The ID of the Invoice this Payment Intent is for, if one exists.
payment_method_id	string	The ID of the PaymentMethod used for this Payment Intent.
metadata	object	A set of key-value pairs that you can attach to an object.
created_at	string	Timestamp of when the object was created.

Expanded Objects

When retrieved, the Payment Intent object can include the following expanded objects:

• customer: The full Customer object.
• paymentCurrency: The full PaymentCurrency object.
• paymentMethod: The full PaymentMethod object.
• invoice: The full Invoice object (when applicable).
• subscription: The full Subscription object (when applicable).
• checkoutSession: The CheckoutSession that created this payment intent.

Retrieve a Payment Intent#

Retrieves the details of a Payment Intent that has previously been created. Client-side retrieval using a publishable key is allowed when the client_secret is provided.

const paymentIntent = await payment.paymentIntents.retrieve(
  'pi_123456789'
);

console.log(paymentIntent);

Parameters

Name	Type	Description
id	string	Required. The ID of the Payment Intent to retrieve.

Returns

Returns a PaymentIntent object if a valid ID was provided. Throws an error otherwise.

{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "amount_received": "1000",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "invoice_id": "in_xxxxxxxx",
  "payment_method_id": "pm_xxxxxxxx",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    /* ... payment currency details ... */
  },
  "paymentMethod": {
    /* ... payment method details ... */
  },
  "customer": {
    /* ... customer details ... */
  },
  "invoice": {
    /* ... invoice details ... */
  },
  "subscription": null,
  "checkoutSession": {

Update a Payment Intent#

Updates a Payment Intent object by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that only the metadata can be updated via this method.

const paymentIntent = await payment.paymentIntents.update(
  'pi_123456789',
  {
    metadata: { order_id: '6735' }
  }
);

console.log(paymentIntent);

Parameters

Name	Type	Description
id	string	Required. The ID of the Payment Intent to update.
metadata	object	A set of key-value pairs to store on the object.

Returns

Returns the updated PaymentIntent object.

{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "metadata": {
    "order_id": "6735"
  },
  // ... other properties
}

List all Payment Intents#

Returns a list of your Payment Intents. The intents are returned sorted by creation date, with the most recent intents appearing first.

const paymentIntents = await payment.paymentIntents.list({
  limit: 5,
  status: 'succeeded'
});

console.log(paymentIntents);

Parameters

Name	Type	Description
status	string	Optional. A comma-separated string of statuses to filter by (e.g., 'succeeded,processing').
invoice_id	string	Optional. Only return Payment Intents for the given invoice.
customer_id	string	Optional. Only return Payment Intents for the given customer ID.
customer_did	string	Optional. Only return Payment Intents for the given customer DID.
metadata.{key}	string	Optional. Filter by a specific metadata key-value pair.
page	number	Optional. The page number for pagination, starting from 1. Default is 1.
pageSize	number	Optional. A limit on the number of objects to be returned, between 1 and 100. Default is 20.

Returns

A paginated object containing a list of PaymentIntent objects and pagination details.

{
  "count": 15,
  "list": [
    {
      "id": "pi_123456789",
      "status": "succeeded",
      // ... other properties
    },
    {
      "id": "pi_987654321",
      "status": "succeeded",
      // ... other properties
    }
    // ... more payment intents
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Search Payment Intents#

Searches for Payment Intents matching a specific query.

const results = await payment.paymentIntents.search({
  query: 'cus_xxxxxxxx'
});

console.log(results);

Parameters

Name	Type	Description
query	string	Required. The search query string.
page	number	Optional. The page number for pagination, starting from 1. Default is 1.
pageSize	number	Optional. The number of items per page. Default is 20.

Returns

A paginated object containing a list of PaymentIntent objects that match the search query.

{
  "count": 1,
  "list": [
    {
      "id": "pi_123456789",
      "customer_id": "cus_xxxxxxxx",
      // ... other properties
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

Refund a Charge#

When a Payment Intent is successful, you can create a refund for the charge. This will create a Refund object and attempt to reverse the charge.

const refund = await payment.paymentIntents.refund(
  'pi_123456789',
  {
    amount: '500',
    reason: 'requested_by_customer',
    description: 'Refund for item not received.'
  }
);

console.log(refund);

Parameters

Name	Type	Description
id	string	Required. The ID of the Payment Intent to refund.
amount	string	Required. A positive string representing how much of this charge to refund. Can refund up to the total amount of the original charge.
reason	string	Required. String indicating the reason for the refund. Valid values are: duplicate, requested_by_customer, requested_by_admin, fraudulent, expired_uncaptured_charge.
description	string	Required. An explanation of the refund.

Returns

Returns a new Refund object.

{
  "id": "re_abcdef123",
  "type": "refund",
  "livemode": false,
  "amount": "500",
  "description": "Refund for item not received.",
  "status": "pending",
  "reason": "requested_by_customer",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_123456789",
  // ... other refund properties
}