Introduction

Welcome to the ProxyPay API to interface with EMIS GPO. This allows merchant applications or services to request a payment from a client, via Multicaixa Express (GPO), using the mobile phone number.

API Format

All request bodies should have content type application/json and be valid JSON. The Content-Type header must be set in all requests that include a JSON body:

Content-Type: application/json

Endpoints

Authentication

You authenticate by providing a bearer token in the Authorization header of every request:

Authorization: Bearer [BEARER_TOKEN]

Transaction Lifecycle

The transaction is initiated by the merchant side and must be accepted by the customer on the Multicaixa Express App.

1. Merchant submits the transaction request. (See Transactions).
2. The API creates the transaction and initiates a request to GPO.
3. Once the GPO request returns, the callback URL receives an asynchronous HTTP(S) POST with the updated transaction object as payload. (See Transaction Schema).

Errors

The API may return the following HTTP error codes:

Resources

Transactions

New Payment

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b3dc944-e30d-49a5-9a94-923f72d11837" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod" \
  "https://<base_url>/opg/v1/transactions" \
  -d '{
        "type": "payment", 
        "pos_id": 123, 
        "mobile": "900123456", 
        "amount": "123.45",
        "callback_url": "https://your_hostname/link/to/confirm"
     }'

If the input is valid the transaction is created.

HTTP/1.1 201 Created

{
  "amount": "123.45",
  "id": "2KaABHhzBVa6qFHeJOebJDle8vG",
  "mobile": "900123456",
  "pos_id": 123,
  "type": "payment"
}

This endpoint creates a new payment transaction.

HTTP Request

POST https://<base_url>/opg/v1/transactions

Payload

Responses

New Refund

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 57feeb24-0b1c-4f53-82bf-9fd74d8249e1" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod" \
  "https://<base_url>/opg/v1/transactions" \
  -d '{
        "type": "refund", 
        "parent_transaction_id": "2KaABHhzBVa6qFHeJOebJDle8vG",
        "callback_url": "https://your_hostname/link/to/confirm"
      }'

If the input is valid the transaction is created.

HTTP/1.1 201 Created

{
  "id": "2KayAfTmbQCIUPoWlsV4G6jsc1T",
  "parent_transaction_id": "2KaABHhzBVa6qFHeJOebJDle8vG",
  "type": "refund"
}

This endpoint creates a new refund transaction. Only full refunds are currently supported.

HTTP Request

POST https://<base_url>/opg/v1/transactions

Payload

Responses

New Authorization

curl -XPOST \
   "Content-Type: application/json" \
  -H "Idempotency-Key: 1a63deb8-9c8b-40a0-ac77-2dde5778d4b5" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod" \
  "https://<base_url>/opg/v1/transactions" \
  -d '{
         "type": "authorization", 
         "pos_id": 123, 
         "mobile": "900111222", 
         "amount": "123.45",
         "callback_url": "https://your_hostname/link/to/confirm"
      }'

If the input is valid the transaction is created.

HTTP/1.1 201 Created

{
  "amount": "123.45",
  "id": "2Kb2wXfV0YOkQo0I51fBcoTLsbq",
  "mobile": "900111222",
  "pos_id": 123,
  "type": "authorization"
}

This endpoint creates a new payment authorization transaction. If accepted, funds will be held until an explicit payment with authorization transaction is submitted and accepted or until the authorization is either canceled or expires.

HTTP Request

POST https://<base_url>/opg/v1/transactions

Payload

Responses

New Cancelation

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 042558be-67db-47ad-aeb8-6aa5ad927361" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod" \
  "https://<base_url>/opg/v1/transactions" \
  -d '{
         "type": "cancelation", 
         "parent_transaction_id": "2Kb2wXfV0YOkQo0I51fBcoTLsbq",
         "callback_url": "https://your_hostname/link/to/confirm"
      }'

If the input is valid the transaction is created.

HTTP/1.1 201 Created


{
  "id": "2Kb3fXeArMGefP0if0CJ71DA5eP",
  "parent_transaction_id": "2Kb2wXfV0YOkQo0I51fBcoTLsbq",
  "type": "cancelation"
}

