Skip to main content

Subscriptions Checkout

The Subscriptions Checkout allows you to initiate a recurring payment agreement directly through our Checkout solution — either embedded (JavaScript widget) or via Redirect Checkout — without the need to call the Subscriptions API directly.

We currently support two subscription schemes through Checkout:

SchemeRegionDescription
PIX_AUTOMATICOBrazilRecurring PIX enrollment via QR Code authorization.
CARDMultiple CountriesCard-based recurring billing using tokenized cards.
Learn more

For a deep dive into the full subscription lifecycle, status transitions, orchestration models, and dunning logic, refer to the Subscriptions Documentation. For PIX Automático-specific rules and scheduling windows, see PIX Automático. For Card-specific rules, see Card Subscriptions.

Reference Checkout UI​

Reference UI - Subscription Checkout - PIX Automático - Part 1Reference UI - Subscription Checkout - PIX Automático - Part 1Reference UI - Subscription Checkout - PIX Automático - Part 2Reference UI - Subscription Checkout - PIX Automático - Part 2

Flow​

Step-by-step​

  1. Merchant initiates the Checkout solution with method: "PIX" and subscription: true.
  2. The enrollment QR Code is presented to the customer.
  3. Customer scans the QR Code and confirms the recurring payment authorization in their banking app.
  4. letpay registers the subscription and notifies the merchant via the subscriptionNotificationUrl.
  5. The Billing Engine automatically generates and processes charges according to the configured subscriptionPeriodicity.

Frontend Integration​

Include our JavaScript library in the <head> section of your HTML:

html
<script src="https://checkout-sandbox.letpay.io/checkout-v0.1.js"></script>

Method I: HTML​

html
<body>
  <letpay-checkout
    amount="10.00"
    asset="BRL"
    reference-id="MY_REFERENCE_ID"
    contract-id="MY_CONTRACT_ID"
    subscription="true"
    subscription-scheme="PIX_AUTOMATICO"
    subscription-retry-policy="NOT_ALLOW"
    subscription-amount-type="FIXED"
    subscription-periodicity="WEEKLY"
    subscription-amount="15.00"
    subscription-asset="BRL"
    subscription-due-date="2026-02-18"
    subscription-initial-charge="true"
    subscription-merchant-initiation="false"
    subscription-notification-url="https://my.notification.url/subscription"
    subscription-description="Music Streaming Service"
    subscription-minimum-amount="0.01">
  </letpay-checkout>
</body>

Method II: JavaScript​

javascript
const letpayCheckout = new LetPayCheckout({
  amount: 10.00,
  asset: "BRL",
  referenceId: "MY_REFERENCE_ID",
  contractId: "MY_CONTRACT_ID",
  subscription: true,
  subscriptionScheme: "PIX_AUTOMATICO",
  subscriptionRetryPolicy: "NOT_ALLOW",
  subscriptionAmountType: "FIXED",
  subscriptionPeriodicity: "WEEKLY",
  subscriptionAmount: 15.00,
  subscriptionAsset: "BRL",
  subscriptionDueDate: "2026-02-18",
  subscriptionEndDate: null,
  subscriptionForceWorkDay: false,
  subscriptionInitialCharge: true,
  subscriptionMerchantInitiation: false,
  subscriptionNotificationUrl: "https://my.notification.url/subscription",
  subscriptionDescription: "My Subscription",
  subscriptionMinimumAmount: 0.01,
});

letpayCheckout.mountIn('#checkout-container-element');

Redirect Checkout​

You can also create a subscription via the Redirect Checkout endpoint, which generates a hosted checkout URL with the subscription parameters.

POST https://api-sandbox.letpay.io/checkout/generate

Authorization​

HeaderValue
X-Auth-TokenMY_ACCESS_TOKEN

Example Request​

Request​

Body
{
  "contractId": "MY_CONTRACT_ID",
  "paymentCountry": "BR",
  "paymentCurrency": "BRL",
  "notificationUrl": "https://my.notification.url/payment",
  "subscription": true,
  "subscriptionScheme": "PIX_AUTOMATICO",
  "subscriptionRetryPolicy": "NOT_ALLOW",
  "subscriptionAmountType": "FIXED",
  "subscriptionPeriodicity": "WEEKLY",
  "subscriptionAmount": 15.00,
  "subscriptionAsset": "BRL",
  "subscriptionDueDate": "2026-02-18",
  "subscriptionEndDate": null,
  "subscriptionForceWorkDay": false,
  "subscriptionInitialCharge": false,
  "subscriptionMerchantInitiation": false,
  "subscriptionNotificationUrl": "https://my.notification.url/subscription",
  "subscriptionDescription": "Music Streaming Service"
}

Response​

200 OK
{
  "url": "MY_CHECKOUT_URL",
  "expires_at": "2026-02-16T10:00:00.000",
  "refresh_token": "MY_ACCESS_TOKEN"
}

