GPO — Online Payment Gateway
This section documents the legacy IZI Pay Online Payment Gateway (GPO) API. It is intended for merchants that have not yet migrated to the current Payment API. Existing integrations can keep using it while planning their migration.
GPO processes card and MULTICAIXA Express payments through virtual terminals (points of sale). It exposes predictable REST URLs, accepts and returns JSON, and uses standard HTTP status codes.
POST /v2/AccessToken/v1/points-of-sale/{posId}/v1/merchants/{merchantId}…/authorizations…/payments…/charges/qrcode…/charges/deeplink…/transactions…/referencesEnvironments
| Environment | Base URL |
|---|---|
| Production | https://gpo.izipay.ao |
| Sandbox | https://gpo-sandbox.izipay.ao |
All requests must use HTTPS. Unencrypted connections are rejected with 403 Forbidden.
Integration at a glance
- 1AuthenticateExchange your user credentials for an access token.
POST /v2/AccessToken - 2Open the terminalStart a clearing period. Required for the first operation of the day.
GET …/{posId}/open - 3TransactAuthorise and capture, purchase, refund, or create a QR Code or deeplink charge.
POST …/{posId}/… - 4QueryFollow transactions, references and clearing periods.
GET …/transactions - 5Close the terminalSettle funds and commissions for the period.
GET …/{posId}/close
Authentication
Every request except the token request is authenticated with a Bearer token. Request it with the credentials of your GPO merchant user:
http
json
Then send the token on every call:
http
Keep credentials and tokens on your backend. Never ship them in mobile apps, browser code or public repositories.
Terminal lifecycle
A virtual terminal must be open before any financial operation. Opening it starts a new local clearing period and transaction sequence, which GPO assigns automatically to every operation that follows.
- The first operation of the day always requires opening the terminal. If it is already open, GPO closes it and opens it again.
- Closing the terminal ends the clearing period and asks the network to transfer the terminal's funds to your account and settle commissions.
- If a close is already running, a second close returns
403 CLOSE_IN_PROGRESS.
Use Get terminal to check the current status (OPEN / CLOSE) and clearing periods to reconcile totals.
Choosing a payment flow
| Authorized purchase | One-step purchase | QR Code / Deeplink | |
|---|---|---|---|
| Steps | Authorise → capture | Single purchase | Create charge → customer pays in the app |
| Who starts it | Your backend | Your backend | The customer scans or opens the link |
| Payment methods | Card, MULTICAIXA Express | MULTICAIXA Express | MULTICAIXA Express |
| Partial amounts | Capture ≤ authorised amount | — | — |
| Release funds | Cancel the authorisation (full amount) | Refund | Refund |
| Confirmation | 201 + transaction status | 201 + transaction status | Backend notification ACCEPTED |
| Guide | Below | API | QR Code · Deeplink |
Authorized purchase
http
GPO creates the Authorization resource whenever the customer's bank answers — accepted or declined. Always query the transaction and check its status before continuing. If communication with the bank fails, no resource is created and an error is returned.
Merchant reference numbers
merchantReferenceNumber must be unique. Reusing one returns 400 REFERENCE_NUMBER, which protects you from charging the same order twice.
Capture funds
Capturing turns the reservation into a purchase. Send the amount to charge and the same currency as the authorisation, using the authorisation id returned in step 1:
http
| Rule | Otherwise |
|---|---|
amount ≤ authorised amount (a lower amount is a partial capture). | 400 — amount above the authorization |
currency matches the authorisation. | 400 — different currency |
| The authorisation was accepted (not refused by the customer, not timed out). | 400 — refused / timeout |
| The authorisation was not captured before. | 400 — already used or paid in full |
| The authorisation exists and was not cancelled. | 404 |
Check the authorisation before capturing
A 201 on the authorisation only means the bank answered. Capture only when the transaction status is ACCEPTED. Validation errors on this endpoint return type: "INVALID_REQUES" (sic).
Charging the remaining amount
An authorisation is captured once. If you captured less than the authorised amount and later need the rest, create a partial authorisation for the remaining value, then capture it. Instead of card or phone data, it uses the payment token GPO attached to your merchant reference — read it from paymentToken.id with Get reference.
json
Refunds and the supervisor card
Refunds debit the merchant, so they require the supervisorCard associated with the terminal. The refund amount must be equal to or lower than the purchase amount.
json
Querying lists
List endpoints (transactions, references, clearing periods and merchant terminals) accept OData-style query parameters:
| Parameter | Default | Description |
|---|---|---|
$skip | 0 | Number of records to skip. |
$top | 20 | Number of records per response. |
$orderBy | — | Result ordering. |
$filter | — | Filter expression, for example only open terminals. |
An unknown parameter returns 400 QUERY_PARAMS. Search endpoints return 200 OK with an empty array when nothing matches.
Return codes
| Code | Status | Definition |
|---|---|---|
| 200 | OK | The requested resource was processed and returned successfully. |
| 201 | Created | Resource created successfully. |
| 204 | No Content | Resource updated or deleted successfully. |
| 400 | Bad Request | The request could not be interpreted, or a business validation failed. |
| 401 | Unauthorized | Token missing, invalid or expired. |
| 402 | Payment Required | Credentials are valid, but the account is blocked for non-payment. |
| 403 | Forbidden | Unencrypted connection, a resource you cannot access, or a blocked operation. |
| 404 | Not Found | Resource or endpoint not found. |
| 422 | Unprocessable Entity | Invalid parameters or business exceptions — see errors. |
| 429 | Too Many Requests | Rate limit reached. Wait for the seconds in the Retry-After header. |
| 500 | Internal Server Error | Failure in the IZI Pay API. Contact support. |
Error format
json
type | code | When |
|---|---|---|
AUTHORIZATION | NOT_AUTHORIZED | Token missing, invalid or expired. |
INVALID_REQUEST | REFERENCE_NUMBER | Merchant reference number already used. |
INVALID_REQUEST | QUERY_PARAMS | Unknown or malformed query parameter. |
INVALID_REQUEST | PATH_PARAMS | Invalid identifier in the URL. |
INVALID_REQUEST | RESOURCE | Terminal, transaction, reference or period not found. |
INVALID_REQUEST | INVALID_TERMINAL_STATE | Terminal already closed. |
BUSINESS | TRANSACTIONAL_BLOCKED | Financial operations blocked for the terminal. |
BUSINESS | CLOSE_IN_PROGRESS | A close request is already running. |
OPG_BUSINESS | BUSINESS | The transaction was already processed. |
SYSTEM_ERROR | GENERAL_ERROR | System unavailable. Contact support. |
Next steps
- Let customers scan and pay with a QR Code.
- Open MULTICAIXA Express straight from your mobile app with a Deeplink charge.
- Explore every endpoint in the GPO API reference.
- Need help? Contact dev-tech@suplitel.ao.