{ "openapi": "3.1.0", "info": { "title": "SMS Notification API", "version": "0.1.0", "description": "Send SMS notifications and manage templates, contacts, lists, balance, and delivery history for IZI Pay merchant accounts." }, "servers": [ { "url": "https://sms.izipay.ao", "description": "Production" }, { "url": "https://sms-sandbox.izipay.ao", "description": "Sandbox" } ], "tags": [ { "name": "Authentication", "description": "Register users, verify email addresses, issue tokens, recover access, and read the signed-in user profile." }, { "name": "MFA", "description": "Add or remove multi-factor authentication for a signed-in user." }, { "name": "Merchant Access", "description": "Manage which users can access a merchant account." }, { "name": "Billing", "description": "View merchant subscription, invoice, and usage information." }, { "name": "Payments", "description": "Create, list, sync, and cancel payment operations." }, { "name": "PPR References", "description": "Create and manage PPR payment references." }, { "name": "Terminal Operations", "description": "Open, close, and inspect GPO terminal status." }, { "name": "SMS Account", "description": "Read the signed-in SMS user and merchant sender configuration." }, { "name": "SMS Balance", "description": "View SMS balance and balance ledger history for the merchant account." }, { "name": "SMS Templates", "description": "Create and manage reusable SMS message templates." }, { "name": "SMS Contacts", "description": "Manage SMS contacts and contact lists for bulk sends." }, { "name": "SMS Sending", "description": "Send SMS messages and inspect sent message history." }, { "name": "Scheduled SMS", "description": "Schedule SMS messages and list pending or historical scheduled sends." } ], "paths": { "/api/Empresa/ObterUtilizadorLogado": { "get": { "tags": [ "SMS Account" ], "summary": "Get logged SMS user", "description": "Method and route: `GET /api/Empresa/ObterUtilizadorLogado`. Returns the Identity user mapped to the current SMS merchant context. Use it to confirm which merchant and user are represented by the bearer token.", "operationId": "getSmsLoggedUser", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Logged user details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsLoggedUser" }, "example": { "userId": "11111111-1111-1111-1111-111111111111", "merchantId": "BB1376D9-03D3-45C6-82FA-61F4270D27B6", "email": "merchant@example.com", "name": "Jane Merchant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Empresa/ObterDadosDaEmpresa": { "get": { "tags": [ "SMS Account" ], "summary": "Get merchant SMS sender", "description": "Method and route: `GET /api/Empresa/ObterDadosDaEmpresa`. Returns merchant information and the sender name configured for SMS sends. Use it before sending messages when your app needs to display or validate the sender shown to recipients.", "operationId": "getSmsMerchantData", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Merchant SMS sender details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsMerchant" }, "example": { "merchantId": "BB1376D9-03D3-45C6-82FA-61F4270D27B6", "nome": "IZI Merchant", "remetenteSms": "IZIPAY" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Saldo/ObterSaldo": { "get": { "tags": [ "SMS Balance" ], "summary": "Get SMS balance", "description": "Method and route: `GET /api/Saldo/ObterSaldo`. Returns the current SMS balance for the authenticated merchant. This endpoint is read-only and does not add or adjust balance.", "operationId": "getSmsBalance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current SMS balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsBalance" }, "example": { "merchantId": "BB1376D9-03D3-45C6-82FA-61F4270D27B6", "saldoAtual": 250, "unidade": "sms", "atualizadoEm": "2026-06-14T10:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/HistoricoSaldo/ObterHistoricoSaldo": { "get": { "tags": [ "SMS Balance" ], "summary": "Get SMS balance history", "description": "Method and route: `GET /api/HistoricoSaldo/ObterHistoricoSaldo`. Returns ledger entries that changed or consumed the merchant SMS balance. Use it for reconciliation and account activity screens.", "operationId": "getSmsBalanceHistory", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SMS balance ledger entries.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmsBalanceLedgerEntry" } }, "example": [ { "id": 1001, "tipo": "Debito", "quantidade": 1, "saldoDepois": 249, "descricao": "SMS sent", "criadoEm": "2026-06-14T10:30:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/TemplatesSMS/CriarTemplate": { "post": { "tags": [ "SMS Templates" ], "summary": "Create SMS template", "description": "Method and route: `POST /api/TemplatesSMS/CriarTemplate`. Creates a reusable SMS template for the authenticated merchant. Use templates for messages that will be sent repeatedly with the same wording.", "operationId": "createSmsTemplate", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateRequest" }, "example": { "nome": "Verification code", "conteudo": "Ola {{customerName}}, o seu codigo e 1234." } } } }, "responses": { "200": { "description": "Template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" }, "example": { "id": 42, "nome": "Verification code", "conteudo": "Ola {{customerName}}, o seu codigo e 1234.", "criadoEm": "2026-06-14T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/TemplatesSMS/ListarTemplatesSms": { "get": { "tags": [ "SMS Templates" ], "summary": "List SMS templates", "description": "Method and route: `GET /api/TemplatesSMS/ListarTemplatesSms`. Returns SMS templates created by the authenticated merchant.", "operationId": "listSmsTemplates", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SMS templates.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmsTemplate" } }, "example": [ { "id": 42, "nome": "Verification code", "conteudo": "Ola {{customerName}}, o seu codigo e 1234.", "criadoEm": "2026-06-14T10:30:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/TemplatesSMS/ObterTemplatesSmsPorId/{templateId}": { "get": { "tags": [ "SMS Templates" ], "summary": "Get SMS template by ID", "description": "Method and route: `GET /api/TemplatesSMS/ObterTemplatesSmsPorId/{templateId}`. Retrieves one SMS template by its identifier.", "operationId": "getSmsTemplateById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsTemplateId" } ], "responses": { "200": { "description": "SMS template details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" }, "example": { "id": 42, "nome": "Verification code", "conteudo": "Ola {{customerName}}, o seu codigo e 1234." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/TemplatesSMS/pesquisarTemplateSMSporData": { "get": { "tags": [ "SMS Templates" ], "summary": "Search SMS templates by date", "description": "Method and route: `GET /api/TemplatesSMS/pesquisarTemplateSMSporData`. Finds SMS templates created on a specific day, month, and year.", "operationId": "searchSmsTemplatesByDate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Day" }, { "$ref": "#/components/parameters/Month" }, { "$ref": "#/components/parameters/Year" } ], "responses": { "200": { "description": "Matching SMS templates.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmsTemplate" } }, "example": [ { "id": 42, "nome": "Verification code", "conteudo": "Ola {{customerName}}, o seu codigo e 1234." } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/TemplatesSMS/AtualizarTemplate/{templateId}": { "put": { "tags": [ "SMS Templates" ], "summary": "Update SMS template", "description": "Method and route: `PUT /api/TemplatesSMS/AtualizarTemplate/{templateId}`. Updates the name and content of an existing SMS template.", "operationId": "updateSmsTemplate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsTemplateId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateRequest" }, "example": { "nome": "Verification code updated", "conteudo": "Mensagem de teste atualizada." } } } }, "responses": { "200": { "description": "Template updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" }, "example": { "id": 42, "nome": "Verification code updated", "conteudo": "Mensagem de teste atualizada." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/TemplatesSMS/DeletarTemplate/{templateId}": { "delete": { "tags": [ "SMS Templates" ], "summary": "Delete SMS template", "description": "Method and route: `DELETE /api/TemplatesSMS/DeletarTemplate/{templateId}`. Deletes an SMS template that is no longer needed.", "operationId": "deleteSmsTemplate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsTemplateId" } ], "responses": { "200": { "description": "Template deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsActionResult" }, "example": { "success": true, "message": "Template deleted." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Contactos/CadastrarContacto": { "post": { "tags": [ "SMS Contacts" ], "summary": "Create SMS contact", "description": "Method and route: `POST /api/Contactos/CadastrarContacto`. Creates one SMS contact for the authenticated merchant.", "operationId": "createSmsContact", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactRequest" }, "example": { "nome": "Jane Customer", "telefone": "923000000" } } } }, "responses": { "200": { "description": "Contact created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContact" }, "example": { "contactoId": 120, "nome": "Jane Customer", "telefone": "923000000" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Contactos/ListarContactos": { "get": { "tags": [ "SMS Contacts" ], "summary": "List SMS contacts", "description": "Method and route: `GET /api/Contactos/ListarContactos`. Returns a paged list of contacts for the authenticated merchant.", "operationId": "listSmsContacts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paged contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactPage" }, "example": { "items": [ { "contactoId": 120, "nome": "Jane Customer", "telefone": "923000000" } ], "pageNumber": 1, "pageSize": 20, "totalCount": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Contactos/ObterContacto/{contactoId}": { "get": { "tags": [ "SMS Contacts" ], "summary": "Get SMS contact by ID", "description": "Method and route: `GET /api/Contactos/ObterContacto/{contactoId}`. Retrieves a single SMS contact by identifier.", "operationId": "getSmsContactById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsContactId" } ], "responses": { "200": { "description": "Contact details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContact" }, "example": { "contactoId": 120, "nome": "Jane Customer", "telefone": "923000000" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Contactos/AtualizarContacto/{contactoId}": { "put": { "tags": [ "SMS Contacts" ], "summary": "Update SMS contact", "description": "Method and route: `PUT /api/Contactos/AtualizarContacto/{contactoId}`. Updates a contact's display name and phone number.", "operationId": "updateSmsContact", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsContactId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactRequest" }, "example": { "nome": "Jane Customer Updated", "telefone": "923000000" } } } }, "responses": { "200": { "description": "Contact updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContact" }, "example": { "contactoId": 120, "nome": "Jane Customer Updated", "telefone": "923000000" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Contactos/DeletarContacto/{contactoId}": { "delete": { "tags": [ "SMS Contacts" ], "summary": "Delete SMS contact", "description": "Method and route: `DELETE /api/Contactos/DeletarContacto/{contactoId}`. Deletes a contact from the authenticated merchant account.", "operationId": "deleteSmsContact", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsContactId" } ], "responses": { "200": { "description": "Contact deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsActionResult" }, "example": { "success": true, "message": "Contact deleted." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Contactos/criar-lista-com-contactos": { "post": { "tags": [ "SMS Contacts" ], "summary": "Create contact list", "description": "Method and route: `POST /api/Contactos/criar-lista-com-contactos`. Creates a contact list and associates existing contact IDs with it.", "operationId": "createSmsContactList", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactListRequest" }, "example": { "nome": "Payment alerts", "contactoIds": [ 120 ] } } } }, "responses": { "200": { "description": "Contact list created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactList" }, "example": { "listaDeContactoId": 30, "nome": "Payment alerts", "contactoIds": [ 120 ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Contactos/ListarListasDeContactos": { "get": { "tags": [ "SMS Contacts" ], "summary": "List contact lists", "description": "Method and route: `GET /api/Contactos/ListarListasDeContactos`. Returns a paged list of SMS contact lists for the authenticated merchant.", "operationId": "listSmsContactLists", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paged contact lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactListPage" }, "example": { "items": [ { "listaDeContactoId": 30, "nome": "Payment alerts", "totalContactos": 1 } ], "pageNumber": 1, "pageSize": 20, "totalCount": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Contactos/ObterListaDeContactos/{listaId}": { "get": { "tags": [ "SMS Contacts" ], "summary": "Get contact list by ID", "description": "Method and route: `GET /api/Contactos/ObterListaDeContactos/{listaId}`. Retrieves a contact list and its associated contacts.", "operationId": "getSmsContactListById", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsContactListId" } ], "responses": { "200": { "description": "Contact list details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsContactList" }, "example": { "listaDeContactoId": 30, "nome": "Payment alerts", "contactos": [ { "contactoId": 120, "nome": "Jane Customer", "telefone": "923000000" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Contactos/AdicionarContactoALista": { "post": { "tags": [ "SMS Contacts" ], "summary": "Add contact to list", "description": "Method and route: `POST /api/Contactos/AdicionarContactoALista`. Adds an existing contact to an existing SMS contact list.", "operationId": "addSmsContactToList", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSmsContactToListRequest" }, "example": { "contactoId": 120, "listaId": 30 } } } }, "responses": { "200": { "description": "Contact added to list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsActionResult" }, "example": { "success": true, "message": "Contact added to list." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Contactos/DeletarListaDeContactos/{listaId}": { "delete": { "tags": [ "SMS Contacts" ], "summary": "Delete contact list", "description": "Method and route: `DELETE /api/Contactos/DeletarListaDeContactos/{listaId}`. Deletes a contact list. Contacts can remain available outside the deleted list.", "operationId": "deleteSmsContactList", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SmsContactListId" } ], "responses": { "200": { "description": "Contact list deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsActionResult" }, "example": { "success": true, "message": "Contact list deleted." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/Envio/enviarSms": { "post": { "tags": [ "SMS Sending" ], "summary": "Send SMS text", "description": "Method and route: `POST /api/Envio/enviarSms`. Sends a plain text SMS message to one or more destination numbers using the authenticated merchant SMS account.", "operationId": "sendSmsText", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsTextRequest" }, "example": { "numerosDestino": [ "923000000" ], "conteudo": "Your IZI Pay payment was received." } } } }, "responses": { "200": { "description": "SMS send accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSendResult" }, "example": { "batchId": "sms-batch-123", "totalDestinatarios": 1, "estado": "Accepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/enviarSmsTemplate": { "post": { "tags": [ "SMS Sending" ], "summary": "Send SMS using template", "description": "Method and route: `POST /api/Envio/enviarSmsTemplate`. Sends an SMS message using an existing template ID. Use this when message content is managed as a reusable template.", "operationId": "sendSmsTemplate", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsTemplateRequest" }, "example": { "smsId": 42, "numerosDestino": [ "923000000" ], "remetente": "IZIPAY" } } } }, "responses": { "200": { "description": "Template SMS send accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSendResult" }, "example": { "batchId": "sms-batch-124", "totalDestinatarios": 1, "estado": "Accepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/enviar-para-lista": { "post": { "tags": [ "SMS Sending" ], "summary": "Send SMS to contact list", "description": "Method and route: `POST /api/Envio/enviar-para-lista`. Sends a text SMS to every contact in an existing contact list.", "operationId": "sendSmsToContactList", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSmsListRequest" }, "example": { "listaId": 30, "remetente": "IZIPAY", "conteudo": "Your IZI Pay payment was received." } } } }, "responses": { "200": { "description": "List SMS send accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSendResult" }, "example": { "batchId": "sms-batch-125", "totalDestinatarios": 25, "estado": "Accepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/ListarSmsEnviadas": { "get": { "tags": [ "SMS Sending" ], "summary": "List sent SMS", "description": "Method and route: `GET /api/Envio/ListarSmsEnviadas`. Returns a paged history of SMS messages sent by the authenticated merchant.", "operationId": "listSentSms", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paged sent SMS history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SentSmsPage" }, "example": { "items": [ { "smsId": 9001, "telefone": "923000000", "conteudo": "Your IZI Pay payment was received.", "estado": "Sent", "enviadoEm": "2026-06-14T10:30:00Z" } ], "pageNumber": 1, "pageSize": 20, "totalCount": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/ObterUltimos5SmsEnviados": { "get": { "tags": [ "SMS Sending" ], "summary": "Get latest five sent SMS", "description": "Method and route: `GET /api/Envio/ObterUltimos5SmsEnviados`. Returns the five most recent SMS messages sent by the authenticated merchant.", "operationId": "getLatestSentSms", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Latest sent SMS messages.", "content": { "application/json": { "schema": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/SentSms" } }, "example": [ { "smsId": 9001, "telefone": "923000000", "conteudo": "Your IZI Pay payment was received.", "estado": "Sent", "enviadoEm": "2026-06-14T10:30:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/PesquisarSMSEnviados": { "get": { "tags": [ "SMS Sending" ], "summary": "Search sent SMS by date", "description": "Method and route: `GET /api/Envio/PesquisarSMSEnviados`. Finds sent SMS messages for a specific day, month, and year.", "operationId": "searchSentSmsByDate", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Day" }, { "$ref": "#/components/parameters/Month" }, { "$ref": "#/components/parameters/Year" } ], "responses": { "200": { "description": "Matching sent SMS messages.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SentSms" } }, "example": [ { "smsId": 9001, "telefone": "923000000", "conteudo": "Your IZI Pay payment was received.", "estado": "Sent", "enviadoEm": "2026-06-14T10:30:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/Envio/pesquisarEnviosPorIntervaloDeDatas": { "get": { "tags": [ "SMS Sending" ], "summary": "Search sent SMS by date interval", "description": "Method and route: `GET /api/Envio/pesquisarEnviosPorIntervaloDeDatas`. Finds sent SMS messages between a start date and an end date.", "operationId": "searchSentSmsByDateInterval", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/StartDay" }, { "$ref": "#/components/parameters/StartMonth" }, { "$ref": "#/components/parameters/StartYear" }, { "$ref": "#/components/parameters/EndDay" }, { "$ref": "#/components/parameters/EndMonth" }, { "$ref": "#/components/parameters/EndYear" } ], "responses": { "200": { "description": "Matching sent SMS messages.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SentSms" } }, "example": [ { "smsId": 9001, "telefone": "923000000", "conteudo": "Your IZI Pay payment was received.", "estado": "Sent", "enviadoEm": "2026-06-14T10:30:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/EnvioAgendado/agendar-envio-smstexto": { "post": { "tags": [ "Scheduled SMS" ], "summary": "Schedule text SMS", "description": "Method and route: `POST /api/EnvioAgendado/agendar-envio-smstexto`. Schedules a text SMS for a future date and time.", "operationId": "scheduleSmsText", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleSmsTextRequest" }, "example": { "numerosDestino": [ "923000000" ], "conteudo": "Scheduled IZI Pay reminder.", "dia": 15, "mes": 6, "ano": 2026, "hora": 10, "minuto": 30 } } } }, "responses": { "200": { "description": "SMS scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledSms" }, "example": { "agendamentoId": 501, "estado": "Scheduled", "agendadoPara": "2026-06-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/EnvioAgendado/listar": { "get": { "tags": [ "Scheduled SMS" ], "summary": "List scheduled SMS", "description": "Method and route: `GET /api/EnvioAgendado/listar`. Returns scheduled SMS messages. Use `apenasPendentes=true` to show only pending schedules.", "operationId": "listScheduledSms", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "apenasPendentes", "in": "query", "required": false, "description": "When true, returns only pending scheduled sends.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Paged scheduled SMS messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledSmsPage" }, "example": { "items": [ { "agendamentoId": 501, "estado": "Scheduled", "agendadoPara": "2026-06-15T10:30:00Z" } ], "pageNumber": 1, "pageSize": 20, "totalCount": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "webhooks": { "pprReferencePaymentNotification": { "post": { "summary": "PPR reference payment notification", "description": "**Merchant Callback Endpoint**\n\nThe callback endpoint is an HTTPS URL hosted by the merchant and provided to the IZI Pay development team during setup. This is the endpoint where IZI Pay sends payment status updates and notifications.\n\nAlong with the callback URL, the merchant must also provide an Access-Key. IZI Pay includes this key in the request headers of every callback request so that the merchant can authenticate and validate incoming notifications.\n\n> The merchant is responsible for ensuring that the callback endpoint is publicly accessible and capable of receiving and processing requests from IZI Pay.\n\nThis callback applies to PPR references created through the current API.\n\n> **Summary**\n>\n> During onboarding, the merchant must provide the following details to the IZI Pay development team:\n>\n> - **Callback URL:** The HTTPS endpoint where IZI Pay will send payment status notifications.\n> - **Access-Key:** A secret value chosen and provided by the merchant. IZI Pay includes this value in the request headers of every callback request, allowing the merchant to verify that the notification originated from IZI Pay.\n", "operationId": "receivePprReferencePaymentNotification", "parameters": [ { "name": "Access-Key", "in": "header", "required": true, "description": "Access key chosen or generated by the merchant for this webhook. IZI Pay sends this same value in the Access-Key header so your endpoint can authenticate the notification.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPprWebhookRequest" }, "example": { "idTransacao": "00000", "numLogSistema": "12967628", "idLogSistema": "8588", "dataTransaccaoCliente": "2026-06-08T11:52:56", "montantePago": 20, "tipoTerminal": "M", "iIdentTerminal": "0000000000", "localidadeTerminal": "Internet ", "refPagamento": "744757420", "nib": null, "banco": null, "Id": "f6701cf7-7fb8-4321-b4a1-eb5138ec9f88" } } } }, "responses": { "200": { "description": "Return HTTP 2xx with `Success: true` when the notification was processed successfully or was already processed before.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantWebhookResponse" }, "examples": { "processed": { "summary": "Payment processed", "value": { "Success": true, "Obs": "Payment processed successfully", "Id": "merchant-payment-123" } }, "duplicate": { "summary": "Payment already processed", "value": { "Success": true, "Obs": "Payment already processed", "Id": "merchant-payment-123" } } } } } } } } }, "qrCodePaymentNotification": { "post": { "summary": "QR Code payment notification", "description": "**Merchant Callback Endpoint**\n\nThe callback endpoint is an HTTPS URL hosted by the merchant and provided to the IZI Pay development team during setup. This is the endpoint where IZI Pay sends payment status updates and notifications.\n\nAlong with the callback URL, the merchant must also provide an Access-Key. IZI Pay includes this key in the request headers of every callback request so that the merchant can authenticate and validate incoming notifications.\n\n> The merchant is responsible for ensuring that the callback endpoint is publicly accessible and capable of receiving and processing requests from IZI Pay.\n\nThis callback applies to GPO QR Code payments created through the Payments API.\n\n> **Summary**\n>\n> During onboarding, the merchant must provide the following details to the IZI Pay development team:\n>\n> - **Callback URL:** The HTTPS endpoint where IZI Pay will send payment status notifications.\n> - **Access-Key:** A secret value chosen and provided by the merchant. IZI Pay includes this value in the request headers of every callback request, allowing the merchant to verify that the notification originated from IZI Pay.\n", "operationId": "receiveQrCodePaymentNotification", "parameters": [ { "name": "Access-Key", "in": "header", "required": true, "description": "Access key chosen or generated by the merchant for this webhook. IZI Pay sends this same value in the Access-Key header so your endpoint can authenticate the notification.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantQrCodeWebhookRequest" }, "example": { "creationDate": "2026-06-08T17:26:45.453+01:00", "updatedDate": "2026-06-08T17:26:46.269+01:00", "id": "5CJ2IZ48T7MAPH1G", "amount": 1, "clearingPeriod": "4", "transactionNumber": "15", "status": "ACCEPTED", "transactionType": "PAYMENT", "orderOrigin": "QR_CODE", "currency": "AOA", "reference": { "id": "TK050B02NWY9EKU" }, "pointOfSale": { "id": "540128" }, "merchantReferenceNumber": "TK050B02NWY9EKU" } } } }, "responses": { "200": { "description": "Return HTTP 2xx with `Success: true` when the notification was processed successfully or was already processed before.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantWebhookResponse" }, "examples": { "processed": { "summary": "Payment processed", "value": { "Success": true, "Obs": "Payment processed successfully", "Id": "merchant-payment-123" } }, "duplicate": { "summary": "Payment already processed", "value": { "Success": true, "Obs": "Payment already processed", "Id": "merchant-payment-123" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "MerchantId": { "name": "merchantId", "in": "path", "required": true, "description": "Merchant identifier.", "schema": { "type": "string" }, "example": "BB1376D9-03D3-45C6-82FA-61F4270D27B6" }, "UserId": { "name": "userId", "in": "path", "required": true, "description": "User identifier.", "schema": { "type": "string" }, "example": "11111111-1111-1111-1111-111111111111" }, "InvoiceId": { "name": "invoiceId", "in": "path", "required": true, "description": "Invoice identifier.", "schema": { "type": "string" }, "example": "inv_12345" }, "PaymentId": { "name": "paymentId", "in": "path", "required": true, "description": "External payment identifier.", "schema": { "type": "string" }, "example": "pay_12345" }, "InternalPaymentId": { "name": "internalPaymentId", "in": "path", "required": true, "description": "Internal payment GUID.", "schema": { "type": "string", "format": "uuid" }, "example": "a18aa875-7a13-47d3-96ca-795ce9ffafa9" }, "PprReference": { "name": "pprReference", "in": "path", "required": true, "description": "PPR reference value.", "schema": { "type": "string" }, "example": "425882116" }, "PosId": { "name": "posId", "in": "path", "required": true, "description": "GPO POS terminal identifier.", "schema": { "type": "string" }, "example": "413205" }, "SupervisorId": { "name": "supervisorId", "in": "query", "required": false, "description": "Optional supervisor identifier for terminal operations.", "schema": { "type": "string" }, "example": "12345" }, "Page": { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Number of records per page.", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, "PageNumber": { "name": "pageNumber", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "SmsTemplateId": { "name": "templateId", "in": "path", "required": true, "description": "SMS template identifier.", "schema": { "type": "integer" }, "example": 42 }, "SmsContactId": { "name": "contactoId", "in": "path", "required": true, "description": "SMS contact identifier.", "schema": { "type": "integer" }, "example": 120 }, "SmsContactListId": { "name": "listaId", "in": "path", "required": true, "description": "SMS contact list identifier.", "schema": { "type": "integer" }, "example": 30 }, "Day": { "name": "dia", "in": "query", "required": true, "description": "Day of month.", "schema": { "type": "integer", "minimum": 1, "maximum": 31 }, "example": 14 }, "Month": { "name": "mes", "in": "query", "required": true, "description": "Month number.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 6 }, "Year": { "name": "ano", "in": "query", "required": true, "description": "Four-digit year.", "schema": { "type": "integer", "minimum": 2000 }, "example": 2026 }, "StartDay": { "name": "diaInicio", "in": "query", "required": true, "description": "Start day of month.", "schema": { "type": "integer", "minimum": 1, "maximum": 31 }, "example": 1 }, "StartMonth": { "name": "mesInicio", "in": "query", "required": true, "description": "Start month number.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 6 }, "StartYear": { "name": "anoInicio", "in": "query", "required": true, "description": "Start year.", "schema": { "type": "integer", "minimum": 2000 }, "example": 2026 }, "EndDay": { "name": "diaFim", "in": "query", "required": true, "description": "End day of month.", "schema": { "type": "integer", "minimum": 1, "maximum": 31 }, "example": 14 }, "EndMonth": { "name": "mesFim", "in": "query", "required": true, "description": "End month number.", "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 6 }, "EndYear": { "name": "anoFim", "in": "query", "required": true, "description": "End year.", "schema": { "type": "integer", "minimum": 2000 }, "example": 2026 } }, "schemas": { "ClientCredentialsTokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "client_secret", "scope" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "format": "password" }, "scope": { "type": "string" } } }, "PasswordTokenRequest": { "type": "object", "required": [ "grant_type", "username", "password", "scope", "client_id" ], "properties": { "grant_type": { "type": "string", "enum": [ "password" ] }, "username": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "scope": { "type": "string" }, "client_id": { "type": "string" } } }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "integer" }, "token_type": { "type": "string", "example": "Bearer" } } }, "RegisterUserRequest": { "type": "object", "required": [ "email", "password", "firstName", "lastName" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" } } }, "TokenOnlyRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "ForgotPasswordRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "ResetPasswordRequest": { "type": "object", "required": [ "token", "newPassword" ], "properties": { "token": { "type": "string" }, "newPassword": { "type": "string", "format": "password" } } }, "UserInfoResponse": { "type": "object", "additionalProperties": true, "properties": { "sub": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "EnableMfaRequest": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "integer", "description": "MFA method identifier." } } }, "AddMerchantUserRequest": { "type": "object", "required": [ "email", "roleId" ], "properties": { "email": { "type": "string", "format": "email" }, "roleId": { "type": "string" } } }, "CustomMetadata": { "type": "object", "additionalProperties": true, "description": "A merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.\n\nProperty names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or `null`. Key spelling and casing are preserved.\n\nIZI Pay stores these values without using them to control payment processing. They are returned as `customMetadata` by payment creation/detail/list and PPR creation/detail/list responses.\n\nUse this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.", "example": { "invoiceNumber": "INV-2026-0042", "department": "SALES", "sourceSystem": "ERP" } }, "CreatePaymentRequest": { "type": "object", "required": [ "amount", "currency", "paymentType" ], "additionalProperties": true, "properties": { "amount": { "type": "number", "minimum": 0, "maximum": 10000000, "description": "Payment amount expressed in the selected currency. Decimals are supported.\n\nFor `GPO` and `PPR` with `metadata.referenceType: Dynamic`, the amount must be between `0.01` and `10,000,000`. For a `PPR` charging reference, use `0` for an open amount that the customer enters when paying; a positive amount is also accepted. Negative values are never allowed." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "Three-letter uppercase ISO-style currency code. Use `AOA` for kwanza payments.", "example": "AOA" }, "paymentType": { "type": "string", "description": "Payment rail to use. `GPO` creates a mobile money, authorization, or QR Code payment; `PPR` creates a payment reference.", "enum": [ "GPO", "PPR" ] }, "reference": { "type": "string", "maxLength": 15, "description": "Merchant payment identifier. It is required for `GPO` and may contain up to 15 characters (individual GPO methods can impose a stricter format).\n\nFor `PPR`, omit it or send an empty string to have IZI Pay generate a 9-digit reference. To define the reference yourself, send only digits and use between 9 and 15 digits. A merchant-defined dynamic reference cannot be reused while the same reference is active and unpaid for the entity." }, "description": { "type": "string", "deprecated": true, "description": "Legacy top-level description. Connector-specific descriptions are read from `metadata.description`; use that field for new integrations." }, "metadata": { "description": "Payment-type-specific settings for `POST /api/payments`.\n\nConnector settings such as `paymentMethod`, `referenceType`, `expiryDate`, and customer fields belong directly in this object. Merchant-defined fields must be grouped inside `metadata.custom`; do not place arbitrary merchant keys alongside connector settings.\n\nValues sent in `metadata.custom` are stored with the payment and returned as the top-level `customMetadata` property in creation and lookup responses. Do not send a top-level `customMetadata` field to `/api/payments`.", "oneOf": [ { "$ref": "#/components/schemas/GpoPaymentMetadata" }, { "$ref": "#/components/schemas/PprPaymentMetadata" } ] } } }, "GpoPaymentMetadata": { "type": "object", "additionalProperties": true, "description": "Settings used when `paymentType` is `GPO`.", "properties": { "paymentMethod": { "type": "string", "description": "GPO flow to start. Use `webframe` for hosted checkout, `onetimepurchase` for an immediate mobile payment, `authorization` to reserve funds, `capture` to complete a previous authorization, or `qrcode` to create a QR Code. Defaults to `webframe` when omitted or unrecognized.", "enum": [ "webframe", "onetimepurchase", "authorization", "capture", "qrcode" ] }, "phoneNumber": { "type": "string", "description": "Customer mobile number used by mobile payment and authorization flows.", "example": "923000000" }, "provider": { "type": "string", "description": "Mobile network/payment provider used for the transaction.", "example": "UNITEL" }, "gpo_merchant_id": { "type": "string", "description": "GPO merchant identifier assigned during onboarding. It can also be supplied by the authenticated merchant configuration." }, "gpo_pos_id": { "type": "string", "description": "GPO point-of-sale identifier assigned during onboarding. It can also be supplied by the authenticated merchant configuration." }, "qrSize": { "type": "string", "description": "Requested QR Code image size. Used only when `paymentMethod` is `qrcode`; defaults to `MEDIUM`.", "example": "MEDIUM" }, "qrType": { "type": "string", "description": "QR Code behavior. Used only when `paymentMethod` is `qrcode`; defaults to `STATIC`.", "example": "STATIC" }, "maxTransactions": { "type": "integer", "minimum": 1, "description": "Maximum number of payments accepted by the QR Code. Used only for QR Code payments and defaults to `1`." }, "endDate": { "type": "string", "format": "date-time", "description": "Optional QR Code expiry in ISO 8601 format. Defaults to 24 hours after creation." }, "authorizationId": { "type": "string", "description": "Identifier returned by a previous authorization. Required when `paymentMethod` is `capture`." }, "description": { "type": "string", "description": "Description sent to GPO. For QR Code payments, the top-level `reference` is used when this value is omitted." }, "custom": { "type": "object", "additionalProperties": true, "description": "Optional merchant-defined JSON object for internal reconciliation data.\n\nThe merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or `null`. IZI Pay does not use these properties to select or configure the GPO payment method.\n\nThe object is returned as `customMetadata` in payment detail and list responses. Do not include credentials, card details, access tokens, or other secrets.", "example": { "invoiceNumber": "INV-2026-0042", "department": "SALES", "sourceSystem": "ERP" } } } }, "PprPaymentMetadata": { "type": "object", "additionalProperties": true, "description": "Settings used when `paymentType` is `PPR`.", "properties": { "referenceType": { "type": "string", "description": "PPR reference behavior. `Dynamic` is a fixed-amount reference and requires `amount` greater than zero. `Charging` is reusable and can receive multiple transactions; use `amount: 0` when the payer should choose the amount. Defaults to `Dynamic` when omitted.", "default": "Dynamic", "enum": [ "Dynamic", "Charging" ] }, "expiryDate": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 expiry date. If omitted, a dynamic reference expires one month after creation and a charging reference defaults to the end of 2099." }, "description": { "type": "string", "description": "Merchant-facing reason or label for the reference." }, "customerEmail": { "type": "string", "format": "email", "description": "Optional customer email stored with the reference and returned in the PPR payment response." }, "customerName": { "type": "string", "description": "Optional customer name stored with the reference and returned in the PPR payment response." }, "customerTelephone": { "type": "string", "description": "Optional customer telephone number returned in the PPR payment response." }, "documentNumber": { "type": "string", "description": "Optional customer identity document number returned in payment details." }, "custom": { "type": "object", "additionalProperties": true, "description": "Optional merchant-defined JSON object for linking the PPR payment to your internal records.\n\nThe merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or `null`. These values do not affect the generated entity, reference, amount, expiry, or payment status.\n\nSend this object as `metadata.custom` when using `POST /api/payments`. IZI Pay stores it and returns it as the top-level `customMetadata` property in PPR creation and lookup responses. Do not include credentials, card details, access tokens, or other secrets.", "example": { "invoiceNumber": "INV-2026-0042", "department": "SALES", "sourceSystem": "ERP" } } } }, "CreatePprReferenceRequest": { "type": "object", "additionalProperties": true, "properties": { "reference": { "type": "string", "pattern": "^[0-9]{9,15}$", "description": "Optional merchant-defined PPR reference containing 9 to 15 digits. Omit it to generate the reference automatically." }, "referenceType": { "type": "string", "description": "`Dynamic` creates a fixed-amount reference. `Charging` creates a reusable reference and allows an open amount. Defaults to `Dynamic` when omitted.", "default": "Dynamic", "enum": [ "Dynamic", "Charging" ] }, "amount": { "type": "number", "description": "Required and greater than zero for `Dynamic`; optional for `Charging`, where `0` represents an open amount." }, "expiryDate": { "type": "string", "format": "date-time", "description": "Optional future expiry in ISO 8601 format." }, "description": { "type": "string", "description": "Optional merchant-facing reason or label for the reference." }, "customerEmail": { "type": "string", "format": "email", "description": "Optional customer email stored with the reference." }, "customerName": { "type": "string", "description": "Optional customer full name stored with the reference." }, "customerTelephone": { "type": "string", "description": "Optional customer telephone number stored with the reference." }, "documentNumber": { "type": "string", "description": "Optional customer identity document number stored with the reference." }, "customMetadata": { "type": "object", "additionalProperties": true, "description": "Optional merchant-defined JSON object for internal reconciliation and record linking.\n\nThis is the direct PPR endpoint form: send `customMetadata` at the request root for `POST /api/references/ppr`, `/api/references/ppr/legacy`, and each item in `/api/references/ppr/bulk`. Do not wrap it in `metadata` or `custom`.\n\nProperty names are chosen by the merchant. Values may be strings, numbers, booleans, arrays, nested objects, or `null`. The values do not affect PPR processing and are returned unchanged as `customMetadata` in creation, detail, and list responses.\n\nDo not include credentials, card details, access tokens, or other secrets.", "example": { "invoiceNumber": "INV-2026-0042", "department": "SALES", "sourceSystem": "ERP", "purchaseOrder": "PO-98765", "customerCode": "CUS-001" } } } }, "CreateBulkPprReferencesRequest": { "type": "object", "required": [ "references" ], "properties": { "references": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CreatePprReferenceRequest" } } } }, "PaymentCreationResponse": { "type": "object", "additionalProperties": true, "description": "Payment creation response. The exact fields depend on the payment type and method.", "properties": { "id": { "type": "string", "description": "For compact PPR responses, this identifies the PPR reference record. Use `reference`, not this field, to call `GET /api/payments/{paymentId}`." }, "internalId": { "type": "string", "format": "uuid", "description": "Internal payment identifier when included by the selected payment flow." }, "entity": { "type": "string" }, "reference": { "type": "string", "description": "Provider/payment reference. For PPR, use this value to retrieve payment details." }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "telephone": { "type": "string" } } }, "customMetadata": { "$ref": "#/components/schemas/CustomMetadata" } } }, "PaymentDetailsResponse": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "internalId": { "type": "string", "format": "uuid" }, "merchantId": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "paymentType": { "type": "string", "enum": [ "GPO", "PPR" ] }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string" }, "customerTelephone": { "type": "string" }, "documentNumber": { "type": "string" }, "customMetadata": { "$ref": "#/components/schemas/CustomMetadata" } } }, "PagedPaymentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDetailsResponse" } }, "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalPages": { "type": "integer" }, "totalItems": { "type": "integer" } } }, "PprReferenceResponse": { "type": "object", "properties": { "reference": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" }, "referenceStatus": { "type": "string" }, "entity": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "customerEmail": { "type": "string", "format": "email" }, "customerName": { "type": "string" }, "customerTelephone": { "type": "string" }, "documentNumber": { "type": "string" }, "customMetadata": { "$ref": "#/components/schemas/CustomMetadata" } } }, "PprReferenceListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PprReferenceResponse" } }, "totalCount": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "BulkPprReferenceResponse": { "type": "object", "properties": { "successCount": { "type": "integer" }, "errorCount": { "type": "integer" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/PprReferenceResponse" } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "MerchantPprWebhookRequest": { "type": "object", "required": [ "idTransacao", "numLogSistema", "idLogSistema", "dataTransaccaoCliente", "montantePago", "tipoTerminal", "iIdentTerminal", "localidadeTerminal", "refPagamento", "Id" ], "properties": { "idTransacao": { "type": "string", "description": "Transaction identifier." }, "numLogSistema": { "type": "string", "description": "System log number associated with the payment notification." }, "idLogSistema": { "type": "string", "description": "System period/log identifier." }, "dataTransaccaoCliente": { "type": "string", "format": "date-time", "description": "Date and time when the customer payment was registered." }, "montantePago": { "type": "number", "description": "Amount paid by the customer." }, "tipoTerminal": { "type": "string", "description": "Terminal type used for the payment." }, "iIdentTerminal": { "type": "string", "description": "Terminal identifier." }, "localidadeTerminal": { "type": "string", "description": "Terminal location." }, "refPagamento": { "type": "string", "description": "Payment reference paid by the customer." }, "nib": { "type": "string", "nullable": true, "description": "Debit account NIB, when available." }, "banco": { "type": "string", "nullable": true, "description": "Bank name, when available." }, "Id": { "type": "string", "format": "uuid", "description": "Unique notification identifier. Use this value for idempotency." } } }, "MerchantQrCodeWebhookRequest": { "type": "object", "required": [ "creationDate", "updatedDate", "id", "amount", "clearingPeriod", "transactionNumber", "status", "transactionType", "orderOrigin", "currency", "reference", "pointOfSale", "merchantReferenceNumber" ], "properties": { "creationDate": { "type": "string", "format": "date-time", "description": "Date and time when the QR Code transaction was created." }, "updatedDate": { "type": "string", "format": "date-time", "description": "Date and time when the QR Code transaction status was updated." }, "id": { "type": "string", "description": "Unique provider transaction identifier. Use this value for idempotency." }, "amount": { "type": "number", "description": "Amount paid by the customer." }, "clearingPeriod": { "type": "string", "description": "Clearing period associated with the transaction." }, "transactionNumber": { "type": "string", "description": "Provider transaction number." }, "status": { "type": "string", "description": "QR Code payment status.", "example": "ACCEPTED" }, "transactionType": { "type": "string", "description": "Transaction type.", "example": "PAYMENT" }, "orderOrigin": { "type": "string", "description": "Payment order origin.", "example": "QR_CODE" }, "currency": { "type": "string", "description": "Payment currency.", "example": "AOA" }, "reference": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "QR Code reference identifier." } } }, "pointOfSale": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Point of sale identifier." } } }, "merchantReferenceNumber": { "type": "string", "description": "Merchant reference number associated with the QR Code payment." } } }, "MerchantWebhookResponse": { "type": "object", "required": [ "Success", "Obs", "Id" ], "properties": { "Success": { "type": "boolean", "description": "Return true when the notification was processed successfully or was already processed before." }, "Obs": { "type": "string", "description": "Short processing note." }, "Id": { "type": "string", "description": "Merchant internal payment identifier." } } }, "SmsLoggedUser": { "type": "object", "additionalProperties": true, "properties": { "userId": { "type": "string", "format": "uuid" }, "merchantId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "SmsMerchant": { "type": "object", "additionalProperties": true, "properties": { "merchantId": { "type": "string", "format": "uuid" }, "nome": { "type": "string" }, "remetenteSms": { "type": "string", "description": "Sender name configured for SMS messages." } } }, "SmsBalance": { "type": "object", "additionalProperties": true, "properties": { "merchantId": { "type": "string", "format": "uuid" }, "saldoAtual": { "type": "integer", "description": "Current available SMS units." }, "unidade": { "type": "string", "example": "sms" }, "atualizadoEm": { "type": "string", "format": "date-time" } } }, "SmsBalanceLedgerEntry": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "tipo": { "type": "string", "description": "Ledger entry type, such as credit or debit." }, "quantidade": { "type": "integer" }, "saldoDepois": { "type": "integer" }, "descricao": { "type": "string" }, "criadoEm": { "type": "string", "format": "date-time" } } }, "SmsTemplateRequest": { "type": "object", "required": [ "nome", "conteudo" ], "properties": { "nome": { "type": "string" }, "conteudo": { "type": "string" } } }, "SmsTemplate": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "nome": { "type": "string" }, "conteudo": { "type": "string" }, "criadoEm": { "type": "string", "format": "date-time" }, "atualizadoEm": { "type": "string", "format": "date-time" } } }, "SmsContactRequest": { "type": "object", "required": [ "nome", "telefone" ], "properties": { "nome": { "type": "string" }, "telefone": { "type": "string", "description": "Destination phone number in the format accepted by the SMS service." } } }, "SmsContact": { "type": "object", "additionalProperties": true, "properties": { "contactoId": { "type": "integer" }, "nome": { "type": "string" }, "telefone": { "type": "string" } } }, "SmsContactListRequest": { "type": "object", "required": [ "nome", "contactoIds" ], "properties": { "nome": { "type": "string" }, "contactoIds": { "type": "array", "items": { "type": "integer" } } } }, "SmsContactList": { "type": "object", "additionalProperties": true, "properties": { "listaDeContactoId": { "type": "integer" }, "nome": { "type": "string" }, "contactoIds": { "type": "array", "items": { "type": "integer" } }, "contactos": { "type": "array", "items": { "$ref": "#/components/schemas/SmsContact" } }, "totalContactos": { "type": "integer" } } }, "AddSmsContactToListRequest": { "type": "object", "required": [ "contactoId", "listaId" ], "properties": { "contactoId": { "type": "integer" }, "listaId": { "type": "integer" } } }, "SendSmsTextRequest": { "type": "object", "required": [ "numerosDestino", "conteudo" ], "properties": { "numerosDestino": { "type": "array", "items": { "type": "string" } }, "conteudo": { "type": "string" } } }, "SendSmsTemplateRequest": { "type": "object", "required": [ "smsId", "numerosDestino" ], "properties": { "smsId": { "type": "integer", "description": "SMS template identifier." }, "numerosDestino": { "type": "array", "items": { "type": "string" } }, "remetente": { "type": "string" } } }, "SendSmsListRequest": { "type": "object", "required": [ "listaId", "conteudo" ], "properties": { "listaId": { "type": "integer" }, "remetente": { "type": "string" }, "conteudo": { "type": "string" } } }, "SmsSendResult": { "type": "object", "additionalProperties": true, "properties": { "batchId": { "type": "string" }, "totalDestinatarios": { "type": "integer" }, "estado": { "type": "string" } } }, "SentSms": { "type": "object", "additionalProperties": true, "properties": { "smsId": { "type": "integer" }, "telefone": { "type": "string" }, "conteudo": { "type": "string" }, "estado": { "type": "string" }, "enviadoEm": { "type": "string", "format": "date-time" } } }, "ScheduleSmsTextRequest": { "type": "object", "required": [ "numerosDestino", "conteudo", "dia", "mes", "ano", "hora", "minuto" ], "properties": { "numerosDestino": { "type": "array", "items": { "type": "string" } }, "conteudo": { "type": "string" }, "dia": { "type": "integer", "minimum": 1, "maximum": 31 }, "mes": { "type": "integer", "minimum": 1, "maximum": 12 }, "ano": { "type": "integer" }, "hora": { "type": "integer", "minimum": 0, "maximum": 23 }, "minuto": { "type": "integer", "minimum": 0, "maximum": 59 } } }, "ScheduledSms": { "type": "object", "additionalProperties": true, "properties": { "agendamentoId": { "type": "integer" }, "estado": { "type": "string" }, "agendadoPara": { "type": "string", "format": "date-time" } } }, "SmsActionResult": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "SmsContactPage": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SmsContact" } } } }, "SmsContactListPage": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SmsContactList" } } } }, "SentSmsPage": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SentSms" } } } }, "ScheduledSmsPage": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledSms" } } } }, "SmsPage": { "type": "object", "additionalProperties": true, "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalCount": { "type": "integer" } } }, "TodoResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "To Be Done Soon" } } }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "responses": { "BadRequest": { "description": "The request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "To Be Done Soon", "message": "To Be Done Soon" } } } }, "Unauthorized": { "description": "The access token is missing, invalid, or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "To Be Done Soon", "message": "To Be Done Soon" } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "To Be Done Soon", "message": "To Be Done Soon" } } } } } } }