Configuration Options​

Subscription Parameters​

The following parameters activate and configure the recurring payment. They are passed alongside the standard Checkout parameters.

Override Amount Best Practices

The subscriptionAmountType field drives a key architectural decision. Choosing FIXED vs. VARIABLE has direct UX and conversion implications beyond the technical setup. Before going live, review Override Amount for scenario guidance, FX caveats, and merchant communication templates.

HTML AttributeJS PropTypeRequiredDefaultDescription
assetassetstringnon/aReference code for initial charge's asset.
amountamountnumbernon/aTotal amount of the initial charge. Value must have a maximum of two decimal places.
notification-urlnotificationUrlstringnon/aURL to receive webhook callbacks for payment lifecycle events.
subscriptionsubscriptionbooleanyesfalseSet to true to enable the subscription enrollment flow.
subscription-schemesubscriptionSchemestringyesn/aThe subscription payment scheme. Values: PIX_AUTOMATICO, CARD.
subscription-retry-policysubscriptionRetryPolicystringyesn/aRetry/dunning policy for failed charges. See Retry Policy Reference below.
subscription-amount-typesubscriptionAmountTypestringyesn/aDefines whether the recurring amount is fixed or variable. Values: FIXED, VARIABLE.
subscription-periodicitysubscriptionPeriodicitystringyesn/aBilling frequency. See Periodicity Reference below.
subscription-amountsubscriptionAmountnumberyes*n/aThe recurring charge value. Required when subscriptionAmountType is FIXED.
subscription-assetsubscriptionAssetstringyes*BRLCurrency asset for the recurring charge (e.g., BRL). Required when subscriptionAmountType is FIXED.
subscription-due-datesubscriptionDueDateYYYY-MM-DDyesn/aThe first due date for the subscription. For PIX Automático, must be at least Today + 2 days.
subscription-end-datesubscriptionEndDateYYYY-MM-DDnonullEnd date of the subscription. Use null for open-ended subscriptions.
subscription-force-work-daysubscriptionForceWorkDaybooleannofalseIf true, adjusts due dates falling on non-business days to the next business day. Currently, only for PIX_AUTOMATICO.
subscription-initial-chargesubscriptionInitialChargebooleannofalseIf true, bundles an immediate first charge into the enrollment. PIX Automático only.
subscription-merchant-initiationsubscriptionMerchantInitiationbooleanyes*falseIf false, the Billing Engine drives the lifecycle automatically. If true, the merchant triggers each billing cycle.
subscription-notification-urlsubscriptionNotificationUrlstringnon/aURL to receive webhook callbacks for subscription lifecycle events.
subscription-descriptionsubscriptionDescriptionstringnon/aDescription shown on the payer's bank statement for the recurring charges. For PIX_AUTOMATICO max 35 characters. For CARD max 16 characters.
subscription-minimum-amountsubscriptionMinimumAmountnumbernon/aMinimum charge amount allowed for variable subscriptions.
PIX Automático Scheduling Constraint

Due to PIX Automático's mandatory 8-day scheduling window, subscriptionDueDate must be set to at least 2 days after the current date (Today + 2).

Periodicity Reference​

ValuePIX AutomáticoCards
DAILY❌✅
WEEKLY✅✅
BI_WEEKLY❌✅
MONTHLY✅✅
QUARTERLY✅✅
HALF_YEARLY✅✅
YEARLY✅✅
CUSTOM❌✅

Retry Policy Reference​

CodeValueDescription
001NOT_ALLOWNo retries. A single charge attempt is made on the due date.
002ALLOW_3_RETRIES_7_DAYSUp to 3 retry attempts within a 7-day window after the initial failure.
Info

Both the Code and the Name can be informed on the request.

Orchestration Models​

subscriptionMerchantInitiationModelBest For
falseEngine-Driven — The Billing Engine automatically schedules and executes all recurring charges.Standard plans with FIXED amounts (e.g., memberships, SaaS).
trueMerchant-Driven — The merchant must trigger each billing cycle via the Create Charge API.Variable-amount billing or custom scheduling needs.

Events​

The following events are relevant when integrating Subscriptions through the Checkout widget:

Event NameWhen
checkout-successEmitted when the subscription is successfully created/enrolled.
checkout-readyEmitted when the checkout modal is ready.
checkout-dismissedEmitted when the checkout modal is closed by the user.
checkout-errorEmitted when an unexpected error occurs.

Handling Events​

javascript
const letpayCheckout = new LetpayCheckout({ /* ... */ });

letpayCheckout.on('checkout-success', function(event) {
  const data = event.detail[0];
  console.log('Subscription enrolled! Payment token:', data.payment_token);
});

letpayCheckout.on('checkout-error', function(event) {
  console.error('Enrollment error:', event.detail[0]);
});