---
title: "Claim card session"
method: POST
path: "/card-sessions/{sessionId}/claim"
tags: ["Card Sessions"]
---

# Claim card session

`POST /card-sessions/{sessionId}/claim`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/card-sessions/{sessionId}/claim`
- Auth: HTTP bearer

Claim the stand-in card and proxy login for an approved session. It succeeds once; with an Idempotency-Key, retrying with the same key returns a fresh login until expiresAt.

## Path parameters

- `sessionId` string, required: Card session ID (csn_*).

## Query parameters

- `customerPartyId` string: Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.

## Headers

- `Idempotency-Key` string
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `sessionId` string, required
  - `cardId` string, required
  - `card` object, required
    - `number` string, required: Stand-in card number. Only valid through `proxy`.
    - `cvc` string, required: Stand-in CVC. Only valid through `proxy`.
    - `expirationMonth` integer, required
    - `expirationYear` integer, required
    - `holderName` string, nullable, required: Cardholder name as printed on the card, for the merchant's checkout name field. Null for agent cards, which have none on file.
  - `billingAddress` object, nullable, required: The card's billing address on file, for filling the merchant's checkout (the ZIP drives the bank's AVS check). Null for agent cards, which store none.
    - `line1` string, nullable, required
    - `line2` string, nullable, required
    - `city` string, nullable, required
    - `state` string, nullable, required
    - `postalCode` string, nullable, required: ZIP/postal code the bank's AVS check validates at checkout.
    - `country` string, nullable, required
  - `proxy` object, required
    - `host` string, required
    - `port` integer, required
    - `protocol` 'https', required
    - `username` string, required
    - `password` string, required: Secret. Grants use of the card on allowedHosts until expiresAt. Never log it.
    - `caBundleUrl` string, required: Root CA the browser runtime must trust for the proxy.
  - `allowedHosts` string[], required
  - `expiresAt` string, required
  - `instructions` string[], required: Instructions for configuring and verifying the checkout proxy before paying.

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-13** `af91bb69dfcf`: 1 info
  - added the new optional `header` request parameter `Idempotency-Key`
- **2026-10-03** `3f14b9f458e4`: 1 info
  - added the new optional `query` request parameter `customerPartyId`
- **2026-10-01** `ec0929152b0d`: 1 info
  - added the required property `instructions` to the response with the `200` status
- **2026-09-30** `6663cdab7a7c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/card-sessions/:sessionId/claim/post.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)