> ## Documentation Index > Fetch the complete documentation index at: https://bkey.id/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Payment Session > Create a payment session (merchant-facing). Called by plugins (WooCommerce, Medusa, etc.) to start a BKey-approved payment flow. The merchant authenticates with a mk_live_* / mk_test_* API key. Returns an approvalUrl to redirect the shopper to. ## OpenAPI ````yaml post /v1/payment-sessions/ openapi: 3.1.0 info: title: BKey API description: Biometric approval infrastructure for AI agents — OAuth 2.1 + CIBA version: 1.0.0 contact: name: BKey url: https://bkey.id email: dev@bkey.id license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.bkey.id description: Production security: - bearerAuth: [] tags: - name: OAuth description: OAuth 2.1 token, device auth, CIBA, revocation - name: Checkout description: Agent-initiated checkout with biometric approval - name: Vault description: Encrypted secret storage with biometric access - name: Payments description: Payment methods and shared payment tokens - name: Identity description: DID and identity management paths: /v1/payment-sessions/: post: tags: - Payments summary: Create Payment Session description: >- Create a payment session (merchant-facing). Called by plugins (WooCommerce, Medusa, etc.) to start a BKey-approved payment flow. The merchant authenticates with a mk_live_* / mk_test_* API key. Returns an approvalUrl to redirect the shopper to. requestBody: required: true content: application/json: schema: type: object properties: merchantDomain: type: string minLength: 1 externalOrderId: type: string amount: type: integer minimum: 1 maximum: 5000000 currency: type: string minLength: 3 maxLength: 3 default: USD lineItems: type: array items: type: object properties: title: type: string minLength: 1 quantity: type: integer minimum: 1 price: type: integer minimum: 0 required: - title - quantity - price additionalProperties: false minItems: 1 returnUrl: type: string format: uri notifyUrl: type: string format: uri cancelUrl: type: string format: uri customerEmail: type: string format: email expiresInSecs: type: integer minimum: 60 maximum: 7200 default: 1800 required: - amount - lineItems - returnUrl additionalProperties: false responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean paymentSession: type: object properties: id: type: string status: type: string description: >- One of: pending, awaiting_approval, approved, completed, rejected, failed, expired, refunded approvalUrl: type: string description: URL the shopper visits to approve payment amount: type: integer minimum: 0 currency: type: string minLength: 3 maxLength: 3 merchantName: type: string lineItems: type: array items: type: object properties: title: type: string quantity: type: integer exclusiveMinimum: true minimum: 0 price: type: integer minimum: 0 description: Price in smallest currency unit (e.g., cents) required: - title - quantity - price additionalProperties: false expiresAt: type: string format: date-time merchantDomain: type: string createdAt: type: string format: date-time externalOrderId: type: string nullable: true description: >- Merchant's own order ID — echoed back so the merchant plugin can correlate the BKey session with the shop's order. sptId: type: string nullable: true description: >- Stripe Payment Token ID. Populated after payment succeeds. paymentIntentId: type: string nullable: true description: >- Stripe PaymentIntent ID. Populated after payment succeeds. returnUrl: type: string description: Merchant success redirect URL. cancelUrl: type: string description: Merchant cancel redirect URL. paymentResult: type: object additionalProperties: {} description: >- Raw payment processor result (Stripe-shaped). Present on completed / failed sessions. required: - id - status - approvalUrl - amount - currency - expiresAt additionalProperties: false required: - success - paymentSession additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string description: Stable machine-readable error code message: type: string description: Human-readable error message required: - code - message additionalProperties: false required: - success - error additionalProperties: false '401': description: Missing or invalid merchant API key content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string description: Stable machine-readable error code message: type: string description: Human-readable error message required: - code - message additionalProperties: false required: - success - error additionalProperties: false description: Missing or invalid merchant API key '403': description: Default Response content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string description: Stable machine-readable error code message: type: string description: Human-readable error message required: - code - message additionalProperties: false required: - success - error additionalProperties: false security: - merchantApiKey: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: EdDSA-signed JWT obtained via OAuth 2.1 client_credentials or CIBA merchantApiKey: type: http scheme: bearer bearerFormat: mk_live_XXX or mk_test_XXX description: >- Merchant API key issued during merchant onboarding. Distinct from OAuth JWT. ````