This endpoint creates a new cancelation transaction for a previously accepted authorization.

HTTP Request

POST https://<base_url>/opg/v1/transactions

Payload

Responses

New Payment w/ Authorization

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: e0baf9b9-356a-4b13-9efe-5a23b8a61b9e" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod" \
  "https://<base_url>/api/v1/transactions" \
  -d '{
        "type": "payment", 
        "parent_transaction_id": "2Kb2wXfV0YOkQo0I51fBcoTLsbq", 
        "amount": "123.45",
        "callback_url": "https://your_hostname/link/to/confirm"}'

If the input is valid the transaction is created.

HTTP/1.1 202 Accepted
location: /api/v1/requests/1kTFGhJH8i58uD9MdJpMjWnoE

This endpoint creates a new payment transaction from a previously accepted authorization, efectively capturing the amount.

HTTP Request

POST https://<base_url>/opg/v1/transactions

Payload

Responses

Get Transaction

curl "https://<base_url>/opg/v1/transactions/2KaABHhzBVa6qFHeJOebJDle8vG" \
  -H "Authorization: Bearer ve70pfacln98c7pc8j802pisdsg0f9i2anj5jlc3vtsfitod"

The above command returns a structure like this:

HTTP/1.1 200 OK

{
  "amount": "123.45",
  "id": "2KaABHhzBVa6qFHeJOebJDle8vG",
  "mobile": "900123456",
  "parent_transaction_id": null,
  "pos_id": 123,
  "status": "accepted",
  "status_datetime": "2023-01-10T08:09:55Z",
  "status_reason": null,
  "type": "payment"
}

This endpoint retrieves a specific transaction.

HTTP Request

GET https://<base_url>/opg/v1/transactions/<ID>

URL Parameters

Responses

Transaction Schema

The following table details the transaction schema:

Schema

Status

• accepted: payment/refund accepted by the payment system or customer
• rejected: payment/refund rejected by the payment system or customer

Status Reason

Gateway

Processor

Client

Idempotency

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b3dc944-e30d-49a5-9a94-923f72d11837" \
  ...

Notice the Idempotency-Key is passed as a Header to the POST HTTP request

To ensure the client application can implement a simple retry mechanism to handle timeouts, due to temporary communication failures with the API, an optional custom HTTP header Idempotency-Key can be included in the request of a new payment or refund transaction.

Idempotency-Key: [IDEMPOTENCY_KEY]

The Idempotency-Key should include a random and unique string. When retrying, the same value MUST be passed.

The server will cache the value along with the input parameters in the request payload. The following logic will be applied:

• If no Idempotency-Key header is passed, the server will not try to enforce any idempotency guarantee.

• If an Idempotency-Key header is passed, the server will do a lookup in the cache, using the header value as lookup key.

  • If the key is not found, the request will be processed as a new call, resulting in a request sent to the payment provider
  • If the key is found, and the request payload matches what is stored in the cache, the previous HTTP response will be returned, without processing the transaction again.
  • If the key is found, and the request payload does NOT match what is stored in the cache, an HTTP StatusCode 400 is returned.

The cache entries will be stored for 5 minutes, ensuring the server will keep a de-duplication window of 5 minutes.

Charges

The charges resource is currently only available in the sandbox environment. This new resource allows to initiate a payment either via QR-Code or via DeepLink. The normal flow is:

1. The merchant creates a charge and provides the client with the QR-Code, the deeplink, or the deeplink redirect URL.
2. The client scans the QR-Code or triggers the Deeplink (directly or via the redirect URL) and completes the transaction.

After the charge is created the status will be Active. Once the charge is used (via QR-Code or Deeplink), regardless of success or rejection, it can no longer be used. If not used the charge will expire after 30 minutes have passed since creation.

Charge Lifecycle

A charge transitions through the following statuses:

State Diagram

  ┌──────────┐
  │  active  │
  └────┬─────┘
       │
       ├── Client scans QR-Code / triggers Deeplink ───► ┌──────┐
       │                                                 │ used │
       │                                                 └──────┘
       │
       └── 30 minutes elapse without use ──────────────► ┌─────────┐
                                                         │ expired │
                                                         └─────────┘

