{ "openapi": "3.0.0", "info": { "title": "Paymentic Messaging API", "description": "Paymentic REST API for sending SMS messages, checking delivery status and receiving webhook notifications.", "version": "1.2" }, "servers": [ { "url": "https://api.paymentic.com/v1_2", "description": "Production" }, { "url": "https://api.sandbox.paymentic.com/v1_2", "description": "Sandbox" } ], "paths": { "/sms/messaging/single": { "post": { "tags": [ "sms" ], "summary": "Send a single SMS", "description": "Accepts a single SMS for delivery and returns the created message.", "operationId": "send-single-sms", "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "description": "Optional idempotency key. A retry within the 2h window returns the same message without re-charging.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSingleSmsRequest" } } } }, "responses": { "202": { "description": "Message accepted for delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSingleSmsResponse" } } } }, "400": { "description": "Bad request (e.g. no price configured for the destination country)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "Insufficient funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientFunds" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpException" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/sms/messaging/single/{id}": { "get": { "tags": [ "sms" ], "summary": "Fetch a single SMS by ID", "description": "Returns message details and delivery status for the given ID.", "operationId": "show-single-sms", "parameters": [ { "name": "id", "in": "path", "description": "Message ID (the id field from the send response).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagingMessageResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpException" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "SendSingleSmsRequest": { "required": [ "recipient", "text" ], "properties": { "sender": { "description": "Alphanumeric sender ID (max 11 characters). Omitted → client default sender.", "type": "string", "example": "Paymentic", "nullable": true, "maxLength": 11 }, "recipient": { "description": "Recipient number in E.164 format.", "type": "string", "example": "+48123123123" }, "text": { "description": "Message content.", "type": "string", "example": "Your code is 1234." }, "unicode": { "description": "Enforce unicode encoding (UCS-2).", "type": "boolean", "example": false, "nullable": true, "default": false }, "externalReferenceId": { "description": "External identifier for the message. Max 36 characters.", "type": "string", "example": "order-2026-000123", "nullable": true, "maxLength": 36 }, "priority": { "description": "Priority level.", "type": "string", "example": "LOW", "nullable": true, "default": "LOW", "enum": [ "LOW", "MEDIUM", "HIGH" ] } }, "type": "object" }, "MessagingMessage": { "properties": { "id": { "type": "string", "example": "01JZX8K3M9QABCDEF0123456789" }, "status": { "type": "string", "example": "QUEUED", "enum": [ "QUEUED", "SENT", "DELIVERED", "FAILED" ] }, "sender": { "type": "string", "example": "Paymentic", "nullable": true }, "recipient": { "type": "string", "example": "+48123123123" }, "text": { "type": "string", "example": "Your code is 1234." }, "segmentsCount": { "type": "integer", "example": 1 }, "totalCost": { "description": "Total cost as a decimal string with 3 fractional digits.", "type": "string", "format": "decimal", "pattern": "^\\d+\\.\\d{3}$", "example": "0.053" }, "source": { "type": "string", "example": "API", "enum": [ "WEB", "API", "SYSTEM" ] }, "priority": { "type": "string", "example": "LOW", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "externalReferenceId": { "description": "External reference provided by the client when sending.", "type": "string", "example": "order-2026-000123", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "BadRequest": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "PRICE_NOT_CONFIGURED", "message": "No price configured for client [42] and country [PL].", "docsUrl": "https://docs.paymentic.com/errors#PRICE_NOT_CONFIGURED", "details": null } ] } }, "type": "object" }, "ErrorItem": { "required": [ "code", "message", "docsUrl" ], "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Unauthenticated." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#UNAUTHORIZED" }, "details": { "description": "Additional error context (e.g. field validation errors) or null.", "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" }, "InsufficientFunds": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient wallet balance to send the message.", "docsUrl": "https://docs.paymentic.com/errors#INSUFFICIENT_FUNDS", "details": null } ] } }, "type": "object" }, "MethodNotAllowedHttpException": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "METHOD_NOT_ALLOWED", "message": "The GET method is not supported for this route. Supported methods: POST.", "docsUrl": "https://docs.paymentic.com/errors#METHOD_NOT_ALLOWED", "details": null } ] } }, "type": "object" }, "NotFound": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "NOT_FOUND", "message": "Message not found.", "docsUrl": "https://docs.paymentic.com/errors#NOT_FOUND", "details": null } ] } }, "type": "object" }, "Unauthorized": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "UNAUTHORIZED", "message": "Unauthenticated.", "docsUrl": "https://docs.paymentic.com/errors#UNAUTHORIZED", "details": null } ] } }, "type": "object" }, "ValidationError": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" }, "example": [ { "code": "VALIDATION_ERROR", "message": "The selected pointId is invalid.", "docsUrl": "https://docs.paymentic.com/errors#VALIDATION_ERROR", "details": { "field": "pointId", "messages": [ "The selected pointId is invalid." ] } } ] } }, "type": "object" }, "MessagingMessageResponse": { "properties": { "data": { "$ref": "#/components/schemas/MessagingMessage" } }, "type": "object" }, "SendSingleSmsResponse": { "properties": { "data": { "$ref": "#/components/schemas/MessagingMessage" } }, "type": "object" } } }, "tags": [ { "name": "sms", "description": "sms" } ] }