Migrating from v1
This page is for merchants already integrated with the IZI Pay v1 APIs, GPO (Online Payment Gateway) and Payment by Reference, who are considering the v2 Payment API. It summarises what works differently in v2 and maps each v1 operation to its v2 counterpart, so you can estimate the effort before deciding whether and when to move.
v1 remains available and supported, and you can keep using it. Moving to v2 is a choice, not a requirement. The v1 documentation stays under the Legacy tab: GPO and Payment by Reference.
What changes at a glance
| Topic | v1 | v2 |
|---|---|---|
| Authentication | GPO: POST /v2/AccessToken with your merchant username and password (JSON); send the returned token as Bearer.Payment by Reference: HMAC signature on every request, built from AppId and AppSecret, in the Authorization header. | POST /connect/token with grant_type=client_credentials (form-encoded); send access_token as Bearer and renew it before expires_in. See Authentication. |
| Base URLs | GPO: https://gpo.izipay.ao, sandbox https://gpo-sandbox.izipay.aoPayment by Reference: https://pay.izipay.ao, sandbox https://pay-sandbox.izipay.ao (/v1/... paths) | https://pay.izipay.ao, sandbox https://pay-sandbox.izipay.ao (/api/... paths) |
| Merchant and terminal IDs | GPO: merchantId and posId in the URL of each callPayment by Reference: Not in the URL; requests are scoped to your app keys | Read from the token (gpo_merchant_id, gpo_pos_id, ppr_entity_id); normally omitted from requests |
| Starting a payment | GPO: A separate endpoint per flow: authorise, capture, one-step purchase, QR Code charge, deeplink charge Payment by Reference: POST /v1/referencias | One endpoint, POST /api/payments. Pick the flow with paymentType plus metadata.paymentMethod (GPO) or metadata.referenceType (payment references). |
| Terminal open / close | GPO: Required: open the terminal before the first financial operation of the day; close it to settle. Payment by Reference: not applicable | Open, close and status endpoints exist, with an optional supervisorId. The reference does not say whether payments require an open terminal; check with IZI Pay. |
| Refunds | GPO: One refund endpoint per flow; requires the terminal supervisor (supervisorCard or supervisorId).Payment by Reference: not applicable | The reference documents List Refunds for reconciliation, but no operation to request a refund. Check with IZI Pay how refunds are requested. |
| Payment confirmation | GPO: Synchronous 201 plus the transaction status. QR Code and deeplink payments are forwarded to your callback with an Access-Key header.Payment by Reference: Optional merchant webhook with an Access-Key header, plus a notification list you poll and mark as read. | Webhooks for payments by reference and QR Code payments, with an Access-Key header. Your endpoint must return 2xx JSON with Success: true. You can also look up a payment or sync its status. |
| References | GPO: merchantReferenceNumber per order; GPO aggregates totals per reference.Payment by Reference: Each reference has a GUID id; customers pay with entity + reference number. | Payment reference operations use the reference number in the URL. Types are Dynamic (fixed amount) and Charging (reusable). |
| Duplicates and retries | GPO: A reused merchantReferenceNumber returns 400 REFERENCE_NUMBER. Deeplink charges have no idempotency key.Payment by Reference: Creating an existing reference number returns 422. | Optional metadata.idempotencyKey: a retry with the same key returns the existing payment. For payment references, the gateway derives a key from reference and amount when none is sent. |
| Amounts and dates | GPO: Numeric amounts Payment by Reference: Formatted strings, for example "10 000,00" and 31/12/2020 23:59 | Numeric amounts in AOA; ISO 8601 timestamps |
| Lists | GPO: OData $skip, $top, $orderBy, $filterPayment by Reference: page, pageSize (default 50) | pageNumber, pageSize (max 100) on payments and refunds; page, pageSize on payment references. Filters for status, type, dates and search. |
| Status values | GPO: Transaction status, for example ACCEPTEDPayment by Reference: Reference estado: válida, paga, cancelada, expirada | Pending, Processing, Authorized, Completed, Failed, Cancelled, Refunded, PartiallyRefunded |
| Errors | GPO: type + errors[] with code, messagePayment by Reference: errors[] with errorCode, errorMessage | Payment results carry status with errorCode / errorMessage (for a capture, inside additionalData). See Error Handling; check with IZI Pay for the full list of v2 codes. |
Check the status, not only the HTTP code
As in v1, a 201 from v2 does not prove that funds were collected. Fulfil an order only when the payment status is Completed, or after the webhook confirms the payment.
GPO → v2
All v2 payment flows below use Create a Payment (POST /api/payments) with paymentType: GPO, unless stated otherwise.
Authentication
v1 reference: Authentication
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Get access token | Get an access token (POST /connect/token) | OAuth client credentials (client_id, client_secret), form-encoded, instead of a username and password in JSON. The token carries your merchant and terminal IDs. |
Payments
v1 reference: Payments
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Authorize funds | Authorize funds (paymentMethod: authorization) | No posId in the URL. Send phoneNumber and provider in metadata. Save both authorizationId and internalId from the response. Card data is accepted only as an integration agreed with IZI Pay. |
| Capture funds | Capture an authorization (paymentMethod: capture) | A new POST /api/payments with metadata.authorizationId and its own reference, instead of a sub-resource of the authorisation. |
| Partial authorization | No direct equivalent | v2 has no token-based authorisation for a remaining amount. Check with IZI Pay how to handle partial captures. |
| Cancel authorization | Cancel Authorization | POST /api/payments/{internalPaymentId}/cancel with the authorisation's internalId (not authorizationId) and no body. |
| One-step purchase | One-time purchase (paymentMethod: onetimepurchase) | Non-alphanumeric characters are removed from reference. status: Completed means paid; Pending / Processing need tracking. |
QR Code & Deeplink
v1 reference: QR Code & Deeplink
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Create QR Code | QR Code (paymentMethod: qrcode) | Settings move to metadata (qrType, qrSize, maxTransactions, endDate). reference must be alphanumeric, 5 characters at most. Returns PNG bytes by default. |
| Create deeplink charge | QR Code with metadata.includeDeepLink: true | No separate endpoint. Returns JSON with deepLink and qrCodeBase64, and supports idempotencyKey. Support for an app return URL (v1 callbackUrlScheme) is not documented; check with IZI Pay. |
| Get QR Code image | No direct equivalent | The image is only returned when the payment is created. Store it if you need to show it again. |
Refunds
v1 reference: Refunds
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Refund authorized purchase | No direct equivalent | No refund-creation operation is documented in v2. List Refunds lists refund records. Check with IZI Pay how to request refunds. |
| Refund one-step purchase | No direct equivalent | As above. The v1 supervisorCard has no documented v2 counterpart. |
| Refund QR Code payment | No direct equivalent | As above. The v1 supervisorId has no documented v2 counterpart for refunds. |
Payment Tracking
v1 reference: Payment Tracking
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| List transactions | List Payments with paymentType=GPO | Merchant-wide, not per terminal. Uses pageNumber / pageSize and filters (status, startDate, endDate, search) instead of OData. |
| Get transaction | Get Payment Details | Look up by internalId or provider ID. Sync Payment Status queues a refresh from the provider. |
| List references | List Payments with search | search is a substring match on your reference; compare the returned value for an exact match. |
| Get reference | No direct equivalent | v2 has no aggregated reference view (totals authorised, paid, refunded, cancelled). Read each payment with Get Payment Details. |
Terminal Operations
v1 reference: Terminal Operations
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Open terminal | Open Terminal | GET /api/terminals/{posId}/open with an optional supervisorId. The response format and whether opening is still required before payments: check with IZI Pay. |
| Close terminal | Close Terminal | GET /api/terminals/{posId}/close with an optional supervisorId. Check with IZI Pay for the response format. |
| Get terminal | Get Terminal Status | GET /api/terminals/{posId}. Check with IZI Pay for the response format. |
| List merchant terminals | No direct equivalent | The terminal is identified by your token (gpo_pos_id). |
| List clearing periods | No direct equivalent | Check with IZI Pay for clearing-period reconciliation in v2. |
| Get clearing period | No direct equivalent | As above. |
Merchant
v1 reference: Merchant
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Get merchant | No direct equivalent | The merchant is identified by your token (gpo_merchant_id). Merchant Access manages which users can access a merchant account; it does not return merchant details. |
| Get establishment | No direct equivalent | Not exposed in the v2 Payment API. |
Payment by Reference → v2
v1 Payment by Reference creates Multicaixa references; in v2 these are payment references. v1 reference: References, Payments, Notifications, and the guides Information and Merchant Webhooks.
| v1 operation | v2 equivalent | What works differently |
|---|---|---|
| Create a reference | Create a Payment with paymentType: PPR, or Create a Payment Reference | Set referenceType (Dynamic or Charging). Numeric amount, ISO 8601 expiry, own data in metadata.custom (or customMetadata) instead of metadados. A reference you supply must have 9–15 digits. Bulk creation is also available. |
| List references | List Payment References | status filters the payment status; each item also has a separate referenceStatus. No filter by reference number. |
| Get a reference | Get Payment Reference Status | Identified by the reference number, not by the v1 GUID id. |
| Cancel a reference | Cancel Payment Reference | Identified by the reference number. Check with IZI Pay for the response format. |
| Get reference history | Get Payment Reference History | Returns payment rows (amount, status, isPaid), not the v1 list of operations (creation, cancellation, payment). |
| Check a reference number | No direct equivalent | The closest is Get Payment Reference Status, which returns 404 for an unknown reference. |
| List payments | List Payments with paymentType=PPR | Search by reference with search. For Charging references, each collection is a separate payment. |
| Get a payment | Get Payment Details | Use the payment's internalId from the list. |
| List notifications | No direct equivalent | Receive the payment by reference webhook and query List Payments. List Payment Reference Attempts shows failed attempts when enabled. |
| Update notification status | No direct equivalent | v2 has no read / unread notification state. |
| Merchant webhook (guide) | Receive Reference Payment Webhook | Same Access-Key header, request fields and Success: true response. It applies to references created through v2. Check with IZI Pay whether your v1 callback URL and key carry over. |
Legacy payment reference contract
v2 also exposes Create a Legacy Payment Reference for flows that still depend on the legacy payment reference contract. Check with IZI Pay whether it applies to your integration.
New in v2
These v2 features have no v1 counterpart:
- Webframe: a provider-hosted checkout page (
paymentMethod: webframe). - Sync Payment Status: ask the gateway to refresh a payment from the provider.
- List Refunds and List Payment Reference Attempts for reconciliation.
- Idempotency keys (
metadata.idempotencyKey) on payment creation.
Suggested migration steps
- Get v2 credentials. Ask IZI Pay for a v2
client_idandclient_secret, and confirm that your merchant, point of sale and reference entity are onboarded for v2. - Start in sandbox. Point your integration at
https://pay-sandbox.izipay.aoand request a token withPOST /connect/token. - Map your flows. Use the tables above to replace each v1 call. Update amounts, dates and identifiers, and check method-specific rules such as the 5-character QR Code
reference. - Switch notifications. Give IZI Pay your v2 callback URL and
Access-Key. Return2xxJSON withSuccess: true, and process duplicates idempotently. - Run in parallel. Keep v1 live while you test v2. Check with IZI Pay whether references and transactions created in v1 are visible in v2; until then, track and refund them through v1.
- Cut over. Switch production traffic to
https://pay.izipay.aowith your production credentials, monitor payment statuses and webhooks, and keep v1 available for any outstanding v1 operations.
Need help planning the move? Contact dev-tech@suplitel.ao.