Skip to main content

Create Subscription

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

This HTTP POST request is used to create a Subscription using the Credit Card scheme. Depending on the enrollment strategy (new card vs. existing token) and the amount type (Fixed vs. Variable), 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 (required for FIXED/float): The recurring charge value. Omitted when amount_type is VARIABLE.
  • asset (optional/string): Asset code (Default: BRL). Omitted when amount_type is VARIABLE.
  • amount_type (required/enum): Defines the nature of the recurring amount. Values: FIXED or VARIABLE.
  • scheme (required/enum): The payment method. Value: CREDIT_CARD.
  • retry_policy (required/enum): The ID of the retry policy to be applied. Values: NOT_ALLOW, ALLOW_3_RETRIES_7_DAYS, ALLOW_8DAYS_4, ALLOW_3WEEKS_5, ALLOW_P2_BACKOFF_16, CUSTOM.
  • merchant_initiation (optional/boolean): Flag to indicate if the merchant controls the billing trigger. Required when amount_type is VARIABLE.
  • schedule (required/object): Defines the recurrence rules:
    • due_date (required/date): The due date of the first billing cycle (YYYY-MM-DD).
    • end_date (optional/date): The end date. Use null for open-ended subscriptions.
    • periodicity (required/enum): Frequency of the cycle. Values: DAILY, WEEKLY, BI_WEEKLY, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY, CUSTOM.
    • custom_period (conditional/object): Required when periodicity is CUSTOM.
      • period (required/string): The time unit. Values: "day", "month".
      • count (required/integer): The interval count (e.g., 2 for every 2 months).
    • force_work_day (required/boolean): If true, adjusts due dates to the next business day when they fall on weekends or holidays.
  • 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).
    • card (required/object): Card enrollment data. Use one of the following strategies:
      • New Card (tokenization):
        • holder_name (required/string): Name as printed on the card.
        • number (required/string): Card number (PAN).
        • expiry_month (required/string): Two-digit expiry month (e.g., "12").
        • expiry_year (required/string): Four-digit expiry year (e.g., "2027").
        • cvv (required/string): Card security code.
        • tax_id (required/string): Payer's tax identifier. BR: CPF/CNPJ. LATAM: national ID.
        • first_name (required for LATAM/string): Payer's first name.
        • surname (required for LATAM/string): Payer's last name.
        • email (required for LATAM/string): Payer's email address.
      • Existing Token:
        • public_person_id (required/string): ePag's public identifier for the payer.
        • public_card_id (required/string): ePag's public identifier for the card token.

Scenario-Specific Fields​

1. For FIXED Amount Subscriptions:​

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

2. For VARIABLE Amount Subscriptions:​

  • The amount and asset fields are omitted at the root level, as the value changes per cycle.
  • merchant_initiation must be set to true.

Authorization​

HeaderValue
X-Auth-TokenMY_ACCESS_TOKEN

Body Raw (JSON)​

{
    "contract_id": "{{contractId}}",
    "reference_id": "S-{{$guid}}",
    "notification_url": "{{notificationUrl}}",
    "amount": "15.00",
    "asset": "BRL",
    "amount_type": "FIXED",
    "schedule": {
        "due_date": "2026-03-25",
        "end_date": null,
        "periodicity": "DAILY"
    },
    "scheme": "CARD",
    "retry_policy": "ALLOW_5_RETRIES_3_WEEKS",
    "merchant_initiation": false,
    "payment": {
        "initial_charge": {
            "amount": "88.00",
            "asset": "BRL",
            "reference_id": "IC-{{$guid}}"
        },
        "notification_url": "{{notificationUrl}}",
        "country": "BR",
        "currency": "BRL",
        "card": {
            "number": "{{cardNumber}}",
            "cvv": "{{cardCvv}}",
            "month": "{{cardMonth}}",
            "year": "{{cardYear}}",
            "holder": "{{cardHolder}}",
            "public_person_id": "{{publicPersonId}}",
            "public_card_id": "{{publicCardId}}"
        },
        "person": {
            "tax_id": "{{personTaxId}}",
            // "tax_id_type": "NIT",
            "full_name": "{{personFullName}}",
            "email": "{{personEmail}}"
        }
    }
}

Example Request​

New Card – Fixed Amount
    curl --location 'https://api-sandbox.letpay.io/subscriptions' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --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": "2026-03-25",
                    "end_date": null,
                    "periodicity": "DAILY"
                },
                "scheme": "CARD",
                "retry_policy": "ALLOW_5_RETRIES_3_WEEKS",
                "merchant_initiation": false,
                "payment": {
                    "initial_charge": {
                        "amount": "88.00",
                        "asset": "BRL",
                        "reference_id": "MY_REFERENCE_ID"
                    },
                    "notification_url": "https://my.notification.url/payment",
                    "country": "BR",
                    "currency": "BRL",
                    "card": {
                        "number": "MY_CARD_NUMBER",
                        "cvv": "MY_CARD_CVV",
                        "month": "MY_CARD_MONTH",
                        "year": "MY_CARD_YEAR",
                        "holder": "MY_CARD_HOLDER",
                        "public_person_id": "MY_PUBLIC_PERSON_ID",
                        "public_card_id": "MY_PUBLIC_CARD_ID"
                    },
                    "person": {
                        "tax_id": "MY_PERSON_TAX_ID",
                        // "tax_id_type": "NIT",
                        "full_name": "MY_PERSON_FULL_NAME",
                        "email": "MY_PERSON_EMAIL"
                    }
                }
            }'

Example Response​

Header
  Content-Type: application/json
200 OK
    {
        "subscription_id": "cc6effd7-2100-47ee-b483-5b4ac719f97d",
        "reference_id": "MY_REFERENCE_ID",
        "status": "ACTIVE",
        "refresh_token": "MY_ACCESS_TOKEN"
    }