Accept payments

Checkout Sessions

Accept payments through hosted checkout pages. Create a session server-side, then redirect your customer or embed the form.

5 min read

Overview

A Checkout Session represents a single payment intent with line items, currency, and redirect URLs. The customer completes payment on a PaymentHooks-hosted page, then is redirected back to your site.

Redirect

Send customers to hosted checkout

Iframe embed

Embed checkout inside your page

Inline render

Render form directly in your DOM

How it works

1Your server creates a Checkout Session via the API
2Redirect the customer to the session URL, or embed it
3Customer enters card details and submits payment
4PaymentHooks processes the payment and fires a webhook
5Customer is redirected to your success URL

Create a checkout session

POST /api/v1/checkout-sessions

curl -X POST https://paymenthooks.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"lineItems": [{"description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990}], "mode": "payment", "currency": "USD"}'

Request parameters

Parameter	Type	Required	Description
lineItems	array	Yes	Array of line items. Each: { description (string, required), quantity (integer >= 1), unitPrice (integer, cents) }
mode	string	Yes	Payment mode: payment, subscription, or setup
currency	string	No	Three-letter ISO currency code (defaults to USD)
originalCurrency	string	No	Merchant’s original pricing currency (e.g. INR, EUR). Defaults to currency
taxRate	number	No	Tax percentage (e.g. 18 for 18%). Auto-computes taxAmount if taxAmount is not provided
taxAmount	number	No	Tax amount in cents. Overrides auto-computation from taxRate
convenienceFee	number	No	Convenience fee in cents, added to the total
customerId	string	No	ID of an existing customer to associate
customerEmail	string	No	Pre-fill email on the checkout form
successUrl	string	No	Redirect URL after successful payment
cancelUrl	string	No	Redirect URL if customer cancels
webhookUrl	string	No	URL to receive a webhook POST when checkout completes or fails. HTTPS recommended for production. Max 2048 chars
paymentMethod	string	No	Preferred payment method (stored in metadata)
metadata	object	No	Arbitrary key-value pairs to attach

Line items

Each object in the lineItems array describes a product or charge.

Field	Type	Required	Description
description	string	Yes	Display name of the item
quantity	integer	Yes	Number of units (>= 1)
unitPrice	integer	Yes	Price per unit in smallest currency unit (cents)

Endpoints & Responses

Complete payload and response for every checkout session endpoint. Click copy on any block.

POST/v1/checkout-sessionsCreate a checkout session

Request Payload

{
  "lineItems": [
    { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990 }
  ],
  "mode": "payment",
  "currency": "USD",
  "taxRate": 18,
  "convenienceFee": 40,
  "customerEmail": "[email protected]",
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "webhookUrl": "https://yoursite.com/webhooks/paymenthooks",
  "metadata": { "orderId": "order_789" }
}

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "businessEntityId": "be_001",
    "customerId": null,
    "customerEmail": "[email protected]",
    "mode": "payment",
    "status": "open",
    "currency": "USD",
    "originalCurrency": "USD",
    "amountTotal": 3568,
    "subtotal": 2990,
    "taxRate": 18,
    "taxAmount": 538,
    "convenienceFee": 40,
    "exchangeRate": 1.0,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990 }
    ],
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "webhookUrl": "https://yoursite.com/webhooks/paymenthooks",
    "url": "https://paymenthooks.com/checkout/cs_1717000000_abc123",
    "metadata": { "orderId": "order_789" },
    "expiresAt": "2026-05-17T12:00:00.000Z",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

GET/v1/checkout-sessions?page=1&pageSize=10List checkout sessions

Response

{
  "data": [
    {
      "id": "cs_1717000000_abc123",
      "mode": "payment",
      "status": "complete",
      "currency": "USD",
      "amountTotal": 2990,
      "customerEmail": "[email protected]",
      "createdAt": "2026-05-16T12:00:00.000Z"
    }
  ],
  "meta": { "total": 85, "page": 1, "pageSize": 10 },
  "error": null
}

GET/v1/checkout-sessions/:idRetrieve a session (authenticated)

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "customerEmail": "[email protected]",
    "mode": "payment",
    "status": "complete",
    "currency": "USD",
    "amountTotal": 2990,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990 }
    ],
    "url": "https://paymenthooks.com/checkout/cs_1717000000_abc123",
    "paymentId": "pay_1717000000_abc123",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

GET/v1/checkout-sessions/:id/publicRetrieve a session (public, no auth). Branding resolves from BusinessEntity if linked, otherwise from Merchant.

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "mode": "payment",
    "status": "open",
    "currency": "USD",
    "originalCurrency": "USD",
    "amountTotal": 2990,
    "subtotal": 2500,
    "taxRate": 18,
    "taxAmount": 450,
    "convenienceFee": 40,
    "exchangeRate": 1.0,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2500, "total": 2500 }
    ],
    "availableGateways": [
      { "id": "conn_001", "displayName": "Stripe", "catalogGatewayId": "gw_stripe", "mode": "live" }
    ],
    "platformMode": "live",
    "merchantBranding": {
      "businessName": "Acme Corp",
      "logoUrl": "https://example.com/logos/acme.svg",
      "brandColor": "#4D5AFF"
    },
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "expiresAt": "2026-05-17T12:00:00.000Z",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

POST/v1/checkout-sessions/:id/payProcess payment (public)

Request Payload

{
  "email": "[email protected]",
  "cardNumber": "4242424242424242",
  "cardExpiry": "12/28",
  "cardCvc": "123",
  "cardholderName": "Jane Doe"
}

Response

{
  "data": {
    "paymentId": "pay_1717000000_abc123",
    "status": "succeeded",
    "amount": 2990,
    "currency": "USD",
    "cardLast4": "4242",
    "cardBrand": "visa",
    "redirectUrl": "https://yoursite.com/success"
  },
  "error": null
}

Per-session webhooks

Pass a webhookUrl when creating a checkout session to receive a POST notification when payment completes or fails. This is in addition to any global webhook endpoints you have configured.

Event	When
checkout.session.completed	Payment succeeded
checkout.session.payment_failed	Payment failed or was declined

Example webhook payload:

jsonjson

{
  "id": "evt_abc123",
  "type": "checkout.session.completed",
  "created": 1717000000,
  "data": {
    "sessionId": "cs_1717000000_abc123",
    "paymentId": "pay_1717000000_abc123",
    "status": "success",
    "amount": 3568,
    "currency": "USD",
    "customerEmail": "[email protected]",
    "gateway": "gw_stripe"
  }
}

Session statuses

openSession is active and ready for payment

completePayment succeeded, session closed

expiredSession expired before payment

Accept payments

Checkout Sessions

Accept payments through hosted checkout pages. Create a session server-side, then redirect your customer or embed the form.

5 min read

Overview

A Checkout Session represents a single payment intent with line items, currency, and redirect URLs. The customer completes payment on a PaymentHooks-hosted page, then is redirected back to your site.

Redirect

Send customers to hosted checkout

Iframe embed

Embed checkout inside your page

Inline render

Render form directly in your DOM

How it works

1Your server creates a Checkout Session via the API
2Redirect the customer to the session URL, or embed it
3Customer enters card details and submits payment
4PaymentHooks processes the payment and fires a webhook
5Customer is redirected to your success URL

Create a checkout session

POST /api/v1/checkout-sessions

curl -X POST https://paymenthooks.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"lineItems": [{"description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990}], "mode": "payment", "currency": "USD"}'

Request parameters

Parameter	Type	Required	Description
lineItems	array	Yes	Array of line items. Each: { description (string, required), quantity (integer >= 1), unitPrice (integer, cents) }
mode	string	Yes	Payment mode: payment, subscription, or setup
currency	string	No	Three-letter ISO currency code (defaults to USD)
originalCurrency	string	No	Merchant’s original pricing currency (e.g. INR, EUR). Defaults to currency
taxRate	number	No	Tax percentage (e.g. 18 for 18%). Auto-computes taxAmount if taxAmount is not provided
taxAmount	number	No	Tax amount in cents. Overrides auto-computation from taxRate
convenienceFee	number	No	Convenience fee in cents, added to the total
customerId	string	No	ID of an existing customer to associate
customerEmail	string	No	Pre-fill email on the checkout form
successUrl	string	No	Redirect URL after successful payment
cancelUrl	string	No	Redirect URL if customer cancels
webhookUrl	string	No	URL to receive a webhook POST when checkout completes or fails. HTTPS recommended for production. Max 2048 chars
paymentMethod	string	No	Preferred payment method (stored in metadata)
metadata	object	No	Arbitrary key-value pairs to attach

Line items

Each object in the lineItems array describes a product or charge.

Field	Type	Required	Description
description	string	Yes	Display name of the item
quantity	integer	Yes	Number of units (>= 1)
unitPrice	integer	Yes	Price per unit in smallest currency unit (cents)

Endpoints & Responses

Complete payload and response for every checkout session endpoint. Click copy on any block.

POST/v1/checkout-sessionsCreate a checkout session

Request Payload

{
  "lineItems": [
    { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990 }
  ],
  "mode": "payment",
  "currency": "USD",
  "taxRate": 18,
  "convenienceFee": 40,
  "customerEmail": "[email protected]",
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "webhookUrl": "https://yoursite.com/webhooks/paymenthooks",
  "metadata": { "orderId": "order_789" }
}

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "businessEntityId": "be_001",
    "customerId": null,
    "customerEmail": "[email protected]",
    "mode": "payment",
    "status": "open",
    "currency": "USD",
    "originalCurrency": "USD",
    "amountTotal": 3568,
    "subtotal": 2990,
    "taxRate": 18,
    "taxAmount": 538,
    "convenienceFee": 40,
    "exchangeRate": 1.0,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990 }
    ],
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "webhookUrl": "https://yoursite.com/webhooks/paymenthooks",
    "url": "https://paymenthooks.com/checkout/cs_1717000000_abc123",
    "metadata": { "orderId": "order_789" },
    "expiresAt": "2026-05-17T12:00:00.000Z",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

GET/v1/checkout-sessions?page=1&pageSize=10List checkout sessions

Response

{
  "data": [
    {
      "id": "cs_1717000000_abc123",
      "mode": "payment",
      "status": "complete",
      "currency": "USD",
      "amountTotal": 2990,
      "customerEmail": "[email protected]",
      "createdAt": "2026-05-16T12:00:00.000Z"
    }
  ],
  "meta": { "total": 85, "page": 1, "pageSize": 10 },
  "error": null
}

GET/v1/checkout-sessions/:idRetrieve a session (authenticated)

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "customerEmail": "[email protected]",
    "mode": "payment",
    "status": "complete",
    "currency": "USD",
    "amountTotal": 2990,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2990, "total": 2990 }
    ],
    "url": "https://paymenthooks.com/checkout/cs_1717000000_abc123",
    "paymentId": "pay_1717000000_abc123",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

GET/v1/checkout-sessions/:id/publicRetrieve a session (public, no auth). Branding resolves from BusinessEntity if linked, otherwise from Merchant.

Response

{
  "data": {
    "id": "cs_1717000000_abc123",
    "merchantId": "merch_001",
    "mode": "payment",
    "status": "open",
    "currency": "USD",
    "originalCurrency": "USD",
    "amountTotal": 2990,
    "subtotal": 2500,
    "taxRate": 18,
    "taxAmount": 450,
    "convenienceFee": 40,
    "exchangeRate": 1.0,
    "lineItems": [
      { "description": "Pro Plan", "quantity": 1, "unitPrice": 2500, "total": 2500 }
    ],
    "availableGateways": [
      { "id": "conn_001", "displayName": "Stripe", "catalogGatewayId": "gw_stripe", "mode": "live" }
    ],
    "platformMode": "live",
    "merchantBranding": {
      "businessName": "Acme Corp",
      "logoUrl": "https://example.com/logos/acme.svg",
      "brandColor": "#4D5AFF"
    },
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "expiresAt": "2026-05-17T12:00:00.000Z",
    "createdAt": "2026-05-16T12:00:00.000Z"
  },
  "error": null
}

POST/v1/checkout-sessions/:id/payProcess payment (public)

Request Payload

{
  "email": "[email protected]",
  "cardNumber": "4242424242424242",
  "cardExpiry": "12/28",
  "cardCvc": "123",
  "cardholderName": "Jane Doe"
}

Response

{
  "data": {
    "paymentId": "pay_1717000000_abc123",
    "status": "succeeded",
    "amount": 2990,
    "currency": "USD",
    "cardLast4": "4242",
    "cardBrand": "visa",
    "redirectUrl": "https://yoursite.com/success"
  },
  "error": null
}

Per-session webhooks

Pass a webhookUrl when creating a checkout session to receive a POST notification when payment completes or fails. This is in addition to any global webhook endpoints you have configured.

Event	When
checkout.session.completed	Payment succeeded
checkout.session.payment_failed	Payment failed or was declined

Example webhook payload:

jsonjson

{
  "id": "evt_abc123",
  "type": "checkout.session.completed",
  "created": 1717000000,
  "data": {
    "sessionId": "cs_1717000000_abc123",
    "paymentId": "pay_1717000000_abc123",
    "status": "success",
    "amount": 3568,
    "currency": "USD",
    "customerEmail": "[email protected]",
    "gateway": "gw_stripe"
  }
}

Session statuses

openSession is active and ready for payment

completePayment succeeded, session closed

expiredSession expired before payment