{
    "openapi": "3.1.0",
    "info": {
        "title": "Paymentic DirectBilling API",
        "description": "Paymentic REST API for accepting direct carrier billing payments. Create transactions, check their status and receive webhook notifications.",
        "version": "1.2"
    },
    "servers": [
        {
            "url": "https://api.paymentic.com/v1_2"
        },
        {
            "url": "https://api.sandbox.paymentic.com/v1_2"
        }
    ],
    "paths": {
        "/directbilling/points/{pointId}/transactions": {
            "post": {
                "tags": [
                    "Transactions"
                ],
                "summary": "Create direct billing transaction",
                "description": "Creates a direct billing transaction and returns a redirect URL for the payer.",
                "operationId": "create-directbilling-transaction",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/pointId"
                    }
                ],
                "requestBody": {
                    "description": "Create direct billing transaction",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateTransactionRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/CreateTransactionResource"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "anyOf": [
                                        {
                                            "$ref": "#/components/schemas/PointNotActiveExceptionSchema"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "anyOf": [
                                        {
                                            "$ref": "#/components/schemas/PointNotFoundExceptionSchema"
                                        },
                                        {
                                            "$ref": "#/components/schemas/NotFoundHttpExceptionSchema"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method Not Allowed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema"
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "Unsupported Media Type",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UnsupportedMediaTypeHttpExceptionSchema"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Unprocessable Entity",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationExceptionSchema"
                                }
                            }
                        }
                    }
                },
                "x-priority": 10
            }
        },
        "/directbilling/points/{pointId}/transactions/{transactionId}": {
            "get": {
                "tags": [
                    "Transactions"
                ],
                "summary": "Get transaction details",
                "operationId": "get-transaction-details",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/pointId"
                    },
                    {
                        "$ref": "#/components/parameters/transactionId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/GetTransactionDetailsResource"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "anyOf": [
                                        {
                                            "$ref": "#/components/schemas/PointNotFoundExceptionSchema"
                                        },
                                        {
                                            "$ref": "#/components/schemas/TransactionNotFoundExceptionSchema"
                                        },
                                        {
                                            "$ref": "#/components/schemas/NotFoundHttpExceptionSchema"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method Not Allowed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Unprocessable Entity",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValidationExceptionSchema"
                                }
                            }
                        }
                    }
                },
                "x-priority": 20
            }
        },
        "/directbilling/ping": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Ping the API",
                "operationId": "ping",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "example": "pong"
                                                },
                                                "environment": {
                                                    "type": "string",
                                                    "example": "sandbox",
                                                    "enum": [
                                                        "production",
                                                        "sandbox"
                                                    ]
                                                },
                                                "tokenId": {
                                                    "type": "string",
                                                    "example": "2a77157f-7a73-413d-90a1-cd1263533d61"
                                                },
                                                "clientId": {
                                                    "type": "string",
                                                    "example": "72b631fe"
                                                },
                                                "version": {
                                                    "type": "string",
                                                    "example": "1.2"
                                                },
                                                "scopes": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    },
                                                    "example": [
                                                        "*"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method Not Allowed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema"
                                }
                            }
                        }
                    }
                },
                "x-priority": 100
            }
        }
    },
    "components": {
        "schemas": {
            "CreateTransactionRequest": {
                "required": [
                    "amount",
                    "title"
                ],
                "properties": {
                    "amount": {
                        "description": "Amount in PLN with up to 2 decimals, from 1.00 to 200.00 and not above the maximum amount of the point.",
                        "type": "string",
                        "format": "decimal",
                        "example": "12.30"
                    },
                    "title": {
                        "type": "string",
                        "example": "Order #12345",
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 128
                    },
                    "externalReferenceId": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 64
                    },
                    "msisdn": {
                        "description": "Payer phone number in E.164 format (Polish numbers only).",
                        "type": [
                            "string",
                            "null"
                        ],
                        "pattern": "^\\+48\\d{9}$",
                        "example": "+48123456789"
                    },
                    "redirect": {
                        "properties": {
                            "success": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "uri",
                                "maxLength": 255
                            },
                            "failure": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "uri",
                                "maxLength": 255
                            }
                        },
                        "type": [
                            "object",
                            "null"
                        ]
                    }
                },
                "type": "object"
            },
            "CreateTransactionResource": {
                "properties": {
                    "id": {
                        "description": "Transaction ID",
                        "type": "string",
                        "example": "ABC-123-XYZ-9876"
                    },
                    "redirectUrl": {
                        "description": "Transaction URL",
                        "type": "string",
                        "format": "url",
                        "example": "https://directbilling.paymentic.com/?transactionId=ABC-123-XYZ-9876&token=..."
                    }
                },
                "type": "object"
            },
            "GetTransactionDetailsResource": {
                "properties": {
                    "id": {
                        "$ref": "#/components/schemas/TransactionIdSchema",
                        "description": "Transaction ID"
                    },
                    "status": {
                        "$ref": "#/components/schemas/TransactionStatusSchema"
                    },
                    "amount": {
                        "description": "Transaction amount as a string-encoded decimal",
                        "type": "string",
                        "example": "12.30"
                    },
                    "currency": {
                        "description": "ISO 4217 currency code",
                        "type": "string",
                        "example": "PLN"
                    },
                    "commission": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "0.50"
                    },
                    "title": {
                        "type": "string",
                        "example": "Order #12345"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "externalReferenceId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "msisdn": {
                        "description": "Payer phone number in E.164 format.",
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "+48123456789"
                    },
                    "mccmnc": {
                        "description": "MCC and MNC of the mobile network operator that charged the payer.",
                        "type": [
                            "integer",
                            "null"
                        ],
                        "example": 26001
                    },
                    "redirect": {
                        "properties": {
                            "success": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "uri"
                            },
                            "failure": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "uri"
                            }
                        },
                        "type": "object"
                    },
                    "paidAt": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "createdAt": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "expiresAt": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "MethodNotAllowedHttpExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "METHOD_NOT_ALLOWED"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "Method not allowed for "
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#METHOD_NOT_ALLOWED"
                                },
                                "details": {
                                    "properties": {
                                        "allowedMethods": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "example": "GET"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "NotFoundHttpExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "PATH_NOT_FOUND"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "The path / could not be found"
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#PATH_NOT_FOUND"
                                },
                                "details": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "example": null
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "PointNotActiveExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "POINT_NOT_ACTIVE"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "This point is not active."
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#POINT_NOT_ACTIVE"
                                },
                                "details": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "example": null
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "PointNotFoundExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "POINT_NOT_FOUND"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "Point not found."
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#POINT_NOT_FOUND"
                                },
                                "details": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "example": null
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "TransactionNotFoundExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "TRANSACTION_NOT_FOUND"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "Transaction not found."
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#TRANSACTION_NOT_FOUND"
                                },
                                "details": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "example": null
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "UnsupportedMediaTypeHttpExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "UNSUPPORTED_MEDIA_TYPE"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "The multipart/form-data content type is not supported for this route. Supported content types: application/json."
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#UNSUPPORTED_MEDIA_TYPE"
                                },
                                "details": {
                                    "properties": {
                                        "supportedContentTypes": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "example": "application/json"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "ValidationExceptionSchema": {
                "properties": {
                    "errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "code": {
                                    "type": "string",
                                    "example": "VALIDATION_ERROR"
                                },
                                "message": {
                                    "type": "string",
                                    "example": "The selected pointId is invalid."
                                },
                                "docsUrl": {
                                    "type": "string",
                                    "example": "https://docs.paymentic.com/errors#VALIDATION_ERROR"
                                },
                                "details": {
                                    "properties": {
                                        "field": {
                                            "type": "string",
                                            "example": "pointId"
                                        },
                                        "messages": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "example": "The selected pointId is invalid."
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "PointIdSchema": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}$",
                "example": "b8e6e2fc"
            },
            "TransactionIdSchema": {
                "type": "string",
                "pattern": "^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{4}$",
                "example": "ABC-AB2-AB3-ABC4",
                "maxLength": 16,
                "minLength": 16
            },
            "TransactionStatusSchema": {
                "type": "string",
                "enum": [
                    "CREATED",
                    "PENDING",
                    "PAID",
                    "FAILED",
                    "CANCELLED",
                    "EXPIRED",
                    "REFUNDED",
                    "CHARGEBACK"
                ]
            }
        },
        "parameters": {
            "pointId": {
                "name": "pointId",
                "in": "path",
                "description": "Point ID",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/PointIdSchema"
                }
            },
            "transactionId": {
                "name": "transactionId",
                "in": "path",
                "description": "Transaction ID",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/TransactionIdSchema"
                }
            },
            "Content-Type": {
                "name": "Content-Type",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "application/json"
                }
            },
            "X-Paymentic-Event": {
                "name": "X-Paymentic-Event",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "enum": [
                        "DIRECTBILLING.TRANSACTION_STATUS_CHANGED"
                    ]
                }
            },
            "X-Paymentic-Notification-Id": {
                "name": "X-Paymentic-Notification-Id",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "ulid",
                    "example": "01j96yn02bhbv8j1jjtk36zn2t"
                }
            },
            "X-Paymentic-Signature": {
                "name": "X-Paymentic-Signature",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "5Fil+PpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ=="
                }
            },
            "X-Paymentic-Time": {
                "name": "X-Paymentic-Time",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2025-01-01T12:00:00+00:00"
                }
            },
            "User-Agent": {
                "name": "User-Agent",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "Paymentic/1.2"
                }
            }
        },
        "securitySchemes": {
            "bearerToken": {
                "type": "apiKey",
                "name": "Authorization",
                "in": "header"
            }
        }
    },
    "tags": [
        {
            "name": "Transactions",
            "description": "Create direct billing transactions and check their status."
        },
        {
            "name": "System",
            "description": "Health check and diagnostics."
        },
        {
            "name": "Webhooks",
            "description": "Webhooks"
        }
    ],
    "webhooks": {
        "DIRECTBILLING.TRANSACTION_STATUS_CHANGED": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "summary": "Transaction status changed",
                "operationId": "webhook-directbilling-transaction-status-changed",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/User-Agent"
                    },
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/X-Paymentic-Event"
                    },
                    {
                        "$ref": "#/components/parameters/X-Paymentic-Notification-Id"
                    },
                    {
                        "$ref": "#/components/parameters/X-Paymentic-Time"
                    },
                    {
                        "$ref": "#/components/parameters/X-Paymentic-Signature"
                    }
                ],
                "requestBody": {
                    "description": "Direct billing transaction status changed",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "transactionId": {
                                        "$ref": "#/components/schemas/TransactionIdSchema"
                                    },
                                    "pointId": {
                                        "$ref": "#/components/schemas/PointIdSchema"
                                    },
                                    "status": {
                                        "$ref": "#/components/schemas/TransactionStatusSchema"
                                    },
                                    "amount": {
                                        "type": "string",
                                        "format": "decimal",
                                        "example": "123.45"
                                    },
                                    "currency": {
                                        "type": "string",
                                        "format": "ISO-4217",
                                        "example": "PLN",
                                        "maxLength": 3,
                                        "minLength": 3
                                    },
                                    "commission": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "decimal",
                                        "example": "12.34"
                                    },
                                    "externalReferenceId": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "maxLength": 64
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string",
                                    "example": "OK"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}