Create a Checkout Session

What is a Checkout Session?

A Checkout Session represents your customer’s payment session. It controls what the customer sees on the payment page: products, amount, currency, and available options.

Identifier format: cs_ followed by 24 alphanumeric characters.Example: cs_abc123def456ghi789jkl012

Session Modes

payment

One-time paymentFor one-time purchases of products or services.

subscription

SubscriptionTo create a recurring subscription with automatic billing.

setup

SetupTo save a payment method without making an immediate payment.

Create a Checkout Session

Basic Request

curl -X POST https://api.yabetoo.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel",
    "line_items": [
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 15000,
          "product_data": {
            "name": "Premium T-shirt"
          }
        },
        "quantity": 2
      }
    ]
  }'

Required Parameters

Parameter	Type	Description
`success_url`	string	Redirect URL after successful payment
`line_items`	array	List of items to purchase

Optional Parameters

Parameter	Type	Description
`cancel_url`	string	Redirect URL if customer cancels
`mode`	string	`payment`, `subscription`, or `setup` (default: `payment`)
`customer`	string	ID of an existing customer (`cus_xxx`)
`customer_email`	string	Customer email (pre-fills the form)
`client_reference_id`	string	Your internal reference (e.g., order ID)
`allow_promotion_codes`	boolean	Allow promo codes
`locale`	string	Page language (`fr`, `en`, etc.)
`expires_at`	number	Unix timestamp for expiration
`metadata`	object	Custom data

Define Items (line_items)

You have two options for defining items:

Inline price (price_data)
Existing price (price)

Define the price directly in the request:

{
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 25000,
        "product_data": {
          "name": "JavaScript Training",
          "description": "Full access to the course",
          "images": ["https://example.com/image.jpg"]
        }
      },
      "quantity": 1
    }
  ]
}

Reference a price created in your catalog:

{
  "line_items": [
    {
      "price": "price_abc123def456",
      "quantity": 1
    }
  ]
}

Use pre-created prices for centralized catalog management.

Line Item Structure

Field	Type	Description
`price_data`	object	Inline defined price (see below)
`price`	string	ID of an existing price (`price_xxx`)
`quantity`	number	Quantity (minimum 1)
`adjustable_quantity`	object	Allows customer to modify quantity

Price Data Structure

Field	Type	Description
`currency`	string	Currency code (`XOF`, `EUR`, `USD`)
`unit_amount`	number	Unit price
`product_data`	object	Product information
`recurring`	object	For subscriptions only

Product Data Structure

Field	Type	Description
`name`	string	Product name (required)
`description`	string	Description
`images`	array	Image URLs
`metadata`	object	Custom data

Recurring Subscriptions

To create a subscription, use mode: "subscription" and add recurring in price_data:

{
  "mode": "subscription",
  "success_url": "https://your-site.com/success",
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 9900,
        "product_data": {
          "name": "Pro Subscription"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ]
}

Available Intervals

Interval	Description
`day`	Daily billing
`week`	Weekly billing
`month`	Monthly billing
`year`	Annual billing

Advanced Options

Collect Addresses

{
  "billing_address_collection": "required",
  "shipping_address_collection": {
    "allowed_countries": ["CG", "CD", "CI", "SN"]
  }
}

Collect Phone Number

{
  "phone_number_collection": {
    "enabled": true
  }
}

{
  "allow_promotion_codes": true
}

{
  "discounts": [
    {
      "promotion_code": "promo_abc123"
    }
  ]
}

Customize the Payment Button

{
  "submit_type": "pay"
}

Value	Button Text
`auto`	Automatic based on context
`pay`	”Pay”
`book`	”Book”
`donate`	”Donate”

Adjustable Quantity

Allow the customer to modify quantity on the payment page:

{
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 5000,
        "product_data": { "name": "Item" }
      },
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ]
}

Complete Example

curl -X POST https://api.yabetoo.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "success_url": "https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://your-site.com/cancel",
    "customer_email": "customer@example.com",
    "client_reference_id": "order_12345",
    "allow_promotion_codes": true,
    "billing_address_collection": "required",
    "phone_number_collection": { "enabled": true },
    "locale": "en",
    "metadata": {
      "order_id": "12345",
      "source": "website"
    },
    "line_items": [
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 25000,
          "product_data": {
            "name": "HD Screen",
            "description": "24 inch Full HD screen",
            "images": ["https://example.com/screen.jpg"]
          }
        },
        "quantity": 1
      },
      {
        "price_data": {
          "currency": "XOF",
          "unit_amount": 5000,
          "product_data": {
            "name": "HDMI Cable"
          }
        },
        "quantity": 2
      }
    ]
  }'

Response

{
  "id": "cs_abc123def456ghi789",
  "object": "checkout.session",
  "mode": "payment",
  "status": "open",
  "payment_status": "unpaid",
  "url": "https://checkout.yabetoo.com/cs_abc123def456ghi789",
  "success_url": "https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://your-site.com/cancel",
  "customer_email": "customer@example.com",
  "client_reference_id": "order_12345",
  "amount_subtotal": 35000,
  "amount_total": 35000,
  "amount_discount": 0,
  "currency": "XOF",
  "allow_promotion_codes": true,
  "line_items": [
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 25000,
        "product_data": { "name": "HD Screen" }
      },
      "quantity": 1,
      "amount_subtotal": 25000,
      "amount_total": 25000
    },
    {
      "price_data": {
        "currency": "XOF",
        "unit_amount": 5000,
        "product_data": { "name": "HDMI Cable" }
      },
      "quantity": 2,
      "amount_subtotal": 10000,
      "amount_total": 10000
    }
  ],
  "metadata": {
    "order_id": "12345",
    "source": "website"
  },
  "expires_at": "2024-01-15T12:00:00.000Z",
  "created_at": "2024-01-15T11:00:00.000Z"
}

Response Fields

Field	Description
`id`	Unique session identifier
`url`	Payment page URL
`status`	`open`, `complete`, or `expired`
`payment_status`	`unpaid`, `paid`, or `no_payment_required`
`amount_subtotal`	Subtotal before discounts
`amount_total`	Total amount to pay
`amount_discount`	Applied discounts amount

Redirect the Customer

Once the session is created, redirect the customer to the payment URL:

// Server-side: create the session
const session = await createCheckoutSession(/* ... */);

// Client-side: redirect
window.location.href = session.url;

After Payment

Redirection

After payment, the customer is redirected to success_url with the session ID:

https://your-site.com/success?session_id=cs_abc123def456

Verify Status

Never trust the redirect alone. Always verify the session status server-side.

// Get session ID from URL
const sessionId = new URLSearchParams(window.location.search).get("session_id");

// Verify status server-side
const response = await fetch(
  "https://api.yabetoo.com/v1/checkout/sessions/" + sessionId,
  {
    headers: {
      Authorization: "Bearer sk_live_...",
    },
  }
);

const session = await response.json();

if (session.status === "complete" && session.payment_status === "paid") {
  // Payment confirmed - process the order
}

Webhooks

For a robust integration, use webhooks to receive payment notifications:

{
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_abc123def456",
      "status": "complete",
      "payment_status": "paid",
      "amount_total": 35000,
      "currency": "XOF"
    }
  }
}

See Webhooks Documentation for more details.

Session Statuses

Status	Description
`open`	Active session, awaiting payment
`complete`	Payment successful
`expired`	Session expired (not paid within deadline)

Best Practices

Security

Always create sessions server-side
Never store API keys client-side
Verify status via API or webhooks

User Experience

Pre-fill email if you have it
Use client_reference_id to link to your order
Customize submit_type based on context

Error Handling

Handle the case where customer cancels
Plan for session expiration
Use webhooks for edge cases

Next Steps

Webhooks

Receive real-time notifications

Promo Codes

Apply discounts to your sessions

Get started

Build a checkout page

Build an advanced payments integration

Disbursements

Remittance

Use Payment Links

Create a Checkout Session

What is a Checkout Session?

Session Modes

payment

subscription

setup

Create a Checkout Session

Basic Request

Required Parameters

Optional Parameters

Define Items (line_items)

Line Item Structure

Price Data Structure

Product Data Structure

Recurring Subscriptions

Available Intervals

Advanced Options

Collect Addresses

Collect Phone Number

Customize the Payment Button

Adjustable Quantity

Complete Example

Response

Response Fields

Redirect the Customer

After Payment

Redirection

Verify Status

Webhooks

Session Statuses

Best Practices

Next Steps

Webhooks

Promo Codes

Get started

Build a checkout page

Build an advanced payments integration

Disbursements

Remittance

Use Payment Links

​What is a Checkout Session?

​Session Modes

payment

subscription

setup

​Create a Checkout Session

​Basic Request

​Required Parameters

​Optional Parameters

​Define Items (line_items)

​Line Item Structure

​Price Data Structure

​Product Data Structure

​Recurring Subscriptions

​Available Intervals

​Advanced Options

​Collect Addresses

​Collect Phone Number

​Allow Promo Codes

​Apply a Promo Code Automatically

​Customize the Payment Button

​Adjustable Quantity

​Complete Example

​Response

​Response Fields

​Redirect the Customer

​After Payment

​Redirection

​Verify Status

​Webhooks

​Session Statuses

​Best Practices

​Next Steps

Webhooks

Promo Codes

What is a Checkout Session?

Session Modes

Create a Checkout Session

Basic Request

Required Parameters

Optional Parameters

Define Items (line_items)

Line Item Structure

Price Data Structure

Product Data Structure

Recurring Subscriptions

Available Intervals

Advanced Options

Collect Addresses

Collect Phone Number

Allow Promo Codes

Apply a Promo Code Automatically

Customize the Payment Button

Adjustable Quantity

Complete Example

Response

Response Fields

Redirect the Customer

After Payment

Redirection

Verify Status

Webhooks

Session Statuses

Best Practices

Next Steps