{ "openapi": "3.1.0", "info": { "title": "eSIMDual Reseller API", "version": "1.2.0", "description": "One contract, two isolated environments. Production uses the real reseller wallet and upstream supplier APIs. Sandbox uses a fictitious 1,000-unit balance, simulated eSIMs and never calls an upstream supplier.\n\nThe catalogue contains only packages publicly saleable by eSIMDual's hybrid routing. Compatible recharge packages are resolved per owned eSIM.\n\nAutomatic cancellation and wallet refund are limited to supplier-confirmed unused, uninstalled and unactivated eSIMs with no completed recharge and a verified original wallet debit. Consumed or installed eSIMs are never refunded pro rata. Ambiguous cases go to manual review without wallet credit.\n\nWebhook signing secrets are generated by eSIMDual and displayed only after webhook creation or secret rotation. Do not log Bearer tokens, QR/LPA activation values or webhook secrets." }, "servers": [ { "url": "https://esimdual.com/api/reseller/v1", "description": "Production — real wallet and supplier orders" }, { "url": "https://esimdual.com/api/reseller/v1/sandbox", "description": "Sandbox — simulated, no real debit or supplier call" } ], "tags": [ { "name": "System" }, { "name": "Authentication" }, { "name": "Catalog" }, { "name": "Orders" }, { "name": "eSIMs" }, { "name": "Recharges" }, { "name": "Cancellations" }, { "name": "Wallet" }, { "name": "Sandbox" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum" } }, "schemas": { "Error": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string" }, "errors": { "type": "object", "nullable": true, "additionalProperties": true } } }, "Pagination": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 125 }, "last_page": { "type": "integer", "example": 5 } } }, "Money": { "type": "object", "required": [ "currency", "price" ], "properties": { "currency": { "type": "string", "example": "USD" }, "price": { "type": "number", "format": "double", "example": 4.5 } } }, "Package": { "type": "object", "required": [ "id", "name", "package_type", "data_volume", "pricing" ], "properties": { "id": { "type": "integer", "example": 1120 }, "name": { "type": "string", "example": "France 1 GB - 30 days" }, "slug": { "type": "string" }, "package_type": { "type": "string", "enum": [ "DATA", "DATA-VOICE-SMS" ] }, "data_quantity": { "type": "number", "example": 1 }, "data_unit": { "type": "string", "example": "GB" }, "data_volume": { "type": "integer", "format": "int64", "example": 1073741824, "description": "Bytes. A negative value is retained for legacy unlimited plans; also inspect data_unlimited." }, "data_unlimited": { "type": "boolean" }, "voice_quantity": { "type": "integer", "example": 0 }, "voice_unlimited": { "type": "boolean" }, "sms_quantity": { "type": "integer", "example": 0 }, "sms_unlimited": { "type": "boolean" }, "package_validity": { "type": "integer", "example": 30 }, "package_validity_unit": { "type": "string", "example": "Day" }, "reloadable": { "type": "boolean", "example": true, "description": "Catalogue hint only. GET /esims/{id}/topup-options is authoritative for a specific owned eSIM." }, "requires_imei": { "type": "boolean", "description": "When true, device_imei is required for the initial purchase." }, "area_coverage": { "type": "string", "enum": [ "local", "continental", "global" ] }, "countries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string", "example": "fr" }, "slug": { "type": "string", "nullable": true } } } }, "pricing": { "$ref": "#/components/schemas/Money" } } }, "Esim": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "serial_number": { "type": "string", "nullable": true }, "iccid": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "qr_code": { "type": "string", "nullable": true, "description": "Sensitive LPA activation value. Do not log it." }, "qr_code_image": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "expiry_date": { "type": "string", "format": "date", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "installed_at": { "type": "string", "format": "date-time", "nullable": true }, "provider_expiry_at": { "type": "string", "format": "date-time", "nullable": true }, "package": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer" }, "external_order_id": { "type": "string", "nullable": true }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "operation_type": { "type": "string", "enum": [ "purchase", "topup", "cancellation" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "rejected" ] }, "currency": { "type": "string" }, "price": { "type": "number", "format": "double" }, "refund_status": { "type": "string", "nullable": true }, "refunded_amount": { "type": "number", "format": "double" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "package": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "esim": { "$ref": "#/components/schemas/Esim" } } }, "TopupOption": { "type": "object", "properties": { "package_id": { "type": "integer" }, "name": { "type": "string" }, "data_volume": { "type": "integer", "format": "int64" }, "validity_days": { "type": "integer" }, "pricing": { "$ref": "#/components/schemas/Money" }, "requires_period_num": { "type": "boolean" }, "period_num_min": { "type": "integer", "nullable": true }, "period_num_max": { "type": "integer", "nullable": true } } }, "Refund": { "type": "object", "properties": { "id": { "type": "integer" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "rejected", "manual_review" ] }, "amount": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "esim_id": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "paths": { "/capabilities": { "get": { "tags": [ "System" ], "summary": "Discover supported capabilities", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "additionalProperties": true } } } } } } } } }, "/login": { "post": { "tags": [ "Authentication" ], "summary": "Create an environment-scoped API token", "security": [], "description": "Production login requires an approved reseller. Sandbox login accepts an active, email-verified pending or approved reseller.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "device_name": { "type": "string", "maxLength": 255 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Optional token lifetime. Omit for a non-expiring legacy-compatible token." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "user": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/logout": { "post": { "tags": [ "Authentication" ], "summary": "Revoke the current token", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "nullable": true } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "tags": [ "Authentication" ], "summary": "Get the current reseller and environment balance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/packages": { "get": { "tags": [ "Catalog" ], "summary": "List public packages selected by eSIMDual hybrid routing", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "country_slug", "in": "query", "schema": { "type": "string" } }, { "name": "region_slug", "in": "query", "schema": { "type": "string" } }, { "name": "package_type", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/packages/{id}": { "get": { "tags": [ "Catalog" ], "summary": "Get one public package", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Package" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pricing": { "get": { "tags": [ "Catalog" ], "summary": "Legacy country-grouped pricing view", "security": [ { "bearerAuth": [] } ], "description": "Kept for compatibility. New integrations should use the paginated /packages endpoint.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List reseller operations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "operation_type", "in": "query", "schema": { "type": "string", "enum": [ "purchase", "topup", "cancellation" ] } }, { "name": "external_order_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Orders" ], "summary": "Purchase a new eSIM", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Stable unique key for safe retries. Reuse the same key only for the same operation." } ], "description": "Idempotency-Key is required. device_imei is required only when the selected package declares requires_imei=true.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "package_id" ], "properties": { "package_id": { "type": "integer" }, "external_order_id": { "type": "string", "maxLength": 255 }, "device_imei": { "type": "string", "pattern": "^[0-9]{14,16}$" } } } } } }, "responses": { "201": { "description": "Created or safely replayed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Idempotent replay of the original purchase", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency-Key already used with a different request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Supplier response unknown; wallet not debited and operation retained for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get one reseller operation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims": { "get": { "tags": [ "eSIMs" ], "summary": "List owned eSIMs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Esim" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims/{id}": { "get": { "tags": [ "eSIMs" ], "summary": "Get an owned eSIM and activation data", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Esim" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims/{id}/usage": { "get": { "tags": [ "eSIMs" ], "summary": "Get live or simulated usage", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "properties": { "remaining_bytes": { "type": "integer", "format": "int64" }, "used_bytes": { "type": "integer", "format": "int64" }, "total_bytes": { "type": "integer", "format": "int64" }, "status": { "type": "string", "nullable": true } } } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Usage is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims/{id}/topup-options": { "get": { "tags": [ "Recharges" ], "summary": "Resolve compatible recharge packages for one owned eSIM", "security": [ { "bearerAuth": [] } ], "description": "Production performs an authoritative supplier compatibility check. Sandbox returns deterministic compatible test options without a supplier call.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "properties": { "reload_available": { "type": "boolean" }, "provider_check_failed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/TopupOption" } } } } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/topups": { "post": { "tags": [ "Recharges" ], "summary": "Recharge an owned eSIM", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Stable unique key for safe retries. Reuse the same key only for the same operation." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "esim_id", "package_id" ], "properties": { "esim_id": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "package_id": { "type": "integer" }, "period_num": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Required only when the selected option says requires_period_num=true." }, "external_order_id": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "201": { "description": "Recharge completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Order" } } } } } }, "200": { "description": "Idempotent replay of the original recharge", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM or package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency-Key already used with a different request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Supplier response unknown; wallet not debited and operation retained for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims/{id}/cancel": { "post": { "tags": [ "Cancellations" ], "summary": "Cancel an unused eSIM and refund the reseller wallet when eligible", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "format": "uuid" } ] }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Stable unique key for safe retries. Reuse the same key only for the same operation." } ], "description": "Production is automatic only for upstream profiles that support cancellation and are confirmed as zero-usage, never installed and never activated, with no completed recharge and a verified original wallet debit. Unsupported suppliers and ambiguous cases require manual review. No pro-rata refunds are issued. Sandbox reproduces accepted, rejected and manual-review outcomes based on simulated state.", "responses": { "201": { "description": "Cancelled and refunded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Refund" } } } } } }, "200": { "description": "Idempotent replay of the original cancellation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Pending or manual review", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Refund" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not refundable or Idempotency-Key already used with a different request payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Refund" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/refunds": { "get": { "tags": [ "Cancellations" ], "summary": "List cancellation/refund records", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/refunds/{id}": { "get": { "tags": [ "Cancellations" ], "summary": "Get one refund record", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Numeric ID in production; UUID in sandbox for eSIM resources." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Refund" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refund not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/wallet": { "get": { "tags": [ "Wallet" ], "summary": "Get the current environment wallet and recent transactions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "balance": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "transactions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/esims/{id}/simulate": { "post": { "tags": [ "Sandbox" ], "summary": "Sandbox only: simulate installation, activation or usage", "servers": [ { "url": "https://esimdual.com/api/reseller/v1/sandbox", "description": "Sandbox only" } ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sandbox eSIM UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "used_bytes": { "type": "integer", "minimum": 0 }, "installed": { "type": "boolean" }, "activated": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ready", "installed", "active", "exhausted", "expired" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "$ref": "#/components/schemas/Esim" } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "eSIM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reset": { "post": { "tags": [ "Sandbox" ], "summary": "Sandbox only: delete test state and restore the fictitious balance", "servers": [ { "url": "https://esimdual.com/api/reseller/v1/sandbox", "description": "Sandbox only" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "enum": [ true ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account, approval, IP allow-list or token environment denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "resellerEvent": { "post": { "summary": "Signed reseller event delivery", "description": "Events: ping, order.completed, order.processing, order.failed, topup.completed, topup.processing, topup.failed, esim.cancelled, refund.completed, refund.failed. Signature input is `${X-eSIMDual-Timestamp}.${rawBody}` and the header is `X-eSIMDual-Signature: v1=`. Reject stale timestamps (recommended: over 5 minutes) and deduplicate X-eSIMDual-Delivery. eSIMDual retries retryable failures up to three times.", "parameters": [ { "name": "X-eSIMDual-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-eSIMDual-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-eSIMDual-Timestamp", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "X-eSIMDual-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "occurred_at", "environment" ], "properties": { "event": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "order": { "$ref": "#/components/schemas/Order" }, "package": { "$ref": "#/components/schemas/Package" }, "esim": { "$ref": "#/components/schemas/Esim" } } } } } }, "responses": { "200": { "description": "Acknowledge delivery with any 2xx response" } } } } } }