ClientCredentialsTokenRequest
grant_typeclient_idclient_secretscopePasswordTokenRequest
grant_typeusernamepasswordscopeclient_idRegisterUserRequest
emailpasswordfirstNamelastNamephoneNumberCustomMetadata
CreatePaymentRequest
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.
GpoPaymentMetadata
paymentMethodGPO flow to start. Use webframe for Webframe, onetimepurchase for an immediate mobile payment, authorization to reserve funds, capture to complete a previous authorization, or qrcode to create a QR Code. Defaults to webframe when omitted or unrecognized.
phoneNumberSupply for mobile one-time purchase and mobile authorization. Customer’s payment-enabled phone number as a string. Not needed for capture, QR Code, or Webframe. No default; provider validation applies.
providerOptional at the gateway for mobile purchase/authorization. Provider assigned for this integration; if omitted, an empty string is forwarded. The gateway does not validate a provider enum.
gpo_merchant_idNormally supplied by the merchant token. The token value overrides request metadata. Required in the resolved GPO context; use only the value assigned during onboarding.
gpo_pos_idNormally supplied by the merchant token. The token value overrides request metadata. Required in the resolved GPO context; use only the value assigned during onboarding.
qrSizeRequested QR Code image size. Used only when paymentMethod is qrcode; defaults to MEDIUM.
qrTypeQR Code behavior. Used only when paymentMethod is qrcode; defaults to STATIC.
maxTransactionsMaximum number of payments accepted by the QR Code. Used only for QR Code payments and defaults to 1.
endDateOptional QR Code expiry in ISO 8601 format. Defaults to 24 hours after creation.
authorizationIdIdentifier returned by a previous authorization. Required when paymentMethod is capture.
descriptionDescription sent to GPO. For QR Code payments, the top-level reference is used when this value is omitted.
Optional merchant-defined JSON object for internal reconciliation data.
The merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or null. IZI Pay does not use these properties to select or configure the GPO payment method.
The object is returned as customMetadata in payment detail and list responses. Do not include credentials, card details, access tokens, or other secrets.
gpo_user_emailNormally supplied by the merchant token. The token value overrides request metadata. Required in the resolved GPO context; use only the value assigned during onboarding.
includeDeepLinkOptional, only for qrcode. true returns HTTP 201 JSON with qrCodeBase64 and deepLink; false returns a PNG image on successful creation. Send a JSON boolean, not a string.
qrCodeOptional Webframe setting, forwarded to the provider. Use values agreed for the merchant configuration.
mobileOptional Webframe setting, forwarded to the provider. Use values agreed for the merchant configuration.
cardOptional Webframe setting, forwarded to the provider. Use values agreed for the merchant configuration.
cssUrlOptional stylesheet URL for Webframe.
cardNumberCard number. Its presence selects card data for purchase/authorization. Not required for mobile flows.
expiryDateCard expiry in the format agreed with the provider. Used with cardNumber; this is not QR Code expiry.
cvvCard security code, used with cardNumber. Provider validation determines requirements.
cardholderNameCardholder name, used with cardNumber. Provider validation determines requirements.
idempotencyKeyOptional merchant-scoped key for retrying one creation operation. Reuse only with the same request details. The gateway returns the existing payment without comparing payloads. Use a different key for a separate operation, including capture.
PprPaymentMetadata
referenceTypePPR reference behavior. Dynamic is a fixed-amount reference and requires amount greater than zero. Charging is reusable and can receive multiple transactions; use amount: 0 when the payer should choose the amount. Defaults to Dynamic when omitted.
expiryDateOptional ISO 8601 expiry date. If omitted, a dynamic reference expires one month after creation and a charging reference defaults to the end of 2099.
descriptionMerchant-facing reason or label for the reference.
customerEmailOptional customer email stored with the reference and returned in the PPR payment response.
customerNameOptional customer name stored with the reference and returned in the PPR payment response.
customerTelephoneOptional customer telephone number returned in the PPR payment response.
documentNumberOptional customer identity document number returned in payment details.
Optional merchant-defined JSON object for linking the PPR payment to your internal records.
The merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or null. These values do not affect the generated entity, reference, amount, expiry, or payment status.
Send this object as metadata.custom when using POST /api/payments. IZI Pay stores it and returns it as the top-level customMetadata property in PPR creation and lookup responses. Do not include credentials, card details, access tokens, or other secrets.
idempotencyKeyOptional merchant-scoped key for retrying one creation operation. Reuse only with the same request details. The gateway returns the existing payment without comparing payloads. Use a different key for a separate operation, including capture.
CreatePprReferenceRequest
reference^[0-9]{9,15}$Optional merchant-defined PPR reference containing 9 to 15 digits. Omit it to generate the reference automatically.
referenceTypeDynamic creates a fixed-amount reference. Charging creates a reusable reference and allows an open amount. Defaults to Dynamic when omitted.
amountRequired and greater than zero for Dynamic; optional for Charging, where 0 represents an open amount.
expiryDateOptional future expiry in ISO 8601 format.
descriptionOptional merchant-facing reason or label for the reference.
customerEmailOptional customer email stored with the reference.
customerNameOptional customer full name stored with the reference.
customerTelephoneOptional customer telephone number stored with the reference.
documentNumberOptional customer identity document number stored with the reference.
Optional merchant-defined JSON object for internal reconciliation and record linking.
This is the direct PPR endpoint form: send customMetadata at the request root for POST /api/references/ppr, /api/references/ppr/legacy, and each item in /api/references/ppr/bulk. Do not wrap it in metadata or custom.
Property names are chosen by the merchant. Values may be strings, numbers, booleans, arrays, nested objects, or null. The values do not affect PPR processing and are returned unchanged as customMetadata in creation, detail, and list responses.
Do not include credentials, card details, access tokens, or other secrets.
CreateBulkPprReferencesRequest
PaymentCreationResponse
idPPR creation returns a reference-record ID here. Other flows can return a provider payment ID. For individual PPR collections, obtain internalId from the payments list.
internalIdInternal payment identifier when included by the selected payment flow.
providerIdProvider identifier returned by the GPO authorization or one-time purchase flow.
authorizationIdFor GPO authorization, this is the provider authorization ID to pass as metadata.authorizationId when capturing. A GPO capture response can also include this field to identify the original authorization.
entityreferenceMerchant/payment reference. For PPR collections, search by this value and use the returned internalId to retrieve an individual payment.
amountcurrencystatuscreatedAtexpiresAtdescriptionA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
paymentUrlHosted checkout URL for a successfully created webframe payment.
qrCodeBase64Base64 PNG image when includeDeepLink is true.
deepLinkProvider payment-app link returned when includeDeepLink is true.
errorCodeTop-level error code in compact one-time purchase or authorization responses.
errorMessageTop-level error message in compact one-time purchase or authorization responses.
Method-specific details. For capture, QR Code, or webframe failures, inspect errorCode and errorMessage here.
PaymentDetailsResponse
idinternalIdmerchantIdreferenceamountcurrencypaymentTypestatuscreatedAtcompletedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
PprReferenceResponse
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
MerchantPprWebhookRequest
idTransacaoTransaction identifier.
numLogSistemaSystem log number associated with the payment notification.
idLogSistemaSystem period/log identifier.
dataTransaccaoClienteDate and time when the customer payment was registered.
montantePagoAmount paid by the customer.
tipoTerminalTerminal type used for the payment.
iIdentTerminalTerminal identifier.
localidadeTerminalTerminal location.
refPagamentoPayment reference paid by the customer.
IdUnique notification identifier. Use this value for idempotency.
nibDebit account NIB, when available.
bancoBank name, when available.
MerchantQrCodeWebhookRequest
creationDateDate and time when the QR Code transaction was created.
updatedDateDate and time when the QR Code transaction status was updated.
idUnique provider transaction identifier. Use this value for idempotency.
amountAmount paid by the customer.
clearingPeriodClearing period associated with the transaction.
transactionNumberProvider transaction number.
statusQR Code payment status.
transactionTypeTransaction type.
orderOriginPayment order origin.
currencyPayment currency.
merchantReferenceNumberMerchant reference number associated with the QR Code payment.
MerchantWebhookResponse
SuccessReturn true when the notification was processed successfully or was already processed before.
ObsShort processing note.
IdMerchant internal payment identifier.
SmsMerchant
merchantIdnomeremetenteSmsSender name configured for SMS messages.
SmsBalance
merchantIdsaldoAtualCurrent available SMS units.
unidadeatualizadoEmSmsBalanceLedgerEntry
idtipoLedger entry type, such as credit or debit.
quantidadesaldoDepoisdescricaocriadoEmSmsTemplate
idnomeconteudocriadoEmatualizadoEmSmsContactRequest
nometelefoneDestination phone number in the format accepted by the SMS service.
SendSmsTemplateRequest
smsIdSMS template identifier.
numerosDestinoremetenteScheduleSmsTextRequest
numerosDestinoconteudodiamesanohoraminuto