Skip to main content
The customer lifecycle in Paygentic involves creating customer relationships, establishing subscriptions, and tracking usage. This guide covers the programmatic approach to managing customers through the API.

Overview

Paygentic supports two distinct types of consumer accounts, each with different capabilities and use cases:

Managed Consumers

Created via API by merchants for quick onboarding. Customers only access Paygentic in relation to this one merchant. These customers do not have Paygentic users and only use Paygentic through the merchant integration.

Full Consumer Accounts

When the customer interacts with multiple merchants they can choose to keep everything in one account and sign in to Paygentic to manage their usage.
Customers usually start as managed and only transition to a full account when needed. The key point for you is that funds in a managed account are exclusively available to your merchant integration.

Creating customers via API

Prerequisites

  • Valid merchant API key
  • Merchant account ID
  • Customer email and preferable address
API Reference: See the Create Customer API endpoint for complete request and response schemas.
When creating a new customer with consumer data, you’re establishing a managed consumer account:
Idempotency: If a customer already exists for the consumer-merchant pair, the API returns 200 with the existing customer ID instead of creating a duplicate.

Creating subscriptions

Once you have a customer, you can create subscriptions. The plan you choose determines which fees and usage-based prices apply. Customers must pay prepaid fees before the subscription starts. The subscription response includes a payment link where the customer can pay for this charge.
API Reference: See the Create Subscription API endpoint for complete request and response schemas.

Starting a subscription in the past

You can set startedAt to a date in the past, for example when you move a customer from another billing system or bill a customer for time they already used. A start is backdated when startedAt is more than 24 hours before you create the subscription. For a backdated start, elapsedPeriodBilling decides what Paygentic bills for the periods that have already passed: elapsedPeriodBilling has no effect on a start that isn’t backdated. A subscription that starts less than 24 hours ago, or in the future, bills from startedAt with either value, so you can send the field on every request.

Example

You create a subscription on 7 October with startedAt set to 10 August. The plan bills monthly, with a fee charged in advance and a fee charged in arrears. The in-advance fee for each period falls due at the start of the period, and the in-arrears fee falls due at the end. With none, the in-arrears fee for 10 September to 10 October is billed in full, because it falls due after you created the subscription. Paygentic doesn’t prorate it. If the other system already billed the customer for part of that period, take this into account. With per_period, Invoice 0 is due after the subscription’s payment term, paymentTermDays, counted from the day you create the subscription. If you also set activateImmediately to true, the subscription is active immediately, and Paygentic still issues Invoice 0.

Usage in elapsed periods

The elapsed periods of a backdated start bill fees only, with either elapsedPeriodBilling value. The period you create the subscription in bills usage in one of two ways:
  • A price with a metered feature counts usage from the moment you create the subscription. Earlier usage in the period is never billed and never draws down the allowance. See Usage dated in the past.
  • A usage price without a metered feature reads the meter for the whole period, so usage dated earlier in the period is billed.
To build a history of usage and invoices, for example in the sandbox, start a test clock in the past instead of backdating the subscription. See Simulating time.

Limits

  • With per_period, startedAt can be at most 12 months before you create the subscription. An earlier date returns 400 Bad Request.
  • With none, startedAt can be up to 10 years in the past.
If you set testClockId, Paygentic measures the 24 hours and both limits from the test clock’s time instead of the current time.

The billing start

The subscription response includes two fields: If you send the same create request again while the subscription is active or pending_payment, Paygentic returns the existing subscription. If the new request has a different elapsedPeriodBilling, Paygentic returns 409 Conflict. A request without elapsedPeriodBilling counts as none.

Customer portal

The customer portal allows your customers to view their subscription details, usage metrics, invoices, and manage payment sources - all within a secure, hosted interface.
For managed consumers, generate portal links via the subscription endpoint:
API Reference: See the Generate Portal Link API endpoint for complete request and response schemas.
This provides read-only access to subscription data, source management, and usage tracking.

Embedding the portal

You can embed the customer portal directly into your application, providing a seamless experience without redirecting users away.

Setup requirements

Before embedding:
  1. Domain whitelisting: Contact support@paygentic.io to whitelist your domain(s)
  2. CSP configuration: Add platform.paygentic.io to your CSP frame-src directive:

Implementation

Important:
  • Portal URLs are single-use - generate a fresh URL for each session or page reload
  • The sandbox attribute is required for security
The sandbox attribute is required for security:
  • allow-scripts - Portal functionality
  • allow-same-origin - Communication with your site
  • allow-forms - Form submission
  • allow-popups - 3D Secure authentication
Payment checkout: To collect one-off payments or embed a payment form in your application, see Payment Portal.

Next steps