> ## 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. # Submit Received SMS > Submits SMS payloads received on the physical companion device to the server. The server parses the payload using brand-configured regex rules to verify customer transaction payments. Supports batch processing up to 200 messages to prevent visual details from getting lost during connection drops. Enforces maximum length limits (100 bytes for sender, 16384 bytes for body) to block DoS attempts. ## OpenAPI ````yaml /api/mobile_api.yaml post /api/mobile/v1/sms openapi: 3.1.0 info: title: OwnPay Mobile Companion App API description: > The OwnPay Mobile API is exposed exclusively to the paired mobile companion application. It contains endpoints to complete initial device pairing, submit heartbeats to report online statuses, refresh authentication tokens, upload received SMS messages (supporting batch processing up to 200 items), fetch pending outbound SMS queues, acknowledge push notifications, and retrieve dashboard statistics. ### Security and Cryptography - Except for `/api/mobile/v1/devices` (bootstrap pairing) and `/api/mobile/v1/devices/token-refreshes` (token refresh), all endpoints require authentication using a JSON Web Token (JWT) in the HTTP `Authorization` header. ```http Authorization: Bearer ``` - Device fingerprints are checked during token refreshes. - Endpoints are brand-scoped; data visibility is restricted to the specific brand/merchant. version: 1.0.0 servers: - url: https://{brand_domain} description: Master brand domain hosting OwnPay gateway. variables: brand_domain: default: ownpay.org description: The domain of the specific white-labeled gateway. security: - JWTAuth: [] paths: /api/mobile/v1/sms: post: summary: Submit Received SMS description: > Submits SMS payloads received on the physical companion device to the server. The server parses the payload using brand-configured regex rules to verify customer transaction payments. Supports batch processing up to 200 messages to prevent visual details from getting lost during connection drops. Enforces maximum length limits (100 bytes for sender, 16384 bytes for body) to block DoS attempts. operationId: submitSms requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitSmsRequest' responses: '200': description: SMS processed successfully. content: application/json: schema: $ref: '#/components/schemas/SubmitSmsResponse' '400': description: >- Processing failed for a single message payload (e.g. SMS rejected as invalid format). content: application/json: schema: $ref: '#/components/schemas/SmsStatusResponse' '422': description: >- Validation failed (e.g. batch size exceeds 200, sender name too long, or body size exceeds 16KB). content: application/json: schema: $ref: '#/components/schemas/ApiErrorsResponse' components: schemas: SubmitSmsRequest: type: object description: >- Can be a single SMS object payload, a batch array of objects, or a wrapper object containing a messages array. properties: messages: type: array items: $ref: '#/components/schemas/SingleSmsPayload' example: messages: - sender: bKash body: >- You have received Tk 500.00 from 01700000000. Ref INV-10029. Fee Tk 0.00. Balance Tk 15400.00. TrxID A8K9D2J3S local_id: 104 received_at: '2026-06-23 14:17:12' SubmitSmsResponse: type: object properties: success: type: boolean example: true data: type: array items: 852a7acb-9548-4eb6-b1e0-561a30460b78 SmsStatusResponse: type: object properties: success: type: boolean example: true data: type: object properties: status: type: string enum: - accepted - duplicate - rejected example: accepted server_ref: type: string nullable: true description: Transaction reference ID generated on OwnPay server. example: OP-481029304 error: type: string nullable: true example: null ApiErrorsResponse: type: object properties: success: type: boolean example: false error: type: string example: Validation failed errors: type: array items: type: object properties: code: type: string example: VALIDATION_FAILED message: type: string example: sender exceeds 100 bytes field: type: string example: sender request_id: type: string example: 8f5a2e9b0c7d4e5f SingleSmsPayload: type: object required: - sender properties: sender: type: string maxLength: 100 description: The sender address (e.g. bKash, Nagad, or phone number). example: bKash encrypted_payload: type: string maxLength: 16384 description: Base64-encoded encrypted SMS text. Preferred format. example: T3BlblNlY3VyZUV4YW1wbGU... body: type: string maxLength: 16384 description: Plaintext SMS message body. example: >- You have received Tk 500.00 from 01700000000. Ref INV-10029. Fee Tk 0.00. Balance Tk 15400.00. TrxID A8K9D2J3S local_id: type: integer nullable: true description: Local database primary key of the SMS on the mobile app. example: 104 received_at: type: string description: >- ISO-like timestamp representing when the SMS was received on the device. example: '2026-06-23 14:17:12' securitySchemes: JWTAuth: type: http scheme: bearer bearerFormat: JWT description: Enter your Short-lived access JWT token. ```` ## Related topics - [Submit Device Heartbeat](/docs/api-reference/submit-device-heartbeat.md) - [Retry Outbound SMS](/docs/api-reference/retry-outbound-sms.md) - [Update SMS Template](/docs/api-reference/update-sms-template.md) - [List SMS Templates](/docs/api-reference/list-sms-templates.md) - [Get Pending Outbound SMS](/docs/api-reference/get-pending-outbound-sms.md)