***

title: Glossary: Payments & Integration Terms
subtitle: Payment processing and API integration terminology
slug: glossary/payments-integration-terms
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/glossary/llms.txt. For full documentation content, see https://docs.prolifi.io/glossary/llms-full.txt.

This page covers payment processing, API integration, and developer-facing terminology. For other glossary categories, see: [Platform Concepts](/glossary/platform-concepts), [Billing Terms](/glossary/billing-terms), [Pricing & Subscription Terms](/glossary/pricing-subscription-terms), and [Reporting & Global Terms](/glossary/reporting-global-terms).

***

## Payment Terms

***

### Card Updater

**Plain-language definition:** An automated service that keeps customers' saved card details current, even when their card expires or is replaced. Card issuers participate in card updater programs that push new card numbers and expiry dates to merchants automatically, without requiring the customer to manually update their payment method. This significantly reduces involuntary churn from expired cards.

**Technical definition:** A payment ecosystem service (typically provided or facilitated by a payment network — Visa Account Updater, Mastercard Automatic Billing Updater) that propagates card detail changes to merchants who have a stored token. When Prolifi's configured payment gateway supports card updater, updated card credentials are applied to the stored payment method token automatically.

**See also:** [Payment Method](#payment-method), [Involuntary Churn](/glossary/pricing-subscription-terms#involuntary-churn), [Dunning](/glossary/billing-terms#dunning)

***

### Merchant of Record (MOR)

**Plain-language definition:** The legal entity responsible for a transaction from a payment and compliance standpoint. The merchant of record is the entity that appears on the customer's bank statement, is responsible for tax collection and remittance, and handles chargebacks. In complex international deployments, the merchant of record may differ from the entity providing the service.

**Technical definition:** The `OperatingEntity` in Prolifi that is designated as the merchant of record for a given collection country. The MOR designation determines the tax calculation context, the payment gateway routing, and the entity to which revenue is attributed.

**See also:** [Operating Entity](/glossary/platform-concepts#operating-entity), [Collection Country](/glossary/reporting-global-terms#collection-country), [Tax Treatment](/glossary/reporting-global-terms#tax-treatment)

***

### Offline Payment

**Plain-language definition:** A payment made outside of an automated online payment collection channel — for example, a bank transfer, cheque, or cash payment. Prolifi supports recording offline payments against invoices, allowing the invoice to be marked as paid even when the collection did not happen through a connected payment gateway.

**Technical definition:** An offline payment is recorded in Prolifi via a manual payment posting action against an open invoice. The posting records: payment amount, payment date, reference number, payment method type (bank transfer, cheque, etc.), and the user who recorded it. The invoice state transitions to `paid` (or `partial_paid` if the amount is less than the invoice total) upon recording.

**See also:** [Invoice](/glossary/billing-terms#invoice), [Payment Collection](#payment-collection), [Reconciliation](/glossary/reporting-global-terms#reconciliation)

***

### Payment Collection

**Plain-language definition:** The process of actually collecting the money from a customer once an invoice has been generated. Prolifi supports three collection modes: (1) self-collect (you use your own existing payment gateway), (2) collect through Prolifi (Prolifi routes to a connected gateway), and (3) collect through existing channels (for offline or manual collection).

**Technical definition:** The payment collection configuration in Prolifi determines the gateway routing and collection trigger for each invoice. Collection can be: automatic (triggered immediately on invoice finalisation), scheduled (triggered at a defined offset from invoice date), or manual (triggered via explicit API call or UI action). Collection country and operating entity context determine gateway selection in multi-country deployments.

**See also:** [Payment Gateway](#payment-gateway-psp), [Offline Payment](#offline-payment), [Dunning](/glossary/billing-terms#dunning), [Invoice](/glossary/billing-terms#invoice)

***

### Payment Gateway (PSP)

**Plain-language definition:** The technology service that processes payment transactions between your platform and your customers' banks. Common examples include Stripe, Adyen, Braintree, and GoCardless. Prolifi connects to your payment gateway — it does not replace it. The gateway handles the actual movement of money; Prolifi orchestrates when and what to charge.

**Technical definition:** A payment service provider (PSP) integrated with Prolifi via gateway connector configuration. Prolifi supports multiple simultaneous gateway connections, enabling routing by: collection country, payment method type, or entity. Gateway credentials are stored securely and referenced by the collection configuration on each subscription or invoice.

**See also:** [Payment Collection](#payment-collection), [Operating Entity](/glossary/platform-concepts#operating-entity), [Offline Payment](#offline-payment)

***

### Payment Method

**Plain-language definition:** The specific card, bank account, or other instrument that is used to collect payment from a customer. Each customer can have multiple payment methods on file. The payment method is the thing that gets charged when an invoice comes due.

**Technical definition:** A `PaymentMethod` object in Prolifi stores a tokenised reference to a customer's payment instrument. The token is generated by the payment gateway — Prolifi never stores raw card numbers. Payment methods carry: method type (card, bank account, direct debit mandate, wallet), gateway-specific token, last four digits (for display), expiry information (for cards), and default flag.

**See also:** [Payment Gateway](#payment-gateway-psp), [Customer](/glossary/platform-concepts#customer), [Dunning](/glossary/billing-terms#dunning), [Card Updater](#card-updater)

***

### Payment Retry

**Plain-language definition:** An automated attempt to collect payment again after an initial failure. When a payment fails with a soft decline, the failure may be temporary — the customer's card might have had a momentary issue, or there may have been a bank-side fraud flag that clears. Payment retry logic determines when and how often to try again before escalating to the dunning flow.

**Technical definition:** A payment collection attempt made against an invoice that has previously failed, triggered by the dunning configuration schedule. Each retry creates a payment event record in the audit trail. Retry attempts may use the same payment method or, where card updater is active, an updated payment method token.

**See also:** [Dunning](/glossary/billing-terms#dunning), [Soft Decline](#soft-decline), [Smart Retry](#smart-retry), [Involuntary Churn](/glossary/pricing-subscription-terms#involuntary-churn)

***

### Smart Retry

**Plain-language definition:** An intelligent payment retry system that uses data signals to determine the optimal time to retry a failed payment. Rather than retrying at fixed intervals (e.g., every 3 days), smart retry might attempt collection at the time of day when a particular customer's card is most likely to authorise, or after a bank-flagged fraud hold is likely to have cleared. Industry research indicates smart retry can recover a significant proportion of initially failed soft-decline transactions.

**Technical definition:** A retry scheduling algorithm that considers multiple signals when determining retry timing: time of day, day of week, customer's historical payment success patterns, decline reason code, and bank-specific patterns. Smart retry is an enhancement to the base dunning configuration and requires sufficient transaction history to generate meaningful signals.

**See also:** [Payment Retry](#payment-retry), [Dunning](/glossary/billing-terms#dunning), [Soft Decline](#soft-decline), [Involuntary Churn](/glossary/pricing-subscription-terms#involuntary-churn)

***

### Soft Decline

**Plain-language definition:** A temporary payment rejection that may succeed if retried. Common causes include: insufficient funds (which may resolve when the customer gets paid), a temporary bank fraud hold, or a payment processor technical issue. Soft declines are the primary target of dunning and retry logic — because there is a reasonable chance the payment will succeed on a subsequent attempt.

**Technical definition:** A payment processor response code category indicating a transient failure condition. Common soft decline codes include: `insufficient_funds`, `do_not_honor` (when issued by certain card types), `try_again_later`, and `service_not_allowed`. Prolifi dunning logic treats soft declines as retryable and includes them in the retry schedule.

**See also:** [Hard Decline](/glossary/billing-terms#hard-decline), [Payment Retry](#payment-retry), [Dunning](/glossary/billing-terms#dunning), [Smart Retry](#smart-retry)

***

## Integration Terms

***

### API (Application Programming Interface)

**Plain-language definition:** The programmatic interface through which your development team connects your application to Prolifi. Rather than using Prolifi's web interface manually, the API allows your application to create customers, trigger subscriptions, send usage events, and retrieve billing data automatically. Prolifi is API-first — every action available in the interface is also available via the API.

**Technical definition:** Prolifi exposes a RESTful HTTP API that accepts JSON request bodies and returns JSON responses. Authentication is via API key or OAuth 2.0, depending on the integration pattern. All resources (products, subscriptions, invoices, customers, entitlements) are available as API endpoints with standard CRUD operations.

<Tip>
  For a developer-focused introduction to the Prolifi API, see [Developers](/getting-started/developers).
</Tip>

**See also:** [Webhook](#webhook), [SDK](#sdk-software-development-kit), [API Key](#api-key), [OpenAPI](#openapi), [Sandbox](#sandbox)

***

### API Key

**Plain-language definition:** A credential used to authenticate your application's requests to the Prolifi API. Think of it as a password for your application. API keys must be kept secret and should never be exposed in client-side code.

**Technical definition:** A long, randomly generated string that identifies a specific integration context (typically a specific environment — sandbox or production) and grants access to the Prolifi API. API keys are scoped to an account and can be assigned restricted permissions. Keys should be rotated periodically and revoked immediately if compromised.

<Note>
  API keys must be treated as secrets. Never commit them to version control or expose them in client-side code.
</Note>

**See also:** [API](#api-application-programming-interface), [OAuth](#oauth), [Sandbox](#sandbox)

***

### Event

**Plain-language definition:** A record of something that happened in the platform. Prolifi tracks events for every significant action — a subscription was created, an invoice was paid, an entitlement was exhausted, a payment failed. Events form the audit trail and are also the mechanism by which Prolifi communicates with your application via webhooks.

**Technical definition:** An immutable record of a state change in the Prolifi data model. Events carry: event type (e.g., `subscription.activated`, `invoice.paid`), event timestamp, associated object reference, and a payload containing the relevant object state at the time of the event. Events are stored permanently as part of the audit trail and delivered to registered webhook endpoints.

**See also:** [Webhook](#webhook), [Event Stream](#event-stream), [Audit Trail](/glossary/reporting-global-terms#audit-trail)

***

### Event Stream

**Plain-language definition:** The continuous sequence of events emitted by Prolifi as things happen in the platform. Your application can subscribe to this stream via webhooks to stay in sync with billing state changes without having to poll the API repeatedly.

**Technical definition:** The ordered, time-sequenced series of event objects emitted by Prolifi's event bus. Events are delivered to webhook endpoints in near-real-time. The event stream includes all resource lifecycle events, payment events, entitlement events, and system events. Prolifi guarantees at-least-once delivery with idempotency key support for safe deduplication.

**See also:** [Webhook](#webhook), [Event](#event), [Idempotency Key](#idempotency-key)

***

### Idempotency Key

**Plain-language definition:** A unique identifier included with an API request to ensure that if the request is sent more than once (e.g., due to a network retry), the operation is only performed once. This prevents double-charging a customer or creating duplicate records when a request is retried after a timeout.

**Technical definition:** A client-generated unique string passed in the `Idempotency-Key` HTTP header of a write operation (POST, PATCH). Prolifi stores the key and response for a defined window. If the same key is received again within the window, Prolifi returns the original response without re-executing the operation.

**See also:** [API](#api-application-programming-interface), [Event](#event), [Webhook](#webhook)

***

### OAuth

**Plain-language definition:** A standard authentication protocol that allows your application to act on behalf of a user without requiring the user's password. Prolifi supports OAuth for integration patterns where individual user context is required.

**Technical definition:** Prolifi's OAuth 2.0 implementation supports the authorization code flow and client credentials flow. The authorization code flow is used for user-scoped integrations (e.g., connecting a third-party application to a specific Prolifi account). The client credentials flow is used for machine-to-machine integrations.

**See also:** [API Key](#api-key), [API](#api-application-programming-interface)

***

### OpenAPI

**Plain-language definition:** An industry standard format for describing REST APIs. Prolifi's API is described in an OpenAPI specification, which can be imported into tools like Postman or Insomnia to test the API before writing code.

**Technical definition:** A machine-readable API description document conforming to the OpenAPI 3.x standard. The spec defines all endpoints, request/response schemas, authentication methods, and error formats. It is used to auto-generate API reference documentation and can be imported into API client tools.

<Note>
  API Reference documentation and sandbox access are coming soon.
</Note>

**See also:** [API](#api-application-programming-interface), [Sandbox](#sandbox)

***

### Rate Limit

**Plain-language definition:** A cap on how many API requests your application can make in a given time window. Rate limits protect the platform from being overwhelmed by excessive traffic and ensure fair access for all integrations. If your application exceeds the rate limit, requests will be temporarily rejected until the window resets.

**Technical definition:** Prolifi applies rate limits per API key, per time window (typically 60 seconds). The limit varies by plan tier. Rate limit status is communicated via response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After`. A `429 Too Many Requests` response indicates the limit has been exceeded.

**See also:** [API](#api-application-programming-interface), [API Key](#api-key)

***

### Sandbox

**Plain-language definition:** A testing environment that mirrors the production Prolifi platform but uses test data and simulated payment gateways. The sandbox allows your development team to build and test integrations without touching real customer data or real money.

**Technical definition:** An isolated Prolifi environment with a separate set of API credentials, test customer data, and simulated gateway responses. The sandbox supports all API endpoints available in production. Test payment method tokens and test event triggers are documented in the sandbox documentation.

<Note>
  Sandbox environment access and documentation are coming soon.
</Note>

**See also:** [API Key](#api-key), [API](#api-application-programming-interface), [Event](#event)

***

### SDK (Software Development Kit)

**Plain-language definition:** A pre-built code library that makes it easier to integrate with the Prolifi API in your programming language of choice. Instead of writing raw HTTP requests, you call functions and methods provided by the SDK. SDKs are available for the most common programming languages.

**Technical definition:** A language-specific wrapper around the Prolifi REST API that handles authentication, request serialisation, response deserialisation, error handling, and retry logic. SDKs abstract the HTTP layer and allow developers to interact with Prolifi resources as native objects in their language.

<Note>
  SDK documentation is coming soon.
</Note>

**See also:** [API](#api-application-programming-interface), [API Key](#api-key)

***

### Usage Metric

**Plain-language definition:** The specific measurement that Prolifi uses to track and bill a customer's usage. A usage metric might be "API calls made," "gigabytes stored," "messages sent," or "minutes of video processed." Usage metrics connect your platform's activity data to Prolifi's billing engine.

**Technical definition:** A configured measurement definition in Prolifi that specifies: the event type it listens to, the property from that event that contains the usage quantity, the aggregation method (sum, max, last value, percentile), and the billing period over which to aggregate. Usage metrics are linked to pricing plans to connect usage data to billing amounts.

**See also:** [Event](#event), [Usage Tracking](#usage-tracking), [Usage-Based Pricing](/glossary/pricing-subscription-terms#usage-based-pricing), [Value Metric](/glossary/platform-concepts#value-metric)

***

### Usage Tracking

**Plain-language definition:** The process of recording what a customer consumes or does within your product, so that Prolifi can use that data to calculate their bill. Your application sends usage events to Prolifi's API, and Prolifi aggregates them for billing.

**Technical definition:** The pipeline through which your application reports customer consumption to Prolifi. Usage events are submitted via API call or event stream. Each event carries: a customer identifier, the usage metric identifier, the quantity consumed, a timestamp, and optional custom properties. Prolifi aggregates events per usage metric per billing period for invoice calculation.

**See also:** [Usage Metric](#usage-metric), [Event](#event), [Event Stream](#event-stream), [Usage-Based Billing](/glossary/billing-terms#usage-based-billing)

***

### Webhook

**Plain-language definition:** An automated notification that Prolifi sends to your application when something happens on the platform — for example, when an invoice is paid, when a subscription is cancelled, or when a payment fails. Your application listens for these notifications and responds accordingly (for example, updating the customer's access when their payment succeeds).

**Technical definition:** An HTTP POST request sent by Prolifi to a configured endpoint URL in response to a platform event. Webhook payloads are JSON objects containing the event type and the relevant resource state. Prolifi signs webhook payloads with an HMAC signature for authenticity verification. Webhook delivery follows an exponential backoff retry schedule on failure.

**See also:** [Event](#event), [Event Stream](#event-stream), [API](#api-application-programming-interface)