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>/api/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.

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.