Choose a method, create payments, and manage unused authorizations, with guidance before the request schema.
Create a Payment
Create a payment, reserve funds, or issue a payment reference with POST /api/payments. The same endpoint supports several flows. First choose how the customer will pay; then send the common fields and the settings for that method.
Choose a Payment Method
For GPO, set metadata.paymentMethod. For PPR, set metadata.referenceType. Select a card to jump to the explanation and fields for that method. Each method also has a request example in the panel on the right.
Before Your First Request
Send Authorization: Bearer <merchant-token> and Content-Type: application/json. Use the token for the merchant receiving the payment. GPO needs an onboarded merchant and point of sale; PPR needs an enabled reference type and a PPR entity.
The gateway reads gpo_merchant_id, gpo_pos_id, and gpo_user_email from the token and uses those values in preference to request metadata. Normally you omit these fields from the body. If your integration supplies them explicitly, use the values assigned during onboarding; all three must be available to the connector. PPR's ppr_entity_id is supplied by the merchant token.
Common Request Fields
These fields belong at the top level of the JSON body. Method-specific settings belong inside metadata.
| Field | Required? | Meaning and rules |
|---|---|---|
paymentType | Yes | GPO for checkout, mobile, QR Code, authorization, and capture; PPR for references. |
amount | Yes | Numeric amount in AOA, not cents. GPO and Dynamic PPR accept 0.01–10000000. Charging accepts 0–10000000; 0 lets the payer enter the amount. |
currency | No; recommended | Send AOA. The gateway defaults to AOA when omitted and validates a supplied currency as three uppercase letters. This does not imply support for other currencies. |
reference | GPO: yes. PPR: optional | Your payment reference. The gateway accepts up to 100 characters, with stricter method rules below. It is distinct from the gateway's internalId. |
metadata | Depends on the method | JSON object containing the settings described below. Send the method explicitly, even where a default exists. |
description belongs in metadata.description; the top-level description field is not used. Put your own reconciliation data in metadata.custom, rather than inventing additional payment settings.
Webframe
Webframe is a checkout page hosted by the payment provider. Your application creates the checkout and opens the returned URL for the customer. The customer enters or approves their payment details on that page, using the options enabled for your merchant.
When to use it: You want to offer a provider-hosted payment screen instead of building the payment-entry screen yourself. For example, an online shop can open Webframe after the customer confirms their basket.
How It Works
- Your application creates the checkout and receives a payment URL.
- The customer opens the page and completes the provider’s payment steps.
- Your application checks the resulting payment status before confirming the order. If the result is an authorization, capture is still needed to collect the reserved funds.
Request Settings
Use paymentType: GPO and metadata.paymentMethod: webframe when the customer should complete checkout on the provider's hosted page. A successful creation returns status: Pending and paymentUrl. Open that URL for the customer and track the payment afterward; creating the checkout page does not confirm payment.
| Metadata field | Required? | Meaning / default |
|---|---|---|
paymentMethod | Send webframe | This is also the connector's fallback when the method is omitted or unrecognized. Use the exact spelling to avoid selecting the wrong flow. |
qrCode | No | Webframe QR Code setting. Default: DISABLED. |
mobile | No | Webframe mobile setting. Default: AUTHORIZATION. |
card | No | Webframe card setting. Default: AUTHORIZATION. |
cssUrl | No | URL of the stylesheet passed to the Webframe provider. |
The three checkout settings are forwarded to the provider. Use the values agreed for your merchant configuration; the gateway does not validate a list of alternatives. If the checkout results in an authorization, reserve-versus-capture handling still applies.
One-Time Purchase
A one-time purchase is a payment for one specific sale, such as buying a product or paying an invoice. The customer approves that payment, and a successful result means the amount has been collected. It does not set up a subscription or permission to charge the customer again.
When to use it: You already know the amount and are ready to collect it now. For example, a customer confirms an order and approves its payment on their phone. A separate authorization-and-capture flow is useful when you need to reserve funds before deciding to collect them.
How It Works
- Your application sends the sale amount and the customer’s payment-enabled mobile number.
- The customer receives the payment request on their phone and follows the approval steps.
- Your application checks the result.
Completedmeans the sale was paid;PendingorProcessingneeds further tracking. There is no separate capture request for a successful one-time purchase.
Request Settings
Use metadata.paymentMethod: onetimepurchase to request a direct payment. In the mobile flow, the customer receives the payment request on their phone. This flow collects the funds without a subsequent capture request.
| Metadata field | Required? | Meaning / default |
|---|---|---|
paymentMethod | Yes for this flow | onetimepurchase. |
phoneNumber | Supply for mobile payment | Customer's payment-enabled mobile number, as a string. There is no default. |
provider | Optional at the gateway | Provider configured for the customer's mobile payment. If omitted, an empty value is forwarded; use the provider value agreed during onboarding. |
The connector removes non-alphanumeric characters from reference before sending it to the provider. Prefer an alphanumeric reference to keep reconciliation straightforward.
The JSON response contains internalId, providerId, reference, status, createdAt, and optional errorCode / errorMessage. Confirm status: Completed before treating the order as paid. A pending or processing result needs a later status lookup; a failed result must be handled as a failed payment.
Authorize Funds
An authorization reserves an amount for a possible later payment. It lets you check that funds can be reserved while you decide whether to complete the sale. The reservation and the collection are separate operations: approval of the reservation does not mean you have collected the money.
When to use it: You need to confirm something before charging—for example, whether an item is available. Once you are ready to complete the order, capture the authorization. If the order will not proceed, cancel the unused authorization.
How It Works
- Request authorization for the amount you want to reserve.
- After approval, save the authorization ID and the gateway’s internal payment ID.
- Capture the reservation to collect the funds, or cancel it to release the unused reservation.
Request Settings
Use metadata.paymentMethod: authorization when you need to reserve funds now and collect them later—for example, after confirming an order.
Reserved is not paid
An approved authorization is a reservation, not a completed payment.
| Metadata field | Required? | Meaning |
|---|---|---|
paymentMethod | Yes for this flow | authorization. |
phoneNumber | Supply for mobile authorization | Customer's payment-enabled mobile number. |
provider | Optional at the gateway | Same provider setting as the one-time purchase mobile flow. |
Send the amount you want to reserve. On approval, the response has status: Authorized and a top-level authorizationId. Save both that ID and internalId: capture uses authorizationId, while cancellation uses the authorization's internalId. providerId identifies the provider authorization; it is separate from the internal GUID.
To release an unused reservation, call POST /api/payments/{internalPaymentId}/cancel. To debit it, follow the next section. Authorization failures expose errorCode and errorMessage at the top level of the JSON response.
Capture an Authorization
Capture is the step that collects money from a previously approved authorization. It completes the reserve-now, collect-later flow. A capture refers to the existing reservation; it does not ask the customer to start a new mobile purchase.
When to use it: You already have an approved authorization and are now ready to complete the sale. For example, after confirming that an ordered item is available, you capture the reserved amount.
How It Works
- Reserve. Send an authorization request and confirm
status: Authorized. Save itsauthorizationId. - Capture. Send a new request with
paymentMethod: capture, the saved authorization ID, and the amount to collect. - Confirm. Check
status: Completedand store the capture’s owninternalIdfor reconciliation.
Request Settings
Send a new request to POST /api/payments using the merchant token for the same point of sale.
| Field | Required? | Value to send |
|---|---|---|
paymentType | Yes | GPO. |
reference | Yes | Your reference for this capture operation. |
amount | Yes | Amount to collect from the reservation. Provider authorization rules determine whether the capture is accepted. |
currency | No; recommended | AOA (also the default). |
metadata.paymentMethod | Yes | capture. |
metadata.authorizationId | Yes | The top-level authorizationId saved from the approved authorization response. Do not substitute internalId. |
You do not need to send the phone number again. Select GPO Capture in the request example selector to see the complete body.
A successful capture returns status: Completed, its own provider id, and its own internalId. Save the capture's internalId for payment lookups. A failed capture returns status: Failed; inspect additionalData.errorCode and additionalData.errorMessage. GPO_MISSING_AUTH_ID means the authorization ID was missing or empty.
Check the payment status
HTTP 201 alone does not prove that funds were collected.
QR Code and Deep Link
A QR Code payment lets the customer open a payment by scanning the QR Code image with the Multicaixa Express app.
A Deep Link is a clickable link that opens that payment in the app, which is useful when the customer is already using a phone.
Both help the customer reach the payment; neither confirms that they have paid.
When to use it: Display a QR Code for the customer to scan, or offer a Deep Link to open Multicaixa Express directly from a mobile checkout. Both flows use POST /api/payments with metadata.paymentMethod: qrcode.
How QR Code Payments Work
- Create the QR Code. Send the payment request with
metadata.includeDeepLinkomitted or set tofalse. A successful response contains the QR Code image as PNG bytes. - Display the image. Show the QR Code at checkout so the customer can scan it.
- The customer approves. The customer scans the QR Code image with Multicaixa Express and completes the payment in the app.
- Confirm payment. Receive the payment notification and check the payment status before fulfilling the order. Displaying or scanning the QR Code is not proof of payment.
How Deep Link Payments Work
- Request a Deep Link. Send the payment request with
metadata.includeDeepLink: true. A successful JSON response includesdeepLinkandqrCodeBase64. - Offer a payment button. Use the returned
deepLinkas the destination of a button such as Pay with Multicaixa Express. Use the link exactly as returned. - The customer approves. Tapping the button opens the payment in Multicaixa Express, where the customer completes it. No QR Code scan is needed.
- Confirm payment. Receive the payment notification and check the payment status before fulfilling the order. Opening Multicaixa Express is not proof of payment.
Request Settings
Use metadata.paymentMethod: qrcode to create a payment the customer can scan. Send an alphanumeric reference of at most 5 characters. The connector strips punctuation before checking this limit.
| Metadata field | Required? | Meaning / default |
|---|---|---|
paymentMethod | Yes for this flow | qrcode. |
description | No | Text associated with the QR Code payment. Defaults to reference. |
qrSize | No | Image size requested from the provider. Default: MEDIUM. |
qrType | No | QR Code behavior passed to the provider. Default: STATIC. |
maxTransactions | No | Number of payments the QR Code may accept. Default: 1; send a positive integer. |
endDate | No | Expiry timestamp in ISO 8601 format with a timezone. Defaults to 24 hours after creation. |
includeDeepLink | No | Boolean, default false. Set true to receive JSON containing both the QR Code image and an app-opening link. Only supported for GPO qrcode. |
Choose the response format
By default, successful QR Code creation returns HTTP 200 with raw image/png bytes. Display those bytes as an image; do not parse that response as JSON. With includeDeepLink: true, successful creation returns HTTP 201 JSON with qrCodeBase64, deepLink, id, internalId, and status. Decode the Base64 image or use data:image/png;base64, when displaying it. Open the returned deepLink as provided; do not construct it from a reference.
The initial payment is Pending. Neither displaying the QR Code image nor opening the app confirms payment. Process the QR Code webhook and check the payment status before fulfilling the order. Failed QR Code creation can return JSON even when you requested an image, so inspect the HTTP status and content type first.
Dynamic Reference
A Dynamic Reference is a payment instruction for a fixed amount. The customer receives an entity number, a reference number, the amount due, and an expiry date. They use those details in a supported payment channel to pay the merchant; creating the reference itself does not move money.
When to use it: You want to collect a specific invoice or order amount and let the customer pay using an entity and reference. For example, issue a reference for an unpaid invoice and show its payment details on the invoice page.
How It Works
- Create the reference for the amount due.
- Show the returned entity, reference, amount, and expiry to the customer.
- Wait for the payment notification, then identify and confirm the individual payment.
Request Settings
Use paymentType: PPR and metadata.referenceType: Dynamic for a fixed-amount payment. The customer pays using an entity number and a reference number. Creating a reference makes payment possible; it does not debit the customer.
Send a positive amount. Omit reference (or send an empty string) to generate a 9-digit reference, or supply a string containing 9–15 digits. Preserve leading zeros. A custom Dynamic reference already active and unpaid for the entity cannot be created again as a new reference.
The response contains the reference record's id, entity, reference, amount, currency, status, createdAt, expiresAt, and customer information. Give the customer the returned entity, reference, amount, and expiry. Confirm collection through the PPR webhook and subsequent payment lookup.
Charging Reference
A Charging Reference is a reusable payment reference. The customer can make separate payments using the same entity and reference, and each collection is a separate transaction. With an open amount, the customer chooses how much to pay each time.
When to use it: You want a customer to keep one reference for repeated payments—for example, voluntary account top-ups. The reference does not automatically debit the customer or schedule recurring charges; each payment must still be initiated.
How It Works
- Create the reusable reference and give the customer its entity and reference number.
- The customer uses those details whenever they want to make a payment.
- Reconcile each payment separately. The reference can remain active after one payment, so check the transaction’s status rather than treating the reference as a single completed sale.
Request Settings
Use metadata.referenceType: Charging for a reusable reference that can receive multiple payments. Send amount: 0 when the customer should enter the amount. A positive amount is also accepted. The same optional reference-number rules apply as for Dynamic references.
A Charging reference can remain active after money has been collected. Track each transaction, rather than interpreting the reference's status as the status of every collection. Use GET /api/payments with paymentType=PPR and search to find its payments; compare returned references for an exact match. Use each payment's internalId to retrieve its status. When enabled, the PPR attempts endpoint also shows failed and unconfirmed attempts.
Optional Metadata
These settings apply to both Dynamic and Charging requests through POST /api/payments.
| Metadata field | Required? | Meaning / default |
|---|---|---|
referenceType | Send explicitly | Dynamic or Charging. Default: Dynamic. The merchant must have access to the chosen type. |
expiryDate | No | ISO 8601 expiry. Default: one month after creation for Dynamic; end of 2099 for Charging. |
description | No | Reason or label for the reference. |
customerEmail | No | Customer email stored with the reference. |
customerName | No | Customer name stored with the reference. |
customerTelephone | No | Customer telephone included in the payment's customer information. |
documentNumber | No | Customer document identifier stored with payment details. |
custom | No | Your own JSON object for reconciliation, described below. |
The dedicated POST /api/references/ppr endpoint is another way to create a reference. Its reference settings are top-level fields and it uses customMetadata, rather than metadata.custom. Follow that endpoint's request schema when using it.
Shared Metadata and Retries
| Metadata field | Required? | Meaning |
|---|---|---|
custom | No | Merchant-defined JSON object, such as an order ID or invoice label. It does not change payment processing. Retrieve it as customMetadata in payment detail and list responses. Compact mobile/authorization creation responses do not include it. |
idempotencyKey | No | String identifying one creation operation for this merchant. Reuse it when retrying that operation. Use a different key for a different operation, including a capture after an authorization. |
The gateway returns an existing payment when it finds the same merchant and idempotency key; it does not compare the new payload against the original request. Keep all payment details unchanged on a retry. PPR requests with an explicit reference also derive a key from merchant, reference, and amount when no key is supplied. A replay may have fewer creation-specific fields, so retain the original response and its identifiers.
For QR Code Deep Link requests, replaying a payment that has no stored Deep Link can return 409 with GPO_DEEP_LINK_UNAVAILABLE. A new key is appropriate only when you intend to create a new payment.
Direct Card Input
The one-time purchase and authorization connectors can also read metadata.cardNumber, metadata.expiryDate, metadata.cvv, and metadata.cardholderName when cardNumber is present. These represent the card number, provider-format expiry, security code, and cardholder name. They are not required for the mobile flows above. Use direct card input only as part of an integration agreed with IZI Pay; gateway validation does not define the provider's accepted card formats. Webframe collects payment details on the provider page instead.
Read the Result Before Fulfilling the Order
| Result | Meaning | Next step |
|---|---|---|
Pending / Processing | Payment is not yet confirmed. | Await notification or look up the payment. |
Authorized | Funds are reserved. | Capture to collect, or cancel the authorization. |
Completed | The payment operation completed. | Reconcile its identifiers and amount. |
Failed | The operation failed. | Read the method-specific error fields before deciding how to retry. |
Save your reference alongside the gateway identifiers. Use internalId for individual payment lookups. The compact PPR creation response's id identifies a reference record, so obtain individual collection IDs from the payments list. The request and response examples remain available on the right; choose the matching method and response status.
Create a Payment › Request Body
amountPayment amount expressed in the selected currency. Decimals are supported.
For GPO and PPR with metadata.referenceType: Dynamic, the amount must be between 0.01 and 10,000,000. For a PPR charging reference, use 0 for an open amount that the customer enters when paying; a positive amount is also accepted. Negative values are never allowed.
paymentTypePayment rail to use. GPO creates a mobile money, authorization, or QR Code payment; PPR creates a payment reference.
currency^[A-Z]{3}$Three-letter uppercase ISO-style currency code. Use AOA for kwanza payments.
referenceRequired for GPO; optional for PPR. Maximum 100 characters at the gateway. QR Code: use 1–5 alphanumeric characters. PPR: omit to generate a 9-digit reference, or send 9–15 digits as a string. Keep leading zeros. One-time purchase strips non-alphanumeric characters before sending the reference to the provider.
Method-specific settings. Follow the required/optional field tables in the method guide above. Use metadata.custom for your reconciliation data. The detail and list responses expose it as customMetadata; compact one-time purchase and authorization creation responses do not include it.
descriptionNot read by the current endpoint. Use metadata.description.
Create a Payment › Responses
QR Code image returned for QR Code payment creation.
Cancel Authorization
Release funds reserved by a GPO authorization that should not be captured. Put the authorization’s internalId GUID in the path, not its authorizationId. Send the merchant bearer token; no request body is needed. On success, check success: true and save cancellationId when returned. A rejected cancellation returns HTTP 400 with errorCode, errorMessage, and errorType. This endpoint is for authorizations; it is not a refund of a completed payment.
path Parameters
internalPaymentIdInternal payment GUID.
Cancel Authorization › Responses
Authorization canceled.
successcancellationIderrorCodeerrorMessageerrorType