Guides
Support
Start typing to search…

Getting Started with Subscriptions

Getting Started with Subscriptions

This guide will walk you through creating your first subscription using the Payments Subscriptions API.

Prerequisites

Before you can create a subscription, ensure you have the following:

1. Customer in Customer Module

The customer must already exist in the Customer Module. You'll need the customer's unique identifier to create a subscription.

{
  "customer": {
    "customerUniqueIdentifier": "customer-123"
  }
}

2. Channel and Country Configuration

The payment channel and country must be configured in the Interoperability API for your shop. This configuration determines which payment methods are available and how they're processed.

3. Webhook URL

Configure a webhook URL where you'll receive notifications about subscription and payment events. This URL must:

  • Be publicly accessible (HTTPS)
  • Accept POST requests
  • Return 200 OK responses
{
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions"
}

4. Authentication

All API requests require Basic Authentication using your shop credentials:

Authorization: Basic {base64(shopId:shopSecretKey)}

Basic Flow

Here's the typical flow for creating and managing a subscription:

Step 1: Create a Subscription Product (Optional but Recommended)

A subscription product is a reusable template that defines common subscription parameters. While optional, using products helps maintain consistency and simplifies management.

POST /v1/subscription-products

Example Request:

{
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "country": "BR",
  "language": "pt",
  "description": "Monthly subscription plan"
}

Response:

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000"
}

Step 2: Create a Subscription

Create a subscription for a customer. You can either use a subscription product or specify all parameters directly.

POST /v1/subscriptions

Example Request (using product):

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "customerUniqueIdentifier": "customer-123"
  },
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "startDate": "2025-02-01T00:00:00Z",
  "expirationDate": "2025-12-31T23:59:59Z"
}

Example Request (without product):

{
  "customer": {
    "customerUniqueIdentifier": "customer-123"
  },
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "automaticScheduleAllowed": true,
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt",
  "startDate": "2025-02-01T00:00:00Z",
  "expirationDate": "2025-12-31T23:59:59Z"
}

Response:

{
  "subscriptionId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING_USER_AUTH"
}

Step 3: User Authorization

The subscription status will be PENDING_USER_AUTH until the user authorizes it. The authorization process depends on the authorizationType:

Background Authorization (Journey 1)

For authorizationType: "BACKGROUND":

  • The system sends an authorization request to the user's bank
  • The bank sends a push notification to the user
  • The user authorizes in their banking app
  • The subscription automatically becomes ACTIVE

Required fields for BACKGROUND:

{
  "authorizationDetails": {
    "bankAccount": "12345",
    "bankCode": "001",
    "accountType": "CHECKING"
  }
}

User Interaction Authorization (Journey 2)

For authorizationType: "USER_INTERACTION":

  • The system generates a QR code
  • The user scans the QR code with their banking app
  • The user authorizes in their banking app
  • The subscription becomes ACTIVE

Response includes checkout information:

{
  "subscriptionId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING_USER_AUTH",
  "checkout": {
    "checkoutUrl": "https://checkout.payretailers.com/qr/...",
    "payload": {
      "code": "00020126580014br.gov.bcb.pix...",
      "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

Checkout fields:

  • checkout.checkoutUrl: URL where user can view QR code (optional)
  • checkout.payload.code: EMV code for "copia e cola" (copy and paste)
  • checkout.payload.image: Base64-encoded QR code image

Step 4: Subscription Activation

Once authorized, the subscription status changes to ACTIVE. You'll receive a webhook notification:

{
  "eventType": "subscription_activation",
  "entityId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "ACTIVE",
  "eventDate": "2025-01-15T10:30:00Z"
}

Step 5: Automatic Payment Processing

If automaticScheduleAllowed: true and amountType: "FIXED":

  • The system automatically creates payments 48 hours before the due date
  • Payments are processed on the scheduled date
  • You'll receive webhook notifications for each payment event

If automaticScheduleAllowed: false or amountType: "VARIABLE":

  • You must manually create each payment using POST /v1/subscription-payments
  • Payments are processed on the scheduled date

Complete Example

Here's a complete example using cURL:

# 1. Create subscription product
curl -X POST https://api.payretailers.com/v1/subscription-products \
  -H "Authorization: Basic {base64(shopId:shopSecretKey)}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "PIX",
    "frequency": "MONTHLY",
    "amount": {
      "type": "FIXED",
      "fixedValue": 10000,
      "currency": "BRL"
    },
    "retryPolicy": {
      "type": "PIX_SPECIFIC"
    },
    "authorizationType": "BACKGROUND",
    "country": "BR",
    "language": "pt",
    "description": "Monthly subscription"
  }'

# 2. Create subscription
curl -X POST https://api.payretailers.com/v1/subscriptions \
  -H "Authorization: Basic {base64(shopId:shopSecretKey)}" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
    "customer": {
      "customerUniqueIdentifier": "customer-123"
    },
    "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
    "startDate": "2025-02-01T00:00:00Z",
    "expirationDate": "2025-12-31T23:59:59Z"
  }'

# 3. Check subscription status
curl -X GET https://api.payretailers.com/v1/subscriptions/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Basic {your-token}"

Next Steps

Now that you've created your first subscription, explore these topics:

For detailed API reference, see the Subscriptions API Reference.

Updated about 8 hours ago