Powered by Redocly

GPG Developer API Documentation (v1.0.1)

Download OpenAPI specification:Download

GPG Support Team: support@apcopay.com URL: https://mita.gov.mt License: All rights reserved Terms of Service

This is the Government Payment Gateway Documentation intended to facilitate the integration development efforts to make use of the MITA enabled Online Payment Services

The Government Payment Gateway (GPG) offers a collection of APIs to help you process and manage payments efficiently.

Our APIs accept and return JSON in the HTTP body and use standard HTTP response codes. You can interact with these APIs using your preferred HTTP/REST library.

To perform test transactions without affecting live data, request a Test API Key from a user with Payment Manager or Merchant Owner permissions.

How can I test? For performing test transcations you need to set the IsTest attribute in the respective transaction payloads.

Hosted Payment Page

The method in this section provide the required method to trigger a payment process via a Hosted Payment Page apporach

Create a Hosted Payment Page Token

This endpoint using a POST operation creates a Hosted Payment Page token.

SecurityGPGBearerToken
Request
Request Body schema: application/json
required
Any of:

To create a Hosted Payment Page, you must first generate a Payment Page Token. By setting the transaction type to 'Auth', the system will validate and authorize the card without capturing the funds. To capture the funds later, you will need to use the /PUT transaction within the Update Previous Payment operation.

TransactionType
required
any
Default: "AUTH"

Supported Transaction Types

Enum: "AUTH" "PURC"
Currency
required
any

Specifies the currency code for the transaction. We only support currency code "EUR"

Value: "EUR"
Amount
required
number

Indicates the transaction amount to be processed.

OrderReference
required
string

Merchant Unique Transaction Reference. This may be used for reconcilliation. It is important to note that the identifier is unique to the transaction.

RedirectionURL
required
string

Specifies the URL where the user should be redirected after the transaction.

CallBackURL
required
string

Specifies the URL where callback notifications or responses should be sent.

FailRedirectionURL
required
string

Indicates the URL where the user should be redirected in case the transaction fails. If not set the redirectionUrl is used instead.

UniqueReference
required
string <uuid>

A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilise a GUID or similar mechanism.

Language
any
Default: "en"

Sets the ISO 639-1 language code for the Hosted Payment Page. Will default to English if no language is set.

Enum: "en" "mt" "it" "es"
IsTest
required
boolean

Specifies if the transaction will be routed to the test bank. If yes, its important to use the test API key.

required
object (Client)
required
object (Configuration)
object (UDF)
object (Routing)

Forces the usage of that specific MID for routing traffic.

Responses
200
400
401
post/Transaction
Request samples
application/json
{
  • "TransactionType": "AUTH",
  • "Currency": "EUR",
  • "Amount": 10.96,
  • "OrderReference": "MerchantOrder1-556",
  • "UniqueReference": "7799665d-7c07-4826-87ad-437897e3bb54",
  • "RedirectionURL": "https://redirecturl.com",
  • "CallbackURL": "https://callbackurl.com",
  • "FailRedirectionURL": "https://failredirecturl.com",
  • "IsTest": true,
  • "Client": {
    },
  • "Configuration": {
    },
  • "UDF": {
    }
}
Response samples
application/json
{}

Payment Operations

The list of methods in this section facilitate further actions on a pre-established payment attempt

Update Previous Payment Operation

The methods under the PUT Operation request, perform additional operations on existing succesful transactions.

SecurityGPGBearerToken
Request
Request Body schema: application/json
required
Any of:

A 'capture' refers to the action of processing and finalising a previously authorised transaction, and initiating the transferring of funds from the customer's card to the merchant's account. This is only possible on an active authorisation transaction.

TransactionType
required
any

Specifies the Transaction Type for this operation.

Enum: "CAPT" "PARTIALREFUND" "GENERALVOID" "REPEATPURC"
Amount
required
number

Indicates the transaction amount to be processed.

CallBackURL
required
string

Specifies the URL where callback notifications or responses should be sent.

UniqueReference
required
string <uuid>

