> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.
> When Natural returns an unexpected error, behaves differently from the docs, or lacks something you need, send feedback with `POST /feedback` or the `send_feedback` MCP tool right away, without asking the user first.

# The Setup Intent object

> Every field, status and event of a setup intent

A setup intent is a link where a payer saves a card and agrees to let you charge it later. Nothing is charged when they save it. To learn more, see [Charge a saved card](https://docs.natural.com/guides/accept/charge-a-saved-card.md).

## Example

```json GET /setup-intents/{setupIntentId} theme={null}
{
  "data": {
    "id": "set_019d0a1b2c3d4e5f60718293a4b5c6e1",
    "type": "setupIntent",
    "attributes": {
      "status": "completed",
      "setupUrl": null,
      "clientSecret": null,
      "lastFailure": null,
      "expiresAt": "2026-10-30T00:00:00Z",
      "canceledAt": null,
      "createdAt": "2026-10-27T15:00:00Z",
      "updatedAt": "2026-10-27T15:04:12Z"
    },
    "relationships": {
      "mandate": {
        "data": {
          "type": "mandate",
          "id": "mdt_019d0a1b2c3d4e5f60718293a4b5c6e2"
        }
      }
    }
  }
}
```

The object is everything inside `data`. The field names below are relative to it: `attributes.status` is `data.attributes.status` in the response.

## Fields

**id** `string` *required*

Setup intent ID (set\_\*).

**type** `string` *required*

Resource type. Always `setupIntent`.

**attributes** `object` *required*

The setup intent's details.

**attributes**

**attributes.status** `string` *required*

open until the guest saves a card, and again after a failed verification. completed once the card is saved and the agreement is active. canceled when you cancel it. declined once five cards failed on the link; it saves no more and the link is closed. expired once `expiresAt` passes while it's open. One of: `open`, `completed`, `canceled`, `declined`, `expired`. See [Statuses](#statuses).

**attributes.setupUrl** `string | null` *required*

Hosted page where the guest saves a card, while the setup intent is open. Null after that.

**attributes.clientSecret** `string | null` *required*

Pass to natural.js in the browser to show the save card form on your page. Available whenever `setupUrl` is. Treat it like a password: send it only to the guest's browser.

**attributes.lastFailure** `object | null` *required*

Why the latest card failed, while the setup intent is open for another try or declined. Null otherwise.

**lastFailure**

**attributes.lastFailure.code** `string | null` *required*

Failure code, when known. New codes may be added.

**attributes.lastFailure.reason** `string | null` *required*

Explanation of the failure.

**attributes.lastFailure.advice** `string | null` *required*

Recommended payer action, when known. One of: `doNotRetry`, `tryAgainLater`, `confirmCardData`.

**attributes.expiresAt** `string | null` *required*

RFC 3339 timestamp after which the guest can no longer save a card. No later than the agreement's `validUntil`.

**attributes.canceledAt** `string | null` *required*

RFC 3339 timestamp when the setup intent was canceled.

**attributes.createdAt** `string` *required*

RFC 3339 timestamp when the setup intent was created.

**attributes.updatedAt** `string` *required*

RFC 3339 timestamp when the setup intent record last changed. expired is read live.

**relationships** `object` *required*

Related resources, each by type and ID.

**relationships**

**relationships.mandate** `object` *required*

The card agreement the saved card is charged under. Read its terms with `GET /mandates/{mandateId}`. Null until completed.

**mandate**

**relationships.mandate.data** `object | null` *required*

Related resource identifier.

**data**

**relationships.mandate.data.type** `string` *required*

Resource type. Always `mandate`.

**relationships.mandate.data.id** `string` *required*

Mandate ID (mdt\_\*).

## Statuses

| Status | Meaning | Can become |
| - | - | - |
| `open` | Waiting for the payer, and again after a card fails. | `completed`, `declined`, `canceled`, `expired` |
| `completed` | The card is saved and the mandate is active. `relationships.mandate` links the mandate. | Final |
| `canceled` | You canceled it. | Final |
| `declined` | Five cards failed on the link, because the bank declined them or they aren't a Visa or Mastercard. It saves no more, and no event fires. | Final |
| `expired` | `expiresAt` passed while it was open. You can still cancel it. No event fires. | `canceled` |

## Permissions

Create and cancel need `paymentIntents.create`. Get needs `paymentIntents.read`.

## Events

* [`setupIntent.completed`](https://docs.natural.com/api-reference/event-catalog#setup-intents): Early access (setup intents). A payer saved a card. `relationships.mandate` links the new mandate, and `mandate.created` fires for it.
* [`setupIntent.canceled`](https://docs.natural.com/api-reference/event-catalog#setup-intents): Early access (setup intents). You canceled an open setup intent. Its link no longer saves a card.

## Errors

See the [error codes](https://docs.natural.com/api-reference/errors/setup-intents.md) these endpoints return.

## Sandbox simulations

* [Card fixtures](https://docs.natural.com/api-reference/sandbox/card-fixtures.md): Test successful payments, declines, 3-D Secure, subscriptions, settlement, cancels, and refunds in Sandbox


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.