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.
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.
- New Managed Consumer
- Existing Managed Consumer
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 setstartedAt 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 withstartedAt 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 eitherelapsedPeriodBilling 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.
Limits
- With
per_period,startedAtcan be at most 12 months before you create the subscription. An earlier date returns400 Bad Request. - With
none,startedAtcan be up to 10 years in the past.
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.Generating portal links
- Managed Consumer Portal
- Full Platform Access
For managed consumers, generate portal links via the subscription endpoint:This provides read-only access to subscription data, source management, and usage tracking.
API Reference: See the Generate Portal Link API endpoint for complete request and response schemas.
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:- Domain whitelisting: Contact support@paygentic.io to whitelist your domain(s)
- CSP configuration: Add
platform.paygentic.ioto your CSPframe-srcdirective:
Implementation
Understanding sandbox attributes
Understanding sandbox attributes
The
sandbox attribute is required for security:allow-scripts- Portal functionalityallow-same-origin- Communication with your siteallow-forms- Form submissionallow-popups- 3D Secure authentication
Payment checkout: To collect one-off payments or embed a payment form in your application, see Payment Portal.
Next steps
- Collect one-off charges with the Payments API
- Explore Pricing for billing configuration