---
name: natural-card-vault
description: Pay with a user's card saved in Natural's card vault. Use whenever you need to buy something, or save a card on file at a merchant, with a card the user saved on Natural (eac_*): open a card session, send the user the approval link, wait for approval, claim the stand-in card before the claim window closes, and pay through Natural's proxy.
metadata:
  author: Natural
  version: "1.0"
---

# Natural card vault

Run this for every purchase with a card the user saved on Natural. One card session covers one
purchase. Setup (API keys, inviting the user, the user saving a card) is already done: you have an
agent key and the user's `customerPartyId` (`pty_*`).

## Requests

- Base URL: `https://api.natural.com` (Sandbox: `https://api.sandbox.natural.com`).
- `Authorization: Bearer <agent key>` (`ak_ntl_…`), or the OAuth token of a Natural-approved
  partner app.
- `X-Instance-ID: <id of this agent run>` on create and claim. Use the same value for the whole
  purchase.
- Pass `customerPartyId` on every call: in `data.attributes` on create, as a query parameter on
  everything else.
- Never log or show the user the claim's `proxy.password`, `card.number` or `card.cvc`.

## The flow

### 1. Pick the card

`GET /external-cards?customerPartyId=pty_…`. Use a card with `attributes.status` `active`.
If the user has several, use the one they named, or ask them by `attributes.nickname` and
`attributes.lastFour`.

```json
{
  "data": [
    {
      "type": "externalCard",
      "id": "eac_01a0e642ed4873d685273ce0e7d1ccab",
      "attributes": {
        "brand": "visa",
        "lastFour": "4242",
        "nickname": "Visa card ending 4242",
        "status": "active",
        "billingAddress": {
          "line1": "235 2nd Street",
          "line2": null,
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  ]
}
```

### 2. Open the session

Open it only when the user is ready to approve. `POST /card-sessions` with an `Idempotency-Key`
unique to this purchase (your order or task ID), so a retry returns the same session and
`approvalUrl` instead of opening a second one.

```json
{
  "data": {
    "attributes": {
      "customerPartyId": "pty_019cd1798d637a4da75dce386343931d",
      "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab",
      "allowedHosts": ["api.stripe.com"],
      "purchase": {
        "merchantName": "Blue Bottle Coffee",
        "amount": 2450,
        "currency": "USD",
        "description": "Two bags of whole bean coffee"
      },
      "reference": "checkout_7f3a",
      "returnUrl": "sms:+15551234567"
    }
  }
}
```

