Skip to main content

Setup Intents

Learn more about the Setup Intent resource

A Setup Intent resource tracks the lifecycle of your customer's attempt to save a payment method.

Use setup intent whenever you want your customer to save a payment method for future payments.

A Setup Intent transitions through multiple statuses throughout its lifetime via Payrex.JS until it creates, at most, one successful saved payment method.

Endpoints​

EndpointName
POST /setup_intentsCreate setup intent endpoint
GET /setup_intents/:idRetrieve setup intent endpoint
POST /setup_intents/:id/cancelCancel setup intent endpoint

The Setup Intent Resource​

{
  "id": "si_bsZLcJKxL2nYFkD5RT1VAbbjE3enpzEs",
  "resource": "setup_intent",
  "livemode": true,
  "client_secret": "si_bsZLcJKxL2nYFkD5RT1VAbbjE3enpzEs_secret_d9GgLMae3tgk2TS1VH4yjLddycRmvVnJ",
  "next_action": null,
  "payment_methods": [
      "card",
      "gcash",
      "maya"
  ],
  "return_url": null,
  "status": "awaiting_payment_method",
  "usage": "off_session",
  "customer": {
    "id": "cus_79nDFxt4a5m3PnasTpmpjhoL9uzYx59Jc",
    "resource": "customer",
    "billing": null,
    "billing_statement_prefix": "NRASWZJD",
    "currency": "PHP",
    "email": "juandelacruz@gmail.com",
    "livemode": true,
    "name": "Juan Dela Cruz",
    "next_billing_statement_sequence_number": "1",
    "metadata": null,
    "created_at": 1779947956,
    "updated_at": 1779947956
  },
  "description": null,
  "metadata": null,
  "payment_method_id": null,
  "created_at": 1780466607,
  "updated_at": 1780466607
}

Attributes​

id string

Unique identifier for the resource. The prefix is si_.

resource string

Represents the resource's type. The value is setup_intent.

payment_methods array of strings

The list of payment methods allowed to be processed by the Setup Intent.

status string

The latest status of the Setup Intent. Possible values are awaiting_payment_method, awaiting_next_action, processing, or succeeded.

You can check this guide to see how a Setup Intent transition from one status to another.

usage string

Indicates how the payment method is intended to be used for future purchases.

Use on_session if you intend only to reuse the payment method when the customer is in your payment form. Use off_session if your customer may or may not be present in your payment form. If not provided, this value defaults to on_session.

client_secret string

The client secret of this Setup Intent used for client-side retrieval using a public API key. The client secret can be used to complete saving a payment method from your client application.

description string

An arbitrary string attached to the Setup Intent.

livemode boolean

The value is true if the resource's mode is live or the value is false if the resource mode is test.

See the mode guide for more details.

metadata hash

A set of key-value pairs attached to the Setup Intent and the resources created by the Setup Intent.

The value is null if there are no metadata for the Setup Intent.

return_url string

The URL where your customer will be redirected after completing the authentication if they didn't exit or close their browser while authenticating.

next_action hash

If the next_action attribute is present, it tells you what actions you need to take so that your customer can make a payment using the selected method.

Show child attributes

next_action.type string

The type of the next action to perform, The possible value is redirect.

next_action.redirect_url string

The URL for authenticating a payment by redirecting your customer.


payment_method_id string

The latest Payment Method ID of attached to the Setup Intent.

customer hash

The Customer resource related to the Setup Intent resource.

created_at timestamp

The time the resource was created and measured in seconds since the Unix epoch.

updated_at timestamp

The time the resource was updated and measured in seconds since the Unix epoch.