> ## Documentation Index > Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees. > Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown. > OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis. > MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries. > Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix. > Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests. # Initiate Payment Intent > Initiates a new payment session by creating a payment intent. Returns a secure, white-labeled checkout URL where customers can choose from the brand's active payment methods (such as Mobile Financial Services (MFS) e.g., bKash, Nagad, Rocket). Validates callback URLs against transport safety regulations, truncates customer PII properties to fit database constraints, and resolves/creates customer profile bindings. ## OpenAPI ````yaml /api/merchant_api.yaml post /payments openapi: 3.1.0 info: title: OwnPay Merchant API description: > The OwnPay Merchant API enables merchants to programmatically interface with their white-labeled payment gateway. It exposes endpoints to initiate payments (creating payment intents), query transaction statuses, issue full or partial refunds, manage customer profiles securely in compliance with GDPR and OWASP, generate and revoke API keys, and test/audit webhook delivery attempts. ### Authentication Authentication is performed via HTTP Bearer token in the `Authorization` header. ```http Authorization: Bearer your_api_key_here ``` API keys carry specific privilege scopes (e.g., `read`, `write`, `admin`). Some administrative operations (like listing/generating API keys) require **both** `write` and `admin` scopes, as well as passing a valid platform super-administrator's email address in the `X-Super-Admin-Email` header for safety. version: 1.0.0 servers: - url: https://{brand_domain}/api/v1 description: Sandbox or Production white-labeled brand gateway API server. variables: brand_domain: default: ownpay.org description: The custom domain configured for your white-labeled brand. security: - BearerAuth: [] paths: /payments: post: summary: Initiate Payment Intent description: > Initiates a new payment session by creating a payment intent. Returns a secure, white-labeled checkout URL where customers can choose from the brand's active payment methods (such as Mobile Financial Services (MFS) e.g., bKash, Nagad, Rocket). Validates callback URLs against transport safety regulations, truncates customer PII properties to fit database constraints, and resolves/creates customer profile bindings. operationId: initiatePayment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiatePaymentRequest' responses: '201': description: Payment session initiated successfully. content: application/json: schema: $ref: '#/components/schemas/InitiatePaymentResponse' '422': description: >- Validation failed (e.g. invalid amount format, unsupported currency, or invalid URL schemes). content: application/json: schema: $ref: '#/components/schemas/ApiErrorsResponse' '500': description: Payment processing/initiation failed on the server. content: application/json: schema: $ref: '#/components/schemas/ApiSingleErrorResponse' components: schemas: InitiatePaymentRequest: type: object required: - amount - currency properties: amount: type: string description: >- Positive numeric string representing the transaction volume (2 decimal places). example: '500.00' currency: type: string description: >- 3-letter ISO currency code. Must be registered and supported by the platform (e.g. BDT, USD). example: BDT callback_url: type: string format: uri description: >- Webhook payload URL where transaction completion callbacks are POSTed. Must use HTTP or HTTPS. example: https://my-store.com/webhooks/ownpay redirect_url: type: string format: uri description: >- Redirection target URL where the user is returned after a successful checkout session. example: https://my-store.com/checkout/success cancel_url: type: string format: uri description: >- Redirection target URL where the user is returned if they cancel the payment session. example: https://my-store.com/checkout/cancel customer_email: type: string format: email description: Customer email address. Used for identity verification and mapping. example: customer@example.com customer_name: type: string description: Customer full name (max 150 characters). example: John Doe customer_phone: type: string description: Customer phone number (max 30 characters). example: '+8801700000000' reference: type: string description: Internal order reference or invoice identifier. example: INV-10029 gateway: type: string description: Request routing through a specific payment gateway slug (optional). example: bkash-merchant metadata: type: object description: Key-value map for merchant custom details. example: store_id: dhaka-branch item_categories: - electronics - peripherals InitiatePaymentResponse: type: object properties: success: type: boolean example: true data: type: object properties: payment_id: type: string format: uuid description: Unique UUID identifier of the generated payment intent. example: a810b445-564a-4e20-80a5-f1261d7b328a token: type: string description: Short-lived payment checkout token string. example: tok_4821a8f902bd3f46 checkout_url: type: string format: uri description: >- Secure white-labeled URL redirection target to launch the user payment screen. example: https://ownpay.org/checkout/tok_4821a8f902bd3f46 status: type: string example: created ApiErrorsResponse: type: object properties: success: type: boolean example: false error: type: string example: amount must be a positive number errors: type: array items: type: object properties: code: type: string example: INVALID_AMOUNT message: type: string example: amount must be a positive number field: type: string example: amount request_id: type: string example: 8f5a2e9b0c7d4e5f ApiSingleErrorResponse: type: object properties: success: type: boolean example: false error: type: string example: Payment not found errors: type: array items: type: object properties: code: type: string example: PAYMENT_NOT_FOUND message: type: string example: Payment not found field: type: string nullable: true example: null request_id: type: string example: 8f5a2e9b0c7d4e5f securitySchemes: BearerAuth: type: http scheme: bearer description: Provide the Bearer API Key generated for your brand. ```` ## Related topics - [Retrieve Payment Details](/docs/api-reference/retrieve-payment-details.md) - [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md) - [OwnPay API Overview - REST API for Multi-Brand Payments](/docs/api/overview.md) - [Node.js SDK - TypeScript-First Payment Integration](/docs/developer/integration/nodejs.md) - [Dispatch Test Webhook](/docs/api-reference/dispatch-test-webhook.md)