| Field                   | Required | Notes                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardId`                | yes      | The `eac_*` from step 1.                                                                                                                                                                                                                                                                                               |
| `allowedHosts`          | yes      | 1–5 exact hostnames that receive the card: the payment processor's API host (`api.stripe.com`), not the store's site. No wildcards, ports or paths. For card iframes from `checkoutshopper-live.adyen.com` or `flex.cybersource.com`, list that host; for CyberSource also the merchant host serving the payment page. |
| `purchase.merchantName` | yes      | As the user will recognize it.                                                                                                                                                                                                                                                                                         |
| `purchase.amount`       | yes      | Integer minor units (cents). `0` for a card action with no purchase, such as saving the card on file; then say what you'll do in `description`.                                                                                                                                                                        |
| `purchase.currency`     | yes      | ISO 4217, such as `USD`.                                                                                                                                                                                                                                                                                               |
| `purchase.description`  | no       | One plain line the user reads before approving.                                                                                                                                                                                                                                                                        |
| `claimWindowSeconds`    | no       | Time to claim after the user approves. 600–86400, default 600 (10 minutes). Set it only to pay later than that.                                                                                                                                                                                                        |
| `ttlSeconds`            | no       | How long the claimed card works. 60–900, default 600.                                                                                                                                                                                                                                                                  |
| `reference`             | no       | Your own ID. Not unique; filter `GET /card-sessions?reference=…` by it.                                                                                                                                                                                                                                                |
| `returnUrl`             | no       | Where the user goes after answering: an `https` URL, or `sms:+15551234567`.                                                                                                                                                                                                                                            |
| `requestAgentToken`     | no       | Only for checkouts that encrypt the card in the browser. See [Checkout can't take the stand-in](#checkout-cant-take-the-stand-in).                                                                                                                                                                                     |

The user approves the amount, merchant and description, but Natural doesn't enforce them. It
does enforce `allowedHosts`. Describe the purchase truthfully.

Find the host before you open the session. Open the payment page and find the request that
carries the card when the form is submitted (often sent from a processor's card-field iframe),
and list the host it goes to. If that isn't clear, submit a fake card number that will fail and
see which host receives it.

Response `201`:

```json
{
  "sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92",
  "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab",
  "cardSource": "external",
  "status": "pending_approval",
  "allowedHosts": ["api.stripe.com"],
  "reference": "checkout_7f3a",
  "purchase": {
    "merchantName": "Blue Bottle Coffee",
    "amount": 2450,
    "currency": "USD",
    "description": "Two bags of whole bean coffee"
  },
  "approvalExpiresAt": "2026-09-30T18:00:00.000Z",
  "claimExpiresAt": "2026-09-30T18:10:00.000Z",
  "claimedAt": null,
  "credentialExpiresAt": null,
  "createdAt": "2026-09-29T18:00:00.000Z",
  "agentToken": { "requested": false, "mandateId": null },
  "note": null,
  "approvalUrl": "https://natural.com/dashboard/card-approvals/QO9J1KqnWOZT5dY6W7sT5w?returnTo=sms%3A%2B15551234567"
}
```

`approvalUrl` is returned only here. Keep it until the session ends.

### 3. Send the user the approval link

Add `signin=phone` to `approvalUrl`'s query (keep any existing parameters, such as `returnTo`), and
send it where you talk to the user. Card vault users sign up by phone; without it, a signed-out
user lands on an email sign-in they can't use.

```text
https://natural.com/dashboard/card-approvals/QO9J1KqnWOZT5dY6W7sT5w?returnTo=sms%3A%2B15551234567&signin=phone
```

Tell them what they're approving: merchant, amount, and the card. They approve with Face ID or
the card's security code, or decline.

### 4. Wait for approval

Poll `GET /card-sessions/{sessionId}?customerPartyId=pty_…` every few seconds. It returns the same
shape as step 2, without `approvalUrl`.

| `status`           | What to do                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `pending_approval` | Keep polling until `approvalExpiresAt` (24 hours after creation). Remind the user if they're slow.    |
| `approved`         | Claim now. You have until `claimExpiresAt`: approval time plus `claimWindowSeconds`.                  |
| `declined`         | Stop. Don't reopen unless the user asks.                                                              |
| `claimed`          | Already claimed. If you lost the response, see [Retry a claim](#retry-a-claim).                       |
| `expired`          | The user didn't approve in time, or you didn't claim in time. Open a new session and send a new link. |

Until approval, `claimExpiresAt` is the latest it could be (`approvalExpiresAt` +
`claimWindowSeconds`). Read it again once `status` is `approved`.

When approved, `note` may hold `{ "message": "…", "url": "…" }`: a suggestion for the user, such as
verifying their identity to skip the security code next time. Pass it on once.

### 5. Claim

Claim right before you enter the card. `POST /card-sessions/{sessionId}/claim?customerPartyId=pty_…`,
no body, with an `Idempotency-Key` (a new one, such as `claim_<sessionId>`). Without one, a lost
response can't be recovered.

Response `200`:

```json
{
  "sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92",
  "cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab",
  "card": {
    "number": "4242423289715897",
    "cvc": "128",
    "expirationMonth": 8,
    "expirationYear": 2030,
    "holderName": "Jane Appleseed"
  },
  "billingAddress": {
    "line1": "235 2nd Street",
    "line2": null,
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "proxy": {
    "host": "us-va.browser.relay.evervault.app",
    "port": 443,
    "protocol": "https",
    "username": "app_1a2b3c4d5e6f",
    "password": "eyJhbGciOiJ...",
    "caBundleUrl": "https://ca.evervault.com"
  },
  "allowedHosts": ["api.stripe.com"],
  "expiresAt": "2026-09-29T18:12:00.000Z",
  "instructions": ["…"]
}
```

`card` is a stand-in. It becomes the real card only when sent to `allowedHosts` through `proxy`
before `expiresAt`.

### 6. Pay through the proxy

Follow the claim's `instructions`. In short:

1. Configure your browser or HTTP client with `proxy` (`protocol`, `host`, `port`, `username`,
   `password`). Take them from each claim; the host can change.
2. Trust every CA at `caBundleUrl`, alongside the existing trusted roots. Keep TLS verification on.
3. Route requests to `allowedHosts`, including from checkout iframes, through the proxy. Check
   with a harmless request to an allowed host first.
4. Open or reload the payment page after configuring the proxy, then enter `card`, `holderName`
   and `billingAddress` (the ZIP drives the bank's address check).
5. If the request carrying the card goes to a host missing from `allowedHosts`, don't enter the
   card. Open a new session with that host added and a new `Idempotency-Key` (reusing the
   purchase's key returns `idempotencyKeyReused`), send the user its `approvalUrl`, and
   continue with that session.
6. On a `502` from the proxy, read the JSON body's error code and hint, do what it says, and
   retry. If the proxy fails, never send the card request directly: check routing, certificate
   trust and `expiresAt`, and confirm the last attempt didn't go through before retrying.

## Errors

Errors look like `{ "errors": [{ "code": "…", "status": "409", "detail": "…", "meta": { "supportId": "…" } }] }`.
Act on `code`.

| Code                                              | Status | Do this                                                                                                     |
| ------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `cardSession.pendingApproval`                     | 409    | Claimed too early. Keep polling.                                                                            |
| `cardSession.declined`                            | 409    | The user said no. Stop.                                                                                     |
| `cardSession.expired`                             | 409    | Open a new session and send the new link.                                                                   |
| `cardSessionApproval.lapsed`                      | 409    | The approval can't be used anymore. Open a new session.                                                     |
| `cardSession.alreadyClaimed`                      | 409    | Claimed before, with no key, a different key, or after `expiresAt`. Open a new session.                     |
| `card.notActive`                                  | 409    | The card or your access to it is gone. Ask the user to check their card on Natural.                         |
| `card.notFound`                                   | 404    | Wrong `cardId` or `customerPartyId`. List cards again.                                                      |
| `cardSession.notFound`                            | 404    | Wrong `sessionId` or `customerPartyId`.                                                                     |
| `card.useNotPermitted`                            | 403    | Your agent lacks `saved_cards.use` for this user. Tell the user; don't retry.                               |
| `cardSession.purchaseRequired`                    | 400    | Add `purchase`.                                                                                             |
| `invalidValue`                                    | 400    | Fix the field named in `source.pointer`.                                                                    |
| `idempotencyKeyReused`                            | 409    | Same key, different body. Use a new key only for a different purchase or a session with new `allowedHosts`. |
| `idempotencyRequestInProgress`                    | 409    | Retry the same request with the same key.                                                                   |
| `rateLimited`                                     | 429    | Wait the `Retry-After` seconds, then retry.                                                                 |
| `cardSession.providerUnavailable`                 | 503    | Retry the claim with the same `Idempotency-Key` after a short wait.                                         |
| `cardSession.unavailable`                         | 503    | This card can't be used for sessions yet. Tell the user to try another card.                                |
| `serverError`, `badGateway`, `serviceUnavailable` | 5xx    | Retry with the same `Idempotency-Key`.                                                                      |

## Retries and expirations

- **Lost the create response:** retry with the same `Idempotency-Key` and body. You get the same
  session and `approvalUrl`.
- **Retry a claim:** before the first claim's `expiresAt`, retry with the same `Idempotency-Key`.
  You get a new stand-in card and proxy login; use the latest. They still end at the first
  `expiresAt`.
- **Claimed card expired mid-checkout:** it can't be renewed. Open a new session and ask the user
  to approve again.
- **Missed `claimExpiresAt`:** the session is `expired`. Open a new one. Next time, claim as soon as
  you're ready to pay, or set `claimWindowSeconds` when you need to pay later.
- **Find an earlier session:** `GET /card-sessions?customerPartyId=pty_…&reference=…&status=…`
  lists your sessions newest first: `{ "data": [<session>], "meta": { "pagination": { "hasMore": false, "nextCursor": null } } }`.

## Checkout can't take the stand-in

The proxy swaps the card only when the stand-in number is in the checkout's HTTP request. Adyen,
CyberSource Flex Microform and Southwest card fields work. If a checkout encrypts the card in the
browser some other way, open the session with `"requestAgentToken": true` (USD, $0.01 to
$999,999.99). It has no effect for a user who signed up by phone: tell them this checkout isn't
supported with this card. Otherwise, once `approved`, read `agentToken.mandateId`:

- `amd_*`: create an agentic purchase with it (`POST /agentic-payments/purchases`) and claim that
  purchase's credential.
- `null` (common): claim this session and try the proxy. If the checkout still can't take it, tell
  the user this checkout isn't supported with this card.
