{ "openapi": "3.1.1", "info": { "title": "Gra.Api | v1", "version": "1.0.0" }, "servers": [ { "url": "http://footbridge-uat.masloc.gov.gh/collections/v1" } ], "paths": { "/tax/register": { "post": { "tags": [ "Tax" ], "summary": "Registers a taxpayer with the GRA MTS system.", "operationId": "RegisterTaxpayer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfRegisterTaxPayerResponse" } } } }, "400": { "description": "Bad Request" }, "502": { "description": "Bad Gateway" } } } }, "/tax/pay": { "post": { "tags": [ "Tax" ], "summary": "Pays tax on behalf of a taxpayer.", "operationId": "PayTax", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfPayTaxResponse" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfTransactionStatusResponse" } } } }, "400": { "description": "Bad Request" }, "409": { "description": "Conflict" }, "502": { "description": "Bad Gateway" } } } }, "/tax/taxpayer/info": { "get": { "tags": [ "Tax" ], "operationId": "GetTaxPayerInfo", "parameters": [ { "name": "ghanaCard", "in": "query", "schema": { "type": "string" } }, { "name": "phoneNumber", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfGetTaxPayerInfoResponse" } } } } } } }, "/tax/taxpayer/accountInfo": { "get": { "tags": [ "Tax" ], "operationId": "GetTaxPayerAccountInfo", "parameters": [ { "name": "ghanaCard", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfGetTaxPayerAccountInfoResponse" } } } } } } }, "/tax/taxpayer/compliance": { "get": { "tags": [ "Tax" ], "operationId": "GetComplianceStatus", "parameters": [ { "name": "ghanaCard", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfGetComplianceStatusResponse" } } } } } } }, "/tax/tcc/info": { "get": { "tags": [ "Tax" ], "operationId": "GetTccInfo", "parameters": [ { "name": "tccNumber", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfGetTccInfoResponse" } } } } } } }, "/tax/transactions/status": { "get": { "tags": [ "Tax" ], "operationId": "GetTransactionStatus", "parameters": [ { "name": "transactionId", "in": "query", "schema": { "type": "string" } }, { "name": "mtsTransactionId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfTransactionStatusResponse" } } } } } } }, "/tax/registration/questions": { "get": { "tags": [ "Tax" ], "operationId": "GetRegistrationQuestions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfQuestion" } } } } } } }, "/tax/registration/isics": { "get": { "tags": [ "Tax" ], "operationId": "GetIsics", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfIsic" } } } } } } }, "/tax/taxOffices": { "get": { "tags": [ "Tax" ], "operationId": "GetTaxOffices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseOfListOfTaxOfficeResponse" } } } } } } }, "/tax/integrations": { "post": { "tags": [ "Tax" ], "summary": "Sends an integration payload to MTS (verbatim proxy).", "operationId": "Integrations", "responses": { "200": { "description": "OK" } } } }, "/tax/Integration/upload": { "post": { "tags": [ "Tax" ], "summary": "Uploads a file to MTS (verbatim proxy).", "operationId": "IntegrationUpload", "responses": { "200": { "description": "OK" } } } }, "/tax/Upload/download/{fileId}": { "get": { "tags": [ "Tax" ], "summary": "Downloads a file from MTS (verbatim proxy).", "operationId": "UploadDownload", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "ApiResponseOfGetComplianceStatusResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GetComplianceStatusResponse" } ] } } }, "ApiResponseOfGetTaxPayerAccountInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GetTaxPayerAccountInfoResponse" } ] } } }, "ApiResponseOfGetTaxPayerInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GetTaxPayerInfoResponse" } ] } } }, "ApiResponseOfGetTccInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GetTccInfoResponse" } ] } } }, "ApiResponseOfListOfIsic": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Isic" } } } }, "ApiResponseOfListOfQuestion": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Question" } } } }, "ApiResponseOfListOfTaxOfficeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TaxOfficeResponse" } } } }, "ApiResponseOfPayTaxResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PayTaxResponse" } ] } } }, "ApiResponseOfRegisterTaxPayerResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegisterTaxPayerResponse" } ] } } }, "ApiResponseOfTransactionStatusResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "code": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TransactionStatusResponse" } ] } } }, "Business": { "type": "object", "properties": { "tradingName": { "type": [ "null", "string" ] }, "popularName": { "type": [ "null", "string" ] }, "natureOfBusiness": { "type": "string" }, "businessOutlets": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessOutlet" } } } }, "BusinessOutlet": { "type": "object", "properties": { "name": { "type": "string" }, "ghanaPostGps": { "type": "string" }, "dailySales": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "location": { "type": "string" }, "storeNumber": { "type": [ "null", "string" ] } } }, "GetComplianceStatusResponse": { "type": "object", "properties": { "isCompliant": { "type": "boolean" }, "taxCategory": { "type": "string" }, "asAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "GetTaxPayerAccountInfoResponse": { "type": "object", "properties": { "taxDue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "GetTaxPayerInfoResponse": { "type": "object", "properties": { "isRegistered": { "type": "boolean" }, "name": { "type": "string" }, "phoneNumber": { "type": "string" }, "ghanacard": { "type": "string" }, "isCompliant": { "type": "boolean" }, "tradingNames": { "type": [ "null", "array" ], "items": { "type": "string" } }, "taxDue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "GetTccInfoResponse": { "type": "object", "properties": { "ghanacard": { "type": "string" }, "issueDate": { "type": "string", "format": "date-time" }, "expiryDate": { "type": "string", "format": "date-time" } } }, "Isic": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" } } }, "ModeOfPayment": { "type": "integer" }, "PayRequest": { "required": [ "ghanacard", "agentCode", "agentName" ], "type": "object", "properties": { "ghanacard": { "type": "string" }, "amount": { "minimum": 0.01, "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "agentCode": { "type": "string" }, "agentName": { "type": "string" }, "modeOfPayment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModeOfPayment" } ] }, "callbackUrl": { "type": [ "null", "string" ], "format": "uri" } } }, "PayTaxResponse": { "type": "object", "properties": { "mtsTransactionId": { "type": "string" }, "receiptUrl": { "type": "string" } } }, "Question": { "type": "object", "properties": { "index": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "boolean" }, "active": { "type": "boolean" } } }, "QuestionnaireAnswer": { "type": "object", "properties": { "index": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "fieldName": { "type": "string" }, "value": { "type": "boolean" } } }, "RegisterRequest": { "required": [ "ghanacard", "name", "phoneNumber", "businesses", "agentCode", "agentName" ], "type": "object", "properties": { "ghanacard": { "type": "string" }, "name": { "type": "string" }, "phoneNumber": { "type": "string" }, "answers": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/QuestionnaireAnswer" } }, "businesses": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Business" } }, "handles": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/SocialHandle" } }, "agentCode": { "type": "string" }, "agentName": { "type": "string" }, "callbackUrl": { "type": [ "null", "string" ], "format": "uri" } } }, "RegisterTaxPayerResponse": { "type": "object", "properties": { "taxCategory": { "type": "string" }, "estimatedAnnualTurnover": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "notes": { "type": "string" } } }, "SocialHandle": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/SocialMediaType" }, "handle": { "type": "string" } } }, "SocialMediaType": { "type": "integer" }, "TaxOfficeResponse": { "type": "object", "properties": { "name": { "type": "string" }, "area": { "type": "string" }, "region": { "type": "string" }, "ghanaPostGps": { "type": "string" }, "longitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "latitude": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "TransactionStatusResponse": { "type": "object", "properties": { "transactionId": { "type": [ "null", "string" ] }, "mtsTransactionId": { "type": [ "null", "string" ] }, "ghanacard": { "type": "string" }, "amount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "status": { "type": "string" }, "statusDescription": { "type": [ "null", "string" ] }, "receiptUrl": { "type": [ "null", "string" ] }, "date": { "type": [ "null", "string" ], "format": "date-time" }, "transactionType": { "type": "string" } } } } }, "tags": [ { "name": "Tax" } ] }