Skip to main content

Checkout Subscription — PIX Automático

The Checkout PIX Automático Subscription 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.

By passing the subscription-specific parameters to the Checkout, our platform will:

  1. Present the enrollment QR Code to the payer.
  2. Register the subscription in the Subscriptions Engine upon confirmation.
  3. Automate subsequent billing cycles according to the configured schedule.
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.

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. epag 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.epag.io/checkout-v0.1.js"></script>

Method I: HTML​

html
<body>
  <epag-checkout
    amount="15.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-end-date=""
    subscription-force-work-day="false"
    subscription-initial-charge="true"
    subscription-merchant-initiation="false"
    subscription-notification-url="https://my.notification.url/subscription"
    subscription-description="My Subscription"
    subscription-minimum-amount="0.01">
  </epag-checkout>
</body>

Method II: JavaScript​

javascript
const ePagCheckout = new EPagCheckout({
  amount: 15.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,
});

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

Redirect Checkout​

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

POST https://api-sandbox.epag.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": "My Subscription"
}

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 PIX Automático recurring payment. They are passed alongside the standard Checkout parameters.

HTML AttributeJS PropTypeRequiredDefaultDescription
subscriptionsubscriptionbooleanyesfalseSet to true to enable the subscription enrollment flow.
subscription-schemesubscriptionSchemestringyesn/aThe subscription payment scheme. Value: PIX_AUTOMATICO.
subscription-retry-policysubscriptionRetryPolicystringyesn/aRetry/dunning policy for failed charges. Values: NOT_ALLOW, ALLOW_3_RETRIES_7_DAYS.
subscription-amount-typesubscriptionAmountTypestringyesn/aDefines whether the recurring amount is fixed or variable. Values: FIXED, VARIABLE.
subscription-periodicitysubscriptionPeriodicitystringyesn/aBilling frequency. Values: WEEKLY, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY.
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. Must be at least Today + 2 days due to PIX Automático scheduling windows.
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.
subscription-initial-chargesubscriptionInitialChargebooleannofalseIf true, bundles an immediate first charge into the enrollment QR Code.
subscription-merchant-initiationsubscriptionMerchantInitiationbooleanyes*falseIf false, the Billing Engine drives the lifecycle automatically (recommended for FIXED amounts). If true, the merchant is responsible for triggering each billing cycle. Required when subscriptionAmountType is FIXED
subscription-notification-urlsubscriptionNotificationUrlstringnon/aURL to receive webhook callbacks for subscription lifecycle events (enrollment, status changes).
subscription-descriptionsubscriptionDescriptionstringnon/aDescription shown on the payer's bank statement for the recurring charges.
subscription-minimum-amountsubscriptionMinimumAmountnumbernon/aMinimum charge amount allowed for variable subscriptions.
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).

Retry Policy Reference​

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

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 PIX Automático Subscription through the Checkout widget:

Event NameWhen
checkout-successEmitted when the enrollment QR Code is successfully confirmed by the payer.
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.
pix-copyEmitted when the payer copies the PIX/enrollment code.
pix-complete-purchaseEmitted when the payer clicks the complete button after scanning.

Handling Events​

javascript
const ePagCheckout = new EPagCheckout({ /* ... */ });

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

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