Subscription

Create a new subscription

Creates a new subscription for recurring payments. Supports two authorization journeys: BACKGROUND (push notification) and USER_INTERACTION (QR code scan).

post/v1/subscriptions

Request

Base URL
https://api.payretailers.com
URL
https://api.payretailers.com/v1/subscriptions
Auth
HTTP basic

Request body

subscriptionProductIdstring uuid nullable

ID of a pre-configured subscription product. If provided, inherits product configuration.

channelstring required

Payment channel/method. Valid values: PIX (PIX Automatic), WALLET (coming soon), SPEI (coming soon).

authorizationTypestring required

Authorization type. Valid values: BACKGROUND (Journey 1 - push notification, requires authorizationDetails), USER_INTERACTION (Journey 2 - QR code scan). INITIAL_PAYMENT (Journey 3 - Subscription and a First Immediate Payment)

frequencystring required

Payment frequency. Valid values: WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL.

startDatestring date-time nullable

Subscription start date in ISO 8601 format

expirationDatestring date-time nullable

Subscription expiration date in ISO 8601 format

authorizationExpirationTimeinteger nullable

Optional. Time window in minutes the customer has to authorize the mandate before the subscription is transitioned to EXPIRED. If omitted, defaults to 2880 minutes (48 hours). The value is persisted on the subscription and propagated to the PSP integration so the deadline is enforced end-to-end.

notificationUrlstring uri required

Webhook URL for receiving subscription and payment events. Must be HTTPS.

countrystring required

ISO country code (2 characters)

automaticScheduleAllowedboolean

Whether payments should be automatically scheduled

descriptionstring nullable

Description of the subscription

languagestring required

ISO language code (2 characters)

internalReferenceIdstring required

Your internal reference ID for this subscription. Required — used for correlation across webhooks, reporting and reconciliation. Max length: 50 characters.

metadataobject nullable

Custom metadata key-value pairs

Example request

{
  "customer": {
    "customerUniqueIdentifier": "customer-123",
    "authorizationDetails": {
      "bankAccount": "12345",
      "bankCode": "001",
      "accountType": "CHECKING"
    }
  },
  "channel": "PIX",
  "authorizationType": "BACKGROUND",
  "frequency": "MONTHLY",
  "retryPolicy": {
    "type": "PIX_SPECIFIC",
    "maxRetries": 5,
    "retryIntervalDays": 2
  },
  "initialPayment": {
    "description": "Initial payment description.",
    "amount": 10000,
    "expiration": 86400
  },
  "startDate": "2025-02-01T00:00:00Z",
  "expirationDate": "2025-12-31T23:59:59Z",
  "authorizationExpirationTime": 2880,
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "minValue": 5000,
    "maxValue": 50000,
    "currency": "BRL"
  },
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt",
  "internalReferenceId": "MERCHANT-REF-123"
}

Response

Subscription created successfully

subscriptionIdstring uuid

Unique identifier for the created subscription

subscriptionPaymentIdstring uuid

Unique identifier for the created initial payment/transaction, this ID corresponds with the transaction ID

statusstring

Initial subscription status

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.