Sign in

v1

latestOpenAPI 3.1.02026-07-263436159.3 KB
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 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

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 nullable

Your internal reference ID for this subscription

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",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "minValue": 5000,
    "maxValue": 50000,
    "currency": "BRL"
  },
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt"
}

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..."
    }
  }
}