> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencharge.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Checkout Session

> Receive orders from Merchant Gateways and return a checkout URL

## Overview

Merchant Gateways call this endpoint to create a hosted checkout session. You return a URL where the end user will be redirected to complete payment on your checkout page.

## When This Is Called

1. A customer initiates checkout at a merchant's website
2. The merchant sends the order to their Merchant Gateway
3. The Merchant Gateway forwards the order to your Payment Gateway
4. You create a checkout session and return the URL
5. The customer is redirected to your checkout page

## Implementation

```javascript theme={null}
app.post('/checkout/create', signatureAuth, async (req, res) => {
  const { order, signature, merchantOcid, urls } = req.body;
  const merchantGatewayOcid = req.headers['x-oc-id'];

  // 1. Verify the order signature matches the merchant
  const merchant = await fetchMerchantMetadata(merchantOcid);
  if (!verifyOrderSignature(order, signature, merchant.config.publicKey)) {
    return res.status(400).json({
      error: { code: 'INVALID_SIGNATURE', message: 'Order signature invalid' }
    });
  }

  // 2. Create checkout session
  const session = await db.createCheckoutSession({
    id: crypto.randomUUID(),
    merchantOcid,
    merchantGatewayOcid,
    order,
    signature,
    urls,
    status: 'pending',
    expiresAt: Date.now() + 30 * 60 * 1000
  });

  // 3. Return checkout URL
  res.json({
    checkout_url: `https://checkout.yourgateway.com/${session.id}`,
    expires_at: Math.floor(session.expiresAt / 1000)
  });
});
```

## After Payment

When the user completes payment on your checkout page:

1. Credit the merchant gateway account.
2. Redirect the user to the `urls.success` URL

```javascript theme={null}
async function completeCheckout(session, user) {
  // Generate transfer proof for the merchant gateway
  const proof = await generateProof(user, session.order, session.merchantOcid);

  // Update session
  await db.updateCheckoutSession(session.id, {
    status: 'completed',
    proof
  });

  // Redirect user to success URL
  return session.urls?.success || '/success';
}
```

<Card title="Settlement Guide" icon="arrow-right" href="/payment-gateway-api/settlement">
  Learn about the different ways to settle payments with merchants
</Card>


## OpenAPI

````yaml payment-gateway-api/endpoint/payment-gateway-api/openapi.json post /checkout/create
openapi: 3.1.0
info:
  title: Opencharge Payment Gateway API
  description: >-
    API specification for payment gateways integrating with the Opencharge
    protocol. Payment gateways help end users pay merchants through wallet apps
    or hosted checkout pages.
  version: 0.1.0
  license:
    name: MIT
servers:
  - url: https://api.wallet.example/opencharge
    description: Example payment gateway Opencharge endpoint
security: []
paths:
  /checkout/create:
    post:
      summary: Create checkout session
      description: >-
        Merchant Gateways POST orders to this endpoint to create a hosted
        checkout session. Returns a checkout URL where the end user will be
        redirected to complete payment.
      operationId: createCheckout
      parameters:
        - $ref: '#/components/parameters/X-OC-ID'
        - $ref: '#/components/parameters/X-OC-Timestamp'
        - $ref: '#/components/parameters/X-OC-Nonce'
        - $ref: '#/components/parameters/X-OC-Signature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutCreateRequest'
            example:
              order:
                id: ord_abc123
                ocid: 500
                reference: INV-001
                amount: '99.99'
                currency: USD
                items:
                  - id: item_001
                    name: Product A
                    quantity: 1
                    price: '99.99'
                memo: Order from Merchant Store
                createdAt: 1706313600
                expiresAt: 1706400000
                accepts:
                  - 100
                  - 101
                  - 102
              signature: a1b2c3d4e5f6...merchant_sig
              merchantOcid: 500
              urls:
                success: https://merchant.example/checkout/success
                cancel: https://merchant.example/checkout/cancel
      responses:
        '200':
          description: Checkout session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutCreateResponse'
              example:
                checkout_url: https://checkout.wallet.example/pay/sess_xyz789
                session_id: sess_xyz789
                expires_at: 1706400000
        '400':
          description: Invalid request or signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    X-OC-ID:
      name: X-OC-ID
      in: header
      required: true
      description: Caller's OCID
      schema:
        type: string
      example: '500'
    X-OC-Timestamp:
      name: X-OC-Timestamp
      in: header
      required: true
      description: Unix timestamp in seconds
      schema:
        type: string
      example: '1706500000'
    X-OC-Nonce:
      name: X-OC-Nonce
      in: header
      required: true
      description: Unique request identifier
      schema:
        type: string
      example: req_abc123
    X-OC-Signature:
      name: X-OC-Signature
      in: header
      required: true
      description: secp256k1 ECDSA signature
      schema:
        type: string
      example: a1b2c3d4...7f1b
  schemas:
    CheckoutCreateRequest:
      type: object
      required:
        - order
        - signature
        - merchantOcid
        - urls
      properties:
        order:
          $ref: '#/components/schemas/Order'
        signature:
          type: string
          description: Merchant's signature on the order
        merchantOcid:
          type: integer
          description: The merchant's OCID
        urls:
          type: object
          properties:
            success:
              type: string
              format: uri
              description: Redirect URL after successful payment
            cancel:
              type: string
              format: uri
              description: Redirect URL if user cancels
    CheckoutCreateResponse:
      type: object
      required:
        - checkout_url
        - session_id
      properties:
        checkout_url:
          type: string
          format: uri
          description: URL to redirect user to for payment
        session_id:
          type: string
          description: Unique checkout session identifier
        expires_at:
          type: integer
          description: Unix timestamp when session expires
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - INVALID_SIGNATURE
                - TIMESTAMP_EXPIRED
                - NONCE_REUSED
                - UNKNOWN_OCID
                - SESSION_NOT_FOUND
                - SESSION_EXPIRED
                - SESSION_USED
                - INVALID_PROOF
                - PROOF_SIGNATURE_INVALID
                - ISSUER_NOT_ACCEPTED
                - INSUFFICIENT_FUNDS
                - ACCOUNT_NOT_FOUND
            message:
              type: string
            details:
              type: object
    Order:
      type: object
      required:
        - id
        - ocid
        - amount
        - currency
        - createdAt
      properties:
        id:
          type: string
        ocid:
          type: integer
        reference:
          type: string
        amount:
          type: string
        currency:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        memo:
          type: string
        expiresAt:
          type: integer
        createdAt:
          type: integer
        accepts:
          type: array
          items:
            type: integer
    OrderItem:
      type: object
      required:
        - id
        - name
        - quantity
        - price
      properties:
        id:
          type: string
        name:
          type: string
        quantity:
          type: number
        price:
          type: string

````