Skip to main content

Create Subscription

POST https://api-sandbox.epag.io/subscriptions

This HTTP POST request is used to create a Subscription using the PIX Automático scheme. Depending on the business model (Fixed vs. Variable) and the enrollment strategy (Immediate Payment vs. Enrollment Only), the payload structure varies slightly.

Request Body Parameters​

The request payload includes the following core fields:

  • contract_id (required/string): Merchant's contract id.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this subscription.
  • notification_url (required/string): URL to post callbacks regarding this subscription's status.
  • amount_type (required/enum): Defines the nature of the recurring amount. Values: FIXED or VARIABLE.
  • scheme (required/enum): The payment method. Value: PIX_AUTOMATICO.
  • retry_policy (required/enum): The ID of the retry policy to be applied. Values: NOT_ALLOW, ALLOW_3_RETRIES_7_DAYS.
  • expiration_date (optional/string): Expiration date for the Enrollment QR Code. If not provided, the system defaults to 2 days.
  • merchant_initiation (optional/boolean): Flag to indicate if the merchant controls the billing trigger.
  • schedule (required/object): Defines the recurrence rules:
    • due_date (required/date): The due date of the subscription (YYYY-MM-DD).
    • end_date (optional/date): The end date. Use null for open-ended subscriptions.
    • periodicity (required/enum): Frequency of the cycle. Values: WEEKLY, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY.
    • force_work_day (required/boolean): If true, adjusts dates to business days.
  • payment (required/object): The payment execution data:
    • notification_url (required/string): URL to post callbacks regarding individual payments.
    • country (required/string): Country code (e.g., BR).
    • currency (required/string): Currency code (e.g., BRL).
    • pix (required/object):
      • description (optional/string): Description to appear on the bank statement.
      • tax_id (required/string): The payer's unique tax identifier (CPF/CNPJ).

Scenario-Specific Fields​

Depending on the amount_type and the journey chosen, the following fields apply:

1. For FIXED Amount Subscriptions:​

  • amount (required/float): The recurring charge value.
  • asset (optional/string): Asset code (Default: BRL).

2. For VARIABLE Amount Subscriptions:​

  • Note: The amount and asset fields are omitted at the root level, as the value changes per cycle.

3. For Enrollment with Initial Payment (Bundled):​

  • payment.initial_charge (required/object): Adds an immediate charge to the enrollment flow.
    • due_date (required/date): The due date for the initial charge (YYYY-MM-DD).
    • amount (required/float): The value of the first immediate charge.
    • asset (required/string): Asset code.
    • reference_id (optional/string, max 45 chars): External identifier provided by the merchant to reference the subscription initial charge.

Authorization​

HeaderValue
X-Auth-TokenMY_ACCESS_TOKEN

Body Raw (JSON)​

{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/subscription",
    "amount": "15.00",
    "asset": "BRL",
    "amount_type": "FIXED",
    "minimum_amount": "10.00",
    "schedule": {
        "due_date": "2025-11-23",
        "end_date": null,
        "periodicity": "WEEKLY",
        "force_work_day": false
    },
    "scheme": "PIX_AUTOMATICO",
    "retry_policy": "ALLOW_3_RETRIES_7_DAYS",
    "merchant_initiation": false,
    "expiration_date": "2025-11-25",
    "payment": {
        "initial_charge": {
            "amount": "50.00",
            "asset": "USD"
        },
        "notification_url": "https://my.notification.url/payment",
        "country": "BR",
        "currency": "BRL",
        "pix": {
            "description": "Music Streaming Service",
            "tax_id": "12345678909"
        }
    }
}

Example Request​

Enrollment Without Initial Payment
    curl --location 'https://api-sandbox.epag.io/subscriptions' \
    --data '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/subscription",
        "amount": "15.00",
        "asset": "BRL",
        "amount_type": "FIXED",
        "schedule": {
            "due_date": "2025-11-23",
            "end_date": null,
            "periodicity": "WEEKLY",
            "force_work_day": false
        },
        "scheme": "PIX_AUTOMATICO",
        "retry_policy": "NOT_ALLOW",
        "merchant_initiation": false,
        "expiration_date": "2025-11-25",
        "payment": {
            "notification_url": "https://my.notification.url/payment",
            "country": "BR",
            "currency": "BRL",
            "pix": {
                "description": "Music Streaming Service",
                "tax_id": "12345678909"
            }
        }
    }'

Example Response​

Header
  Content-Type: application/json
200 OK
    {
    "subscription_id": "cc6effd7-2100-47ee-b483-5b4ac719f97d",
    "reference_id": "MY_REFERENCE_ID",
    "status": "PENDING",
    "pix_qr_code": "BASE64_ZIPPED_PNG",
    "pix_code": "00020101021226600016BR.COM.PAGSEGURO013612BB85E0-6156-45D0-BD28-5E04456185FF5204899953039865406123.455802BR5925ELPL Tecnologia em Pagame6009Sao Paulo63047B99",
    "refresh_token": "MY_ACCESS_TOKEN"
    }