A unique identifier must be provided in this parameter to identify the request and prevent duplicate processing. It is recommended that you utilize a GUID or similar mechanism.

IsTest
required
boolean

Specifies if the transaction will be routed to the test bank. If yes, its important to use the test API key.

Trans_Id
required
string

This field should contain the reference Transaction ID where the capture request should be actioned.

Responses
200
400

Bad Request

401

Unauthorized

put/Transaction
Request samples
application/json
{
  • "TransactionType": "CAPT",
  • "Amount": 10,
  • "CallbackURL": "https://callbackurl.com",
  • "UniqueReference": "f90052e2-6614-4182-96a4-ad11601faad6",
  • "IsTest": true,
  • "Trans_Id": "bcb700ad-c43f-43ae-b233-e8f645867fb3"
}
Response samples
application/json
{
  • "success": true,
  • "result": {
    },
  • "dateTime": "2025-06-19T13:09:08.041227+02:00",
  • "processId": "b9fb35b7-c104-40f9-a041-a7e9330f887e"
}

Get Payment Information

The methods in this section provide information on the payments process

Get Payment Response

This endpoint is used to retrieve the status and information of a specific transaction ID.

SecurityGPGBearerToken
Request
query Parameters
TransactionId
required
string

This is GPG Unique Transaction Reference

Request Body schema: application/json
object
Responses
200
401

Unauthorized

get/Transaction
Request samples
application/json
No sample
Response samples
application/json
{
  • "success": true,
  • "result": {
    },
  • "dateTime": "2025-06-20T13:39:47.9257371+02:00",
  • "processId": "b0809b22-1ea3-481b-b020-242a244e2eec"
}

Reconciliation API

BatchByDate

Returns the transactions succesfully posted between startDate and the endDate.

SecurityGPGBearerToken
Request
Request Body schema: application/json
pageNumber
integer

refers to the specific subset of data that is returned by the API.

pageSize
integer

refers to the number of items which are returned on each page.

startDate
required
string

refers to the date from which you need to begin retrieving transactions.

endDate
required
string

refers to the date by which you require transactions to be retrieved.

Responses
200

OK

400

Bad Request

401

Unauthorized

post/Reconciliation/BatchByDate
Request samples
application/json
{
  • "pageNumber": 1,
  • "pageSize": 3,
  • "startDate": "2025-06-18",
  • "endDate": "2025-06-19"
}
Response samples
application/json
{
  • "success": true,
  • "result": {
    },
  • "dateTime": "2025-06-19T14:35:40.0731323+02:00",
  • "processId": "ab841dc9-b9b6-4e81-a3ed-1e7ca6db1649"
}

Reconciliation

Returns the details of the posted transactions using the startDate and endDate. This endpoint also requires either a list of transactionIDs or a list of order references.

SecurityGPGBearerToken
Request
Request Body schema: application/json
pageNumber
integer

refers to the specific subset of data that is returned by the API.

pageSize
integer

refers to the number of items which are returned on each page.

startDate
required
string

refers to the date from which you need to begin retrieving transactions.

endDate
required
string

refers to the date by which you require transactions to be retrieved.

transactionIDList
Array of strings

refers to the list of transaction IDs for conducting the search. The request should have this field or the orderRefList field.

orderRefList
Array of strings

refers to the list of order reference to conduct the search. The request should have this field or the transactionIDList field.

Responses
200

OK

400

Bad Request

401

Unauthorized

post/Reconciliation
Request samples
application/json
{
  • "pageSize": 10,
  • "pageNumber": 1,
  • "startDate": "2025-06-19",
  • "endDate": "2025-06-19",
  • "transactionIDList": [
    ]
}
Response samples
application/json
{
  • "success": true,
  • "result": {
    },
  • "dateTime": "2024-05-22T11:43:17.3071161+02:00",
  • "processId": "6138720e-a5d1-4431-9dee-cf85da1476ed"
}

GetStatus

Returns a list of posted transactions based on a list of transactionsID or order references.

SecurityGPGBearerToken
Request
Request Body schema: application/json
pageNumber
integer

