> ## Documentation Index > Fetch the complete documentation index at: https://virtualsms.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Cancel Order > Cancel a pending order and receive a full refund. **2-minute hold:** Orders cannot be cancelled within the first 2 minutes of purchase. This is to prevent abuse. If you try to cancel too early, you'll get a 425 response telling you how many seconds to wait. Cancellation is only possible while the order is in `waiting` status (no SMS received). ## OpenAPI ````yaml POST /api/v1/customer/cancel/{orderId} openapi: 3.1.0 info: title: VirtualSMS API version: 1.1.0 description: > ## VirtualSMS — sms-activate Compatible SMS Verification API Real phone numbers for OTP verification — for signup testing, login flows, and account verification. Free API key, pay-per-use, no contracts. Works with services that reject VoIP. ### Drop-in compatibility for sms-activate-style code ```diff - BASE_URL = "https://[your-old-provider]/stubs/handler_api.php" + BASE_URL = "https://virtualsms.io/stubs/handler_api.php" ``` All action names, response formats, error codes, and parameter names match the widely-used sms-activate API protocol. Your existing `getNumber`, `getStatus`, `setStatus` code requires **zero modification**. ### Two API Styles | Style | Best For | |-------|----------| | **sms-activate Compatibility** (`/stubs/handler_api.php`) | Existing bots, legacy migrations, automation tools | | **Modern REST API** (`/api/v1/`) | New integrations, webhooks, real-time WebSocket | ### Authentication All endpoints require an API key. Generate yours at **Settings -> API Keys**. Keys look like: `vsms_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1` contact: name: VirtualSMS Support url: https://virtualsms.io email: support@virtualsms.io servers: - url: https://virtualsms.io description: Production security: - ApiKeyHeader: [] - ApiKeyQuery: [] tags: - name: sms-activate Compatibility description: > ## sms-activate-Style Legacy Endpoints These endpoints replicate the widely-used sms-activate API format exactly. All responses are **plain text** (not JSON), returned with HTTP 200 even on errors. **Base URL:** `https://virtualsms.io/stubs/handler_api.php` **Usage:** Append `?action=&api_key=` to the base URL. **Error handling:** Check the response body text - errors are strings like `BAD_KEY`, `NO_NUMBERS`. ### Common Error Codes | Code | Meaning | |------|---------| | `BAD_KEY` | Invalid or missing API key | | `NO_NUMBERS` | No stock for service/country | | `NO_MONEY` | Insufficient balance | | `MAX_PRICE_EXCEEDED` | Actual price > max_price param | | `TOO_MANY_ACTIVE_RENTALS` | Hit 20-rental concurrent limit | | `NO_ACTIVATION` | Invalid rental ID | | `BAD_SERVICE` | Unknown service code | | `BAD_COUNTRY` | Unknown country code | - name: Authentication description: > Register, login, and manage your account. After login, use the JWT token as `Authorization: Bearer ` or generate an API key for use with `X-API-Key` header. - name: Numbers description: > Rent phone numbers and wait for SMS verification codes. **Flow:** 1. `POST /api/v1/numbers/rent` -> get rental_id and phone number 2. Poll `GET /api/v1/numbers/:id/status` every 3-5 seconds (or use WebSocket / webhooks) 3. When `status=received`, read `sms_code` 4. `POST /api/v1/numbers/:id/done` to free your slot - name: Services description: Browse available services, countries, and current prices. - name: Webhooks description: > Register a URL to receive instant push notifications when SMS arrives. Much better than polling - no delay, no wasted requests. **Payload example:** ```json { "activationId": 12345, "service": "wa", "code": "438271", "text": "Your WhatsApp code is 438271. Don't share this code.", "country": 187, "receivedAt": "2026-03-03 14:22:11" } ``` **Retry policy:** Up to 8 retries, 15-second intervals, 3-second timeout per attempt. **HMAC signature:** If you set a `secret`, each request includes `X-VirtualSMS-Signature: sha256=`. - name: Customer API description: > ## Modern Customer API Clean REST endpoints for purchasing SMS verification numbers. All endpoints use **X-API-Key** header authentication. **Base URL:** `https://virtualsms.io/api/v1/` **Numbers:** By default, only **physical SIM card numbers** are returned (no VoIP). Add `include_voip=true` to include VoIP numbers where available. **Order flow:** 1. `GET /api/v1/customer/balance` - Check your balance 2. `GET /api/v1/customer/services` - Find available services 3. `GET /api/v1/customer/countries?service=tg` - Find countries for a service 4. `GET /api/v1/price?service=tg&country=ID` - Check price 5. `POST /api/v1/customer/purchase` - Buy a number 6. `GET /api/v1/customer/order/{orderId}` - Poll for SMS (or use WebSocket) 7. `POST /api/v1/customer/cancel/{orderId}` - Cancel if needed (after 2-minute hold) 8. `POST /api/v1/customer/swap/{orderId}` - Swap for a different number (after 2-minute hold) - name: WebSocket description: | Connect via WebSocket for real-time SMS delivery - no polling required. **Endpoint:** `wss://virtualsms.io/ws/orders` **Message types:** - `sms` - SMS received with verification code - `expired` - Rental time window expired paths: /api/v1/customer/cancel/{orderId}: post: tags: - Customer API summary: Cancel an order description: > Cancel a pending order and receive a full refund. **2-minute hold:** Orders cannot be cancelled within the first 2 minutes of purchase. This is to prevent abuse. If you try to cancel too early, you'll get a 425 response telling you how many seconds to wait. Cancellation is only possible while the order is in `waiting` status (no SMS received). operationId: customer_cancel parameters: - name: orderId in: path required: true schema: type: string format: uuid description: Order ID to cancel example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: Order cancelled and refunded content: application/json: schema: type: object properties: success: type: boolean example: true order_id: type: string format: uuid status: type: string example: cancelled refund_amount: type: number format: float example: 0.4 example: success: true order_id: 550e8400-e29b-41d4-a716-446655440000 status: cancelled refund_amount: 0.4 '401': description: Invalid or missing API key '404': description: Order not found '425': description: Too early to cancel - 2-minute hold period active content: application/json: schema: type: object properties: error: type: string example: >- Cannot cancel within 2 minutes of purchase. Please wait 82 seconds. seconds_remaining: type: integer example: 82 example: error: >- Cannot cancel within 2 minutes of purchase. Please wait 82 seconds. seconds_remaining: 82 security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyHeader: type: apiKey in: header name: X-API-Key description: API key in request header. Use for Modern REST API endpoints. ApiKeyQuery: type: apiKey in: query name: api_key description: >- API key as query parameter. Use for sms-activate compatibility endpoints. ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- API key from virtualsms.io dashboard (Settings -> API tab). Prefix: vsms_ ````