Glossary - Modulus Labs API

Overview

Plain definitions of the terms used across the Modulus APIs. New to payments or new to the Philippine market? Start here.

Money and amounts

Two amount conventions are in use. Check each API’s reference before you send a value.

Term	Meaning
Minor units (Ecom)	Payment Links and Payment Intents take amounts as integers in the currency’s smallest unit, no decimals. For PHP that is centavos: `150000` means PHP 1,500.00.
Major units (QR, Terminal)	The QR and Terminal Gateway APIs take amounts as a decimal in the main unit: `500.00` means PHP 500.00.
Centavo	1/100 of a Philippine peso.
ISO 4217	The currency-code standard. `PHP` is the Philippine peso.

Keys and access

Term	Meaning
`sk_` (secret key)	Server-side key. Creates resources (payment links, payment intents). Never expose it in a browser or mobile app. Newer keys are prefixed `sk_test_` (sandbox) or `sk_live_` (production).
`pk_` (publishable key)	Browser key used by the JavaScript SDK to confirm a payment, scoped to a single intent by its `client_secret`. Safe to ship in your frontend. Prefixed `pk_test_` or `pk_live_`.
Entity hierarchy	Organization levels a key can be scoped to: partner (all merchants and branches under it), merchant (all branches under it), branch (one branch only). Access is restricted to the key’s level.
`merchant_branch_reference_number`	Identifies the branch a resource belongs to. Required for partner- and merchant-scoped keys; branch-scoped keys can omit it.

Ecom concepts

Term	Meaning
Payment link	A shareable hosted checkout URL. Create it server-side, send your customer the `url`, and Modulus hosts the checkout page. See Payment Links.
Payment intent	An amount a customer has agreed to pay, created server-side and confirmed in the browser by the JavaScript SDK. See JavaScript SDK.
`id` vs `client_secret`	The intent `id` is the public identifier (safe in logs, webhooks, dashboards). The `client_secret` is the capability that authorizes confirming that one intent. They are separate on purpose: a value that is widely logged should not also authorize a charge.
`order_reference`	Your own identifier stored on the payment, used to reconcile a payment back to your records.
`idempotency-key`	A client-generated id that lets you safely retry a create request without creating a duplicate. See Authentication.
`administrative_area`	The state or province in a billing address, `{ code, name }` with a short ISO 3166-2 subdivision code (for example `{ "code": "CA", "name": "California" }`). Only required for US, CA, and CN billing addresses; for PH it is not required and is dropped.

Cards and 3D Secure

Term	Meaning
3D Secure (3DS)	An issuer authentication step (an OTP or biometric prompt) that helps confirm the cardholder is genuine.
Challenge	A 3DS flow where the customer must complete a step, such as entering an OTP.
Frictionless	A 3DS flow the issuer approves with no customer interaction.
ECI	Electronic Commerce Indicator. A value returned by 3DS that indicates the authentication outcome and who carries liability for a disputed payment.
PAN	Primary Account Number, the card number itself. With the JavaScript SDK the PAN is entered into Modulus-hosted fields and never touches your page.

Encryption (QR and Webhooks)

Term	Meaning
Encryption Key	A separate key (from your Secret Key) used to encrypt and decrypt JWE payloads in the QR and Webhooks APIs. The Secret Key authenticates requests; the Encryption Key wraps and unwraps payloads.
JWE	JSON Web Encryption. QR and Webhooks carry payloads as a compact JWE inside a `{ "Token": "<JWE>" }` envelope (`alg` `A256KW`, `enc` `A256CBC-HS512`).
Activation code	Identifies one of your sub-merchant accounts. Sent as the `Activation-Code` header on webhook deliveries so you know which account an event belongs to.
`merchantReferenceNumber`	The reference you set when creating a QR. It is echoed in the webhook payload - correlate a payment to your order on this, not on `referenceNumber`.
`webhookAction`	The single event a webhook fires on: `QRPH_SUCCESS` or `QRPH_DECLINED`. Deduplicate deliveries on `(transactionId, webhookAction)`.

Terminals and onboarding

Term	Meaning
`deviceId` vs `connectionId`	On the Terminal Gateway, `deviceId` is a stable identifier that survives reconnects; `connectionId` is the transient per-connection id. Always address terminals by `deviceId`.
Activation code (terminal)	The physical device identifier used to filter terminal transactions in Transaction Reporting.
`onboardingReferenceNumber`	The id returned when a merchant onboarding application is submitted. Poll `/v2/onboard/{ref}/status` with it for the approval result.

Reconciliation

Term	Meaning
`transaction_id`	Modulus reference for a completed payment.
`approval_code`	The issuer’s authorization code for an approved payment.
`reconciliation_id`	Settlement / reconciliation reference used to match a payment to a settlement batch.
`invoice_number`	Modulus invoice number for a payment.