Lifecycle Details

1. Active — A charge enters this status immediately upon creation. The merchant presents the qrcode_url, deeplink, or deeplink_redirect to the client.

2. Used — When the client scans the QR-Code or triggers the Deeplink, the charge transitions to used and a transaction is created. The transaction_id field is populated with the resulting transaction ID. This occurs regardless of whether the transaction is accepted or rejected — a used charge cannot be reused.

3. Expired — If 30 minutes pass since created_at without the charge being used, it automatically transitions to expired. No transaction is created.

Callback Notification

If a callback_url was provided when creating the charge, a POST request with the transaction payload is sent to that URL once the charge transitions to used. This is the recommended way to be notified of charge completion rather than polling the Get Charge endpoint.

New Charge

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b3dc944-e30d-49a5-9a94-923f72d11837" \
  -H "Authorization: Bearer <token>" \
  "https://<base_url>/opg/v1/charges" \
  -d '{
        "pos_id": 123, 
        "amount": "123.45",
        "callback_url": "https://your_hostname/link/to/confirm"
     }'

If the input is valid the charge is created.

HTTP/1.1 201 Created

{
  "amount": "123.45",
  "created_at": "2025-11-02T16:02:44Z",
  "deeplink": "mcxwallet://purchase?qrref=...",
  "deeplink_redirect": "https://deeplink.proxypay.co.ao/...",
  "expires_at": "2025-11-02T16:32:44Z",
  "id": "34vgGPAKbVTMmmsiyy3S7LYihDB",  
  "pos_id": 123,
  "qrcode_url": "https://qrcode.proxypay.co.ao/...",
  "status": "active",
  "transaction_id": null
}

This endpoint creates a new charge that can be used to generate a QRCode or a Deeplink.

HTTP Request

POST https://<base_url>/opg/v1/charges

Payload

Responses

Get Charge

curl  -H "Content-Type: application/json" \
      -H "Authorization: Bearer <token>" \
      "https://<base_url>/opg/v1/charges/34vgGPAKbVTMmmsiyy3S7LYihDB" 

If the id of the charge exists it will return the charge details.

HTTP/1.1 200 OK

{
  "amount": "123.45",
  "created_at": "2025-11-02T16:02:44Z",
  "deeplink": "mcxwallet://purchase?qrref=...",
  "deeplink_redirect": "https://deeplink.proxypay.co.ao/...",
  "expires_at": "2025-11-02T16:32:44Z",
  "id": "34vgGPAKbVTMmmsiyy3S7LYihDB",  
  "pos_id": 444,
  "qrcode_url": "https://qrcode.proxypay.co.ao/...",
  "status": "active",
  "transaction_id": null
}

This endpoint returns the details of the charge identified by charge_id.

HTTP Request

GET https://<base_url>/opg/v1/charges/<charge_id>

Responses

Create a Mock Charge Transaction

curl -XPOST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  "https://<base_url>/opg/v1/charges/34vgGPAKbVTMmmsiyy3S7LYihDB/transactions" \
  -d '{
        "status": "accepted"
      }'

The call above return HTTP status 200 if the Mock Charge Transaction was successfully created

HTTP/1.1 200 OK

{
  "amount": "123.45",
  "id": "2KaABHhzBVa6qFHeJOebJDle8vG",
  "mobile": null,
  "parent_transaction_id": null,
  "pos_id": 123,
  "status": "accepted",
  "status_datetime": "2023-01-10T08:09:55Z",
  "status_reason": null,
  "type": "payment"
}

This endpoint is only available on the Sandbox environment and produces a simulated Transaction event, as if originated directly from Multicaixa.

HTTP Request

POST https://<base_url>/opg/v1/charges/<ID>/transactions

URL Parameters

Payload

Responses

The response structure is described here.

Charge Schema

The following table details the charge schema:

Schema

Status expired and used are final status.

Sandbox

When using the sandbox environment please check information below.

Testing

Mobile

The mobile number you pass for the requests will determine the final status of the transaction.