Create a new subscription

post

https://api.payretailers.com/v1/subscriptions

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

subscriptionProductId

uuid | null

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

customer

object

required

channel

string

required

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

authorizationType

string

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)

frequency

string

required

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

retryPolicy

object

required

initialPayment

object

startDate

date-time | null

Subscription start date in ISO 8601 format

expirationDate

date-time | null

Subscription expiration date in ISO 8601 format

authorizationExpirationTime

int32 | null

≥ 1

Defaults to 2880

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.

amount

object

required

notificationUrl

uri

required

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

country

string

required

length between 2 and 2

ISO country code (2 characters)

automaticScheduleAllowed

boolean

Defaults to false

Whether payments should be automatically scheduled

description

string | null

Description of the subscription

language

string

required

length between 2 and 2

ISO language code (2 characters)

internalReferenceId

string

required

length ≤ 50

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

metadata

object | null

Custom metadata key-value pairs

Responses

201Subscription created successfully

400Bad Request - Validation error