Skip to main content
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

ParameterTypeRequiredDescription
amountintegerYesAmount in smallest currency unit (cents for USD)
currencystringYesThree-letter ISO 4217 currency code (USD, EUR, GBP)
external_idstringNoYour order or cart reference (idempotent if reused)
capture_methodstringNo”automatic” (default) or “manual” for auth-only
customer.emailstringNoCustomer email address
customer.namestringNoCustomer full name
success_urlstringNoRedirect after successful payment
cancel_urlstringNoRedirect after cancellation
payment_method_typesarrayNoAllowed methods: card, apple_pay, google_pay, bank_account
metadataobjectNoCustom 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:
StateDescription
requires_payment_methodSession created, waiting for customer to enter payment details
requires_actionAdditional action needed (3DS authentication, redirect)
processingPayment is being processed
succeededPayment completed successfully
failedPayment failed
canceledCustomer abandoned checkout or session expired

​
Session Expiration

Sessions expire automatically to prevent stale payment intents. Expired sessions cannot be completed.
SettingDescription
DefaultSessions expire 24 hours after creation
CustomSet 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