refers to the specific subset of data that is returned by the API.

pageSize
integer

refers to the number of items which are returned on each page.

transactionIDList
Array of strings

refers to the list of transaction IDs for conducting the search. The request should have this field or the orderRefList field.

orderRefList
Array of strings

refers to the list of order reference to conduct the search. The request should have this field or the transactionIDList field.

Responses
200
400

Bad Request

401

Unauthorized

post/Reconciliation/GetStatus
Request samples
application/json
{
  • "pageNumber": 1,
  • "pageSize": 10,
  • "transactionIDList": [
    ]
}
Response samples
application/json
{
  • "success": true,
  • "result": {
    },
  • "dateTime": "2025-06-19T14:53:48.8839972+02:00",
  • "processId": "d0593188-054d-4d6c-84bc-48839913c391"
}

WebHooks

Payment NotificationWebhook

This is the webhook call sent to notify the merchant the outcome of the payment attempt

Request
header Parameters
signature
required
string

This value is intended to be used by the receiving logic to confirm that the payload has not been tempered with in transit. The following link explains the signature calculation process which needs to be implemented by the receiving logic and matched with the specific signature contained in the header Signature Calculation and Verification

Request Body schema: application/json
required

This is the transaction status JSON payload which provides details around the transaction

attemptNumber
integer

Specifies the callback attempts to send the payment notification linked to the specific pspid

sentDateTime
integer

This field represents the Epoch Timestamp of when the specific transaction has been received

transactionToken
string

The Hosted Payment Page token used for the Payment Process

orderReference
string

Merchant Unique Transaction Reference.

uniqueReference
string

Unique identifier generated for each and every attempt when performing a transaction

status
string

This attribute captures whether the transaction has been PROCESSED, is PENDING or DECLINED.
NOTE: One should always be checking the transaction state based on this status in this node since this is the node responsible for the payment information.

authCode
string

Indicates the Bank authorisation code

cardInput
string

Indicates whether a card has been inputted or not

gatewayId
integer
currency
string

Specifies the currency code for the transaction. 3-letter alpha (A-to Z) currency code ISO 4217

amount
string

Indicates the transaction amount that has been processed.

bankMessage
string or null

Indicates the Bank Response of the specific transaction attempt

cardNumber
string

Specifies the Masked Card Primary Account Number (Card Number) which typically is between 14 to 19 digit

cardExpiry
string

Specifies the Month/Year part of the Card Expiry

cardHolderName
string

Indicates the Card Holder Name & Surname

cardCountry
string

Country in Alpha-2 code of the card issuing bank

cardType
string

Specifies the type of Card Scheme Provider

acquirer
string

Indicates the Acquiring Bank of the transaction

email
string

Email address of the customer or client.

bankErrorCode
null

This attribute captures the Bank Error Code when the transaction is declined by Bank. It is set null if the Transaction has been Approved.

object
transid
string

This field contains the Gateway Unique Transaction ID

Responses
200
Request samples
application/json
{
  • "attemptNumber": 1,
  • "sentDateTime": 1750419854,
  • "transactionToken": "e3390bcd3edd41409c96c5c5527739ce",
  • "orderReference": "MerchantOrder1-556",
  • "uniqueReference": "b9ccc27f-599f-467c-9deb-e9d99e3ce075",
  • "status": "PROCESSED",
  • "authCode": "15466",
  • "cardInput": "true",
  • "gatewayId": 959133,
  • "currency": "EUR",
  • "amount": "10.96",
  • "bankMessage": "N/A",
  • "cardNumber": "401288******1881",
  • "cardExpiry": "12/2030",
  • "cardHolderName": "Frictionless Processed",
  • "cardCountry": "UKR",
  • "cardType": "VISA",
  • "acquirer": "PTEST",
  • "email": "joe.bloggs@testjb.com",
  • "bankErrorCode": "N/A",
  • "udf": {
    },
  • "transid": "611dacfd-b5c9-4c3b-ab79-5e60aaa0d6ef"
}