NAnatural
Card Sessions

Create card session

Changed on

Open a session to pay for one purchase with one card. Poll it until the user approves, then claim it once for a stand-in card and proxy login.

post/card-sessions

Request

  • Base URL
    https://api.natural.com
  • URL
    https://api.natural.com/card-sessions
  • Auth
    HTTP bearer

Headers

X-Instance-IDstring nullable

Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.

Idempotency-Keystring

Optional. Retrying with the same key and body returns the original session and approvalUrl instead of opening another one.

Request body

Response

Successful Response

sessionIdstring required
cardIdstring required
cardSource'natural_issued' | 'external' required

natural_issued: an agent card Natural issued to you. external: a card the user added on the dashboard.

status'pending_approval' | 'approved' | 'declined' | 'claimed' | 'expired' required

pending_approval: waiting for the user; keep polling. approved: claim it now. declined: the user said no. claimed: already collected. expired: open a new session.

allowedHostsstring[] required
referencestring nullable required

The reference you created the session with. Null when you didn't set one.

approvalExpiresAtstring required

A pending session must be approved before this, 24 hours after creation. After it, an unapproved session is expired.

claimExpiresAtstring required

An approved session must be claimed before this: approval plus claimWindowSeconds. Until the user approves, it's the latest that could be: approvalExpiresAt plus claimWindowSeconds. After it, an unclaimed session is expired.

claimedAtstring nullable required
credentialExpiresAtstring nullable required

When the claimed proxy login stops working.

createdAtstring required
approvalUrlstring nullable required

Cards the user added only: send the user here to approve the purchase. Returned only in this response; it can't be fetched again.

Changes

  • 9327f52d75d3Revision changes
    • info

      added the new optional request property ///

    • info

      the /// request property's min was decreased from 1.00 to 0.00

    • info

      added the required property to the response with the status

  • 4fda009457beRevision changes
    • info

      added the new optional request property //

    • info

      added the required property to the response with the status