API Reference

Payment Intents

A Payment Intent object represents your intention to collect payment from a customer, tracking the lifecycle of the payment process from creation to completion. It is a central object in the PaymentKit API for processing charges.
Retrieve a Payment Intent#Fetches the details of a specific Payment Intent by its unique ID. This includes related objects like the customer, payment method, and invoice.
Parameters
Name
Type
Description
id
string
The unique identifier of the Payment Intent.
Returns
Returns a TPaymentIntentExpanded object which includes the full Payment Intent details along with the following expanded objects:
paymentCurrency: The PaymentCurrency object used for this payment.
paymentMethod: The PaymentMethod object used for this payment.
customer: The Customer object associated with this payment.
checkoutSession: The CheckoutSession object if the payment was initiated via a checkout session.
invoice: The Invoice object associated with this payment.
subscription: The Subscription object if this payment is for a subscription.
Example
import payment from '@blocklet/payment-js';

async function getPaymentIntent(paymentIntentId) {
  try {
    const intent = await payment.paymentIntents.retrieve(paymentIntentId);
    console.log('Retrieved Payment Intent:', intent);
  } catch (error) {
    console.error('Error retrieving Payment Intent:', error.message);
  }
}

// Replace with a valid Payment Intent ID
getPaymentIntent('pi_xxxxxxxxxxxxxx');Example Response
{
  "id": "pi_xxxxxxxxxxxxxx",
  "object": "payment_intent",
  "amount": "1000",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "status": "succeeded",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:05.000Z",
  "paymentCurrency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  },
  "customer": {
    "id": "cus_xxxxxxxxxxxxxx",
    "did": "did:abt:z123..."
  }
}Update a Payment Intent#Updates the specified Payment Intent by setting key-value pairs on the metadata field. Note that other attributes cannot be updated.
Parameters
Name
Type
Description
id
string
The ID of the Payment Intent to update.
metadata
object
A set of key-value data to store with the object.
Returns
Returns the updated TPaymentIntent object.
Example
import payment from '@blocklet/payment-js';

async function updateIntentMetadata(paymentIntentId) {
  try {
    const intent = await payment.paymentIntents.update(paymentIntentId, {
      metadata: {
        order_id: '6735'
      }
    });
    console.log('Updated Payment Intent:', intent);
  } catch (error) {
    console.error('Error updating Payment Intent:', error.message);
  }
}

// Replace with a valid Payment Intent ID
updateIntentMetadata('pi_xxxxxxxxxxxxxx');Example Response
{
  "id": "pi_xxxxxxxxxxxxxx",
  "object": "payment_intent",
  "status": "succeeded",
  "metadata": {
    "order_id": "6735"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:15.000Z"
}List Payment Intents#Returns a paginated list of Payment Intents. You can filter the list based on various criteria.
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.
customer_did
string
Optional. Only return Payment Intents for the customer with the given DID.
metadata.{key}
string
Optional. Filter by a specific key-value pair in the metadata.
page
number
Optional. The page number for pagination, starting at 1. Default is 1.
pageSize
number
Optional. The number of objects to return per page. Default is 20.
Returns
Returns a paginated object containing a list of TPaymentIntentExpanded objects, the total count, and paging information.
Example
import payment from '@blocklet/payment-js';

async function listSucceededIntents() {
  try {
    const intents = await payment.paymentIntents.list({
      status: 'succeeded',
      pageSize: 10
    });
    console.log(`Found ${intents.count} succeeded intents.`);
    intents.list.forEach(intent => {
      console.log(`- ${intent.id}`);
    });
  } catch (error) {
    console.error('Error listing Payment Intents:', error.message);
  }
}

listSucceededIntents();Example Response
{
  "count": 15,
  "list": [
    {
      "id": "pi_xxxxxxxxxxxxxx",
      "object": "payment_intent",
      "status": "succeeded",
      "amount": "1000"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}Search Payment Intents#Performs a search for Payment Intents matching a query string.
Parameters
Name
Type
Description
query
string
The search query string.
page
number
Optional. The page number for pagination, starting at 1. Default is 1.
pageSize
number
Optional. The number of objects to return per page. Default is 20.
Returns
Returns a paginated object containing a list of matching TPaymentIntentExpanded objects, the total count, and paging information.
Example
import payment from '@blocklet/payment-js';

async function searchIntents(searchQuery) {
  try {
    const results = await payment.paymentIntents.search({ query: searchQuery });
    console.log(`Found ${results.count} results for '${searchQuery}'.`);
  } catch (error) {
    console.error('Error searching Payment Intents:', error.message);
  }
}

searchIntents('cus_xxxxxxxxxxxxxx');Example Response
{
  "count": 1,
  "list": [
    {
      "id": "pi_xxxxxxxxxxxxxx",
      "object": "payment_intent",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "status": "succeeded"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}Refund a Payment Intent#Creates a Refund object for a given Payment Intent. This initiates the process of returning funds to the customer.
Parameters
Name
Type
Description
id
string
The ID of the Payment Intent to refund.
amount
string
The amount to refund, as a string representation of a number. Cannot be greater than the remaining refundable amount.
reason
string
The reason for the refund. Must be one of duplicate, requested_by_customer, requested_by_admin, fraudulent, or expired_uncaptured_charge.
description
string
An explanation of the refund, which will be visible to you.
Returns
Returns a TRefundExpanded object representing the created refund.
Example
import payment from '@blocklet/payment-js';

async function issueRefund(paymentIntentId) {
  try {
    const refund = await payment.paymentIntents.refund(paymentIntentId, {
      amount: '500', // Refund 5.00 if currency decimal is 2
      reason: 'requested_by_customer',
      description: 'Customer requested a partial refund for item not received.'
    });
    console.log('Refund created:', refund);
  } catch (error) {
    console.error('Error issuing refund:', error.message);
  }
}

// Replace with a valid Payment Intent ID
issueRefund('pi_xxxxxxxxxxxxxx');Example Response
{
  "id": "re_xxxxxxxxxxxxxx",
  "object": "refund",
  "amount": "500",
  "status": "pending",
  "reason": "requested_by_customer",
  "payment_intent_id": "pi_xxxxxxxxxxxxxx",
  "created_at": "2023-10-27T11:00:00.000Z"
}Get Refundable Amount#Retrieves the amount that is currently available to be refunded on a specific Payment Intent. The calculation considers the original charge amount, any previous refunds, and any payouts made against the intent.
While this functionality is not exposed as a direct SDK method, you can make a GET request to the API endpoint to determine the refundable amount before initiating a refund.
Endpoint
GET /api/payment-intents/{id}/refundable-amount
Parameters
Name
Type
Description
id
string
The unique identifier of the Payment Intent.
Returns
Returns an object detailing the refundable amounts associated with the Payment Intent.
Name
Type
Description
amount
string
The net amount that can still be refunded.
totalAmount
string
The original amount of the Payment Intent.
refundedAmount
string
The total amount that has already been refunded.
Example Response
{
  "amount": "500",
  "totalAmount": "1000",
  "refundedAmount": "500"
}This concludes the guide for managing Payment Intents. To learn about the different ways customers can provide payment information, see the Payment Methods documentation.

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.
`customer_did`	`string`	Optional. Only return Payment Intents for the customer with the given DID.
`metadata.{key}`	`string`	Optional. Filter by a specific key-value pair in the metadata.
`page`	`number`	Optional. The page number for pagination, starting at 1. Default is `1`.
`pageSize`	`number`	Optional. The number of objects to return per page. Default is `20`.

Name	Type	Description
`query`	`string`	The search query string.
`page`	`number`	Optional. The page number for pagination, starting at 1. Default is `1`.
`pageSize`	`number`	Optional. The number of objects to return per page. Default is `20`.

Name	Type	Description
`id`	`string`	The ID of the Payment Intent to refund.
`amount`	`string`	The amount to refund, as a string representation of a number. Cannot be greater than the remaining refundable amount.
`reason`	`string`	The reason for the refund. Must be one of `duplicate`, `requested_by_customer`, `requested_by_admin`, `fraudulent`, or `expired_uncaptured_charge`.
`description`	`string`	An explanation of the refund, which will be visible to you.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Payment Intents

Retrieve a Payment Intent#

Update a Payment Intent#

List Payment Intents#

Search Payment Intents#

Refund a Payment Intent#

Get Refundable Amount#

Prices

Payment Methods

Name	Type	Description
`id`	`string`	The ID of the Payment Intent to update.
`metadata`	`object`	A set of key-value data to store with the object.

Name	Type	Description
`amount`	`string`	The net amount that can still be refunded.
`totalAmount`	`string`	The original amount of the Payment Intent.
`refundedAmount`	`string`	The total amount that has already been refunded.