Payment Intents | ArcBlock

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.

Retrieve a Payment Intent

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.

Response Example

{
  "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": {
    /* ... checkout session details ... */
  }
}

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.

Update a Payment Intent

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.

Response Example

{
  "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.

List Payment Intents

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.

Response Example

{
  "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.

Search Payment Intents

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.

Response Example

{
  "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.

Refund a 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.

Response Example

{
  "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
}