Checkout Sessions API

Checkout Sessions provide a hosted payment page that handles the entire payment flow.

The Checkout Session Object

{
  "id": "cs_abc123def456",
  "object": "checkout.session",
  "status": "open",
  "url": "https://paygate.44.200.142.19.nip.io/checkout/cs_abc123def456",
  "amount": 5000,
  "currency": "GHS",
  "payment": null,
  "payment_status": "unpaid",
  "customer": null,
  "customer_email": "customer@example.com",
  "success_url": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://yoursite.com/cancel",
  "metadata": {
    "order_id": "1234"
  },
  "expires_at": "2024-01-16T10:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"checkout.session"`
`status`	string	`open`, `complete`, `expired`
`url`	string	URL to redirect customer to
`amount`	integer	Amount in pesewas
`currency`	string	Currency code
`payment`	string	Payment ID (when complete)
`payment_status`	string	`unpaid`, `paid`
`customer`	string	Customer ID
`customer_email`	string	Pre-filled email
`success_url`	string	Redirect URL on success
`cancel_url`	string	Redirect URL on cancel
`metadata`	object	Custom metadata
`expires_at`	string	When session expires
`created_at`	string	Creation timestamp

Create a Checkout Session

Creates a new checkout session.

POST /v1/checkout/sessions

Request Body

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in pesewas
`currency`	string	No	Currency (default: `GHS`)
`success_url`	string	Yes	Redirect URL on success
`cancel_url`	string	Yes	Redirect URL on cancel
`customer`	string	No	Existing customer ID
`customer_email`	string	No	Pre-fill email
`customer_phone`	string	No	Pre-fill phone
`payment_method_types`	array	No	Allowed payment methods
`metadata`	object	No	Custom metadata
`expires_at`	string	No	Expiration timestamp

curl -X POST https://api.44.200.142.19.nip.io/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "GHS",
    "success_url": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yoursite.com/cancel",
    "customer_email": "customer@example.com",
    "metadata": {
      "order_id": "1234"
    }
  }'

const session = await paygate.checkout.sessions.create({
  amount: 5000,
  currency: 'GHS',
  success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://yoursite.com/cancel',
  customer_email: 'customer@example.com',
  metadata: {
    order_id: '1234'
  }
})

// Redirect customer to session.url
console.log(session.url)

session = client.checkout.sessions.create(
    amount=5000,
    currency='GHS',
    success_url='https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yoursite.com/cancel',
    customer_email='customer@example.com',
    metadata={'order_id': '1234'}
)

print(session.url)

$session = $paygate->checkout->sessions->create([
    'amount' => 5000,
    'currency' => 'GHS',
    'success_url' => 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
    'cancel_url' => 'https://yoursite.com/cancel',
    'customer_email' => 'customer@example.com',
    'metadata' => ['order_id' => '1234']
]);

echo $session->url;

URL Parameters

Use {CHECKOUT_SESSION_ID} in your URLs to include the session ID:

const session = await paygate.checkout.sessions.create({
  amount: 5000,
  success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://yoursite.com/cancel'
})

On redirect, {CHECKOUT_SESSION_ID} is replaced with the actual session ID:

https://yoursite.com/success?session_id=cs_abc123def456

Retrieve a Checkout Session

Retrieves a checkout session by ID.

GET /v1/checkout/sessions/:id

curl https://api.44.200.142.19.nip.io/v1/checkout/sessions/cs_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const session = await paygate.checkout.sessions.retrieve('cs_abc123def456')

session = client.checkout.sessions.retrieve('cs_abc123def456')

List Checkout Sessions

Returns a list of checkout sessions.

GET /v1/checkout/sessions

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`status`	string	Filter by status
`customer`	string	Filter by customer
`payment`	string	Filter by payment ID

curl "https://api.44.200.142.19.nip.io/v1/checkout/sessions?status=complete&limit=10" \
  -H "Authorization: Bearer sk_test_..."

const sessions = await paygate.checkout.sessions.list({
  status: 'complete',
  limit: 10
})

sessions = client.checkout.sessions.list(status='complete', limit=10)

Expire a Checkout Session

Manually expire an open session.

POST /v1/checkout/sessions/:id/expire

curl -X POST https://api.44.200.142.19.nip.io/v1/checkout/sessions/cs_abc123def456/expire \
  -H "Authorization: Bearer sk_test_..."

const session = await paygate.checkout.sessions.expire('cs_abc123def456')

session = client.checkout.sessions.expire('cs_abc123def456')

Session Statuses

Status	Description
`open`	Session is active and customer can pay
`complete`	Customer completed payment
`expired`	Session expired

Payment Statuses

Status	Description
`unpaid`	Payment not yet made
`paid`	Payment successful

Webhook Events

Event	Description
`checkout.session.completed`	Customer completed payment
`checkout.session.expired`	Session expired

app.post('/webhooks', (req, res) => {
  const event = Webhook.constructEvent(req.body, signature, secret)

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object

    // Fulfill the order
    await fulfillOrder(session.metadata.order_id)

    // Optionally send confirmation email
    await sendConfirmationEmail(session.customer_email)
  }

  res.json({ received: true })
})

Always use webhooks to verify payment completion. Don't rely solely on the redirect.

Integration Example

Backend (Express)

app.post('/create-checkout', async (req, res) => {
  const { orderId, amount } = req.body

  const session = await paygate.checkout.sessions.create({
    amount,
    currency: 'GHS',
    success_url: `${process.env.FRONTEND_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.FRONTEND_URL}/cart`,
    metadata: { order_id: orderId }
  })

  res.json({ checkoutUrl: session.url })
})

// Success page verification
app.get('/verify-session', async (req, res) => {
  const { session_id } = req.query

  const session = await paygate.checkout.sessions.retrieve(session_id)

  if (session.status === 'complete' && session.payment_status === 'paid') {
    res.json({ success: true, orderId: session.metadata.order_id })
  } else {
    res.json({ success: false })
  }
})

Frontend (React)

function CheckoutButton({ orderId, amount }) {
  const [loading, setLoading] = useState(false)

  const handleCheckout = async () => {
    setLoading(true)

    const response = await fetch('/create-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ orderId, amount })
    })

    const { checkoutUrl } = await response.json()

    // Redirect to PayGate checkout
    window.location.href = checkoutUrl
  }

  return (
    <button onClick={handleCheckout} disabled={loading}>
      {loading ? 'Loading...' : 'Checkout'}
    </button>
  )
}

Checkout Sessions

On this page