> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment session > Create a new payment session. The server derives the source system from the merchant store and returns a checkout URL. ## OpenAPI ````yaml /en/api/openapi.json post /api/v1/checkout/sessions/create openapi: 3.1.0 info: title: StablePay Payment API version: '2026-03-31' summary: Payment session and payment method APIs. description: >- OpenAPI specification for StablePay Payment APIs. Notes: - Base URL: https://api.stablepay.co - Authentication: Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` + `X-StablePay-Signature` - Signed payload: `{timestamp}.{nonce}.{requestBody}` - Signature algorithm: HMAC-SHA256, lowercase hex - For GET requests, `requestBody` is an empty string. servers: - url: https://api.stablepay.co description: Production security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: Payment Sessions description: Create, retrieve, and cancel payment sessions. - name: Payment Methods description: Retrieve payment methods. paths: /api/v1/checkout/sessions/create: post: tags: - Payment Sessions summary: Create a payment session description: >- Create a new payment session. The server derives the source system from the merchant store and returns a checkout URL. operationId: createPaymentSession parameters: - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentSessionRequest' responses: '200': description: Payment session created. content: application/json: schema: $ref: '#/components/schemas/PaymentSession' '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Service unavailable, for example when the exchange-rate service is unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix timestamp in seconds. Must be within 5 minutes of server time. schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. schema: type: string example: a1b2c3d4e5f6... schemas: CreatePaymentSessionRequest: type: object required: - amount - currency - order_id additionalProperties: false properties: amount: type: integer format: int64 minimum: 1 description: Payment amount in the minor unit of the currency. currency: type: string description: Merchant ledger currency, for example `USD`. order_id: type: string description: Merchant order ID. Must be unique for the merchant. description: type: string description: Order description, stored in session metadata. line_items: type: array description: >- Line items. If provided, `amount` must equal item subtotal plus tax and shipping. items: $ref: '#/components/schemas/LineItem' tax_amount: type: integer format: int64 minimum: 0 description: Tax amount in minor units. shipping_amount: type: integer format: int64 minimum: 0 description: Shipping amount in minor units. success_url: type: string format: uri description: Redirect URL after successful payment. cancel_url: type: string format: uri description: Redirect URL after payment cancellation. email: type: string format: email description: >- Payer email. Optional, but strongly recommended for payment notifications, customer identification, and post-payment reconciliation. Stored as metadata.email. metadata: type: object additionalProperties: type: string description: >- Merchant metadata key-value pairs. Non-string values are returned as strings. PaymentSession: type: object required: - id - amount_total - currency - payment_status - created - expires_at properties: id: type: string description: Payment session ID. amount_total: type: integer format: int64 description: Total amount in minor units. currency: type: string description: Merchant ledger currency, returned in lowercase. payment_status: $ref: '#/components/schemas/PaymentStatus' created: type: integer format: int64 description: Creation time, Unix seconds. expires_at: type: integer format: int64 description: Expiration time, Unix seconds. url: type: string format: uri description: Checkout URL. line_items: type: array items: $ref: '#/components/schemas/LineItem' description: Line items. tax_amount: type: integer format: int64 description: Tax amount in minor units. shipping_amount: type: integer format: int64 description: Shipping amount in minor units. exchange_rate: type: string description: Exchange rate when currency conversion applies. target_currency: type: string description: Actual on-chain payment currency, for example `USDT`. target_amount_total: type: integer format: int64 description: Target amount in target-currency minor units. rate_locked_at: type: integer format: int64 description: Rate lock time, Unix seconds. subscription_id: type: string description: Related subscription ID, returned for subscription payments. invoice_id: type: string description: Related invoice ID, returned for invoice or subscription payments. metadata: type: object additionalProperties: type: string description: Merchant metadata. ErrorResponse: type: object description: Error response. properties: error: type: object properties: type: type: string description: Error type. code: type: string description: Error code. message: type: string description: Error message. param: type: string description: Related parameter. doc_url: type: string description: Error documentation URL. decline_code: type: string description: Decline code. request_log_url: type: string description: Request log URL. charge: type: string description: Related payment ID. request_id: type: string description: Request ID. timestamp: type: integer format: int64 description: Error timestamp in Unix seconds. LineItem: type: object required: - price_data - quantity additionalProperties: false properties: price_data: $ref: '#/components/schemas/PriceData' quantity: type: integer minimum: 1 description: Item quantity. Must be greater than 0. PaymentStatus: type: string enum: - pending - processing - paid - failed - expired - canceled description: >- Payment status. `confirming` is returned as `processing`; `completed` is returned as `paid`. PriceData: type: object required: - currency - unit_amount - product_data additionalProperties: false properties: currency: type: string description: Item currency. Must match the top-level `currency`. unit_amount: type: integer format: int64 minimum: 1 description: Unit amount in minor units. product_data: $ref: '#/components/schemas/ProductData' ProductData: type: object required: - name additionalProperties: false properties: name: type: string description: Product name. Cannot be empty. description: type: string description: Product description. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key, for example `Bearer sk_live_xxx`. stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix timestamp in seconds. Must be within 5 minutes of server time. stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: Replay-protection nonce, 16-64 characters. Use a fresh UUID per request. stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- Lowercase hex HMAC-SHA256 of `{timestamp}.{nonce}.{requestBody}` signed with the merchant API Secret. For GET requests, `requestBody` is an empty string. ````