Payment Sessions

A Payment Session represents a customer’s payment intent. Create a session server-side, then use the client_secret to mount the payment form on your frontend.

Payment Flow

1. Create Session (Server) → 2. Mount Form (Client SDK) → 3. Confirm (Automatic) → 4. Capture (Optional)

Card data is collected securely via the SDK and never touches your servers.

Create a Session

curl -X POST https://api.atlas.co/functions/v1/create-session \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "currency": "USD",
    "merchant_reference": "order_12345",
    "payment_method_types": ["card", "apple_pay"],
    "capture_method": "automatic",
    "customer": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "callback_urls": {
      "approved": "https://yoursite.com/success",
      "declined": "https://yoursite.com/declined",
      "cancelled": "https://yoursite.com/cancel"
    }
  }'

Request Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in smallest currency unit (cents for USD)
`currency`	string	Yes	Three-letter ISO 4217 currency code (USD, EUR, GBP)
`external_id`	string	No	Your order or cart reference (idempotent if reused)
`capture_method`	string	No	”automatic” (default) or “manual” for auth-only
`customer.email`	string	No	Customer email address
`customer.name`	string	No	Customer full name
`success_url`	string	No	Redirect after successful payment
`cancel_url`	string	No	Redirect after cancellation
`payment_method_types`	array	No	Allowed methods: card, apple_pay, google_pay, bank_account
`metadata`	object	No	Custom key-value pairs

Response

{
  "id": "sess_2xK9mN7vQ3pL8wYz",
  "object": "payment_session",
  "status": "requires_payment_method",
  "amount": 4990,
  "currency": "USD",
  "client_secret": "cs_abc123xyz789...",
  "payment_method_types": ["card", "apple_pay"],
  "capture_method": "automatic",
  "created_at": "2024-01-15T10:30:00Z",
  "livemode": false
}

Session Lifecycle States

Sessions progress through a state machine from creation to completion:

State	Description
`requires_payment_method`	Session created, waiting for customer to enter payment details
`requires_action`	Additional action needed (3DS authentication, redirect)
`processing`	Payment is being processed
`succeeded`	Payment completed successfully
`failed`	Payment failed
`canceled`	Customer abandoned checkout or session expired

Session Expiration

Sessions expire automatically to prevent stale payment intents. Expired sessions cannot be completed.

Setting	Description
Default	Sessions expire 24 hours after creation
Custom	Set `expires` as seconds from now (e.g., `3600` for 1 hour) or ISO 8601 timestamp

Best Practice: Set shorter expiration times for high-value transactions. If a session expires before the customer completes payment, create a new session.

Retrieve a Session

curl https://api.atlas.co/functions/v1/sessions/sess_xxx \
  -H "Authorization: Bearer sk_test_xxx"

Cancel a Session

curl -X POST https://api.atlas.co/functions/v1/sessions/sess_xxx/cancel \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_reason": "requested_by_customer"}'

Cancellation reasons: duplicate, fraudulent, requested_by_customer, abandoned

Getting Started

Payments

UI Components

Billing

Data & Security

Mobile

Developer

Payment Sessions

Payment Flow

Create a Session

Request Parameters

Response

Session Lifecycle States

Session Expiration

Retrieve a Session

Cancel a Session

​Payment Flow

​Create a Session

​Request Parameters

​Response

​Session Lifecycle States

​Session Expiration

​Retrieve a Session

​Cancel a Session

Payment Flow

Create a Session

Request Parameters

Response

Session Lifecycle States

Session Expiration

Retrieve a Session

Cancel a Session