​

Create a Checkout Session

​

Endpoint

• Endpoint: POST /v1/checkouts
• Description: Create a new checkout session.
• Request Body:
  Copy

  {
    "amount": 1000,
    "currency": "usd",
    "payment_method": "card",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }
  
• Response:
  Copy

  {
    "id": "cs_test_123",
    "amount": 1000,
    "currency": "usd",
    "status": "pending",
    "created_at": "2024-01-01T12:00:00Z",
    "customer_id": "cus_456"
  }
  

​

Parameters

• amount (integer, required): The total amount for the checkout session in the smallest currency unit (e.g., cents for USD).
• currency (string, required): The currency code (e.g., “usd”).
• payment_method (string, required): The payment method type (e.g., “card”).
• success_url (string, required): The URL to redirect to upon successful payment.
• cancel_url (string, required): The URL to redirect to if the payment is canceled.

​

Example Request

curl -X POST https://api.example.com/v1/checkouts \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "usd",
    "payment_method": "card",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

​

Example Response

{
  "id": "cs_test_123",
  "amount": 1000,
  "currency": "usd",
  "status": "pending",
  "created_at": "2024-01-01T12:00:00Z",
  "customer_id": "cus_456"
}

​

Notes

• Ensure that all required parameters are included in the request body.
• The response includes the unique identifier of the newly created checkout session along with its details.

​

Errors

• 400 Bad Request: Missing or invalid request parameters.
• 401 Unauthorized: Invalid or missing API key.
• 500 Internal Server Error: An error occurred on the server while processing the request.

​

See Also

• Retrieve a Checkout Session
• Refund a Checkout Session
• Search Checkout Sessions