Create a Recurrence (Journey 2)

Journey 2 — QR Code with recurrence data only

Overview

What is it

QR Code that presents only the recurrence data for the payer to authorize, without immediate charge.

When to use

Onboarding without initial charge; use at points of sale, counters, screens or printed materials.

How it works

Payer reads QR → views recurrence data in app → authorizes → future charges can be scheduled.

Benefits

Agile enablement via QR; allows mass customer acquisition with low friction and QR can be reused for new recurrences.

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_two

METHOD

POST

Request Path Params

Field	Type	Description	Characters
account_key*	uuid4	Unique identifier key for the account.	36

Request Body

Request Body: Create Recurrence (Journey 2)

{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "periodicity": "monthly",
    "minimum_recurrence_amount": 125,
    "start_date": "2025-06-10",
    "end_date": "2027-06-10",
    "pix_message": "Conta de Luz Residencial nº123",
    "recurrence_type": "variable_amount",
    "debtor_data": {
        "name": "Sebastião",
        "email": "sebastiao@test.com",
        "document_number": "05431134850",
        "contract_id": "124587624",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        }
    },
    "retry_configuration": {
        "retry_allowed": true,
        "retry_rule": {
            "first_retry": {
                "day": "1"
            },
            "second_retry": {
                "day": "3"
            },
            "third_retry": {
                "day": "4"
            }
        }
    },
    "settlement_date_type": "workdays"
}

Body Params

Field	Type	Description	Characters
request_control_key *	uuid	Unique request identifier key used by the client in uuid4 format.	36
periodicity *	enumerator	Type of periodicity associated with the subscription recurrence.	periodicity Enumerators
minimum_recurrence_amount	number	Minimum transaction amount for variable amount recurrences (in cents).	-
start_date *	string	Recurrence start date (ISO 8601 format, e.g., "2025-07-01").	-
end_date	string	Recurrence end date; for indefinite period, send as null.	-
pix_message *	string	Message to be sent with the PIX transaction.	140
debtor_data *	Object	Debtor (subscriber) data.	debtor_data Object
retry_configuration *	Object	Retry configuration for incomplete transactions.	retry_configuration Object
settlement_date_type *	enumerator	Type of settlement date adjustment	settlement_date_type Enumerators
recurrence_type *	enumerator	Type of recurrence	recurrence_type Enumerators

Attention

The field minimum_recurrence_amount is optional and should only be informed for variable amount recurrence. If the recurrence is fixed amount, the field recurrence_amount should be sent with the recurrence amount. As well as the recurrence_type enumerator, which should correspond to the recurrence type (Fixed amount or variable).

periodicity Enumerators

Enumerator	Description
weekly	Weekly recurrence
monthly	Monthly recurrence
quarterly	Quarterly recurrence
semiannual	Semiannual recurrence
annual	Annual recurrence

settlement_date_type Enumerators

Enumerator	Description
workdays	Business days
calendar_days	Calendar days

recurrence_type Enumerators

Enumerator	Description
fixed_amount	Fixed Amount Recurrence
variable_amount	Variable Amount Recurrence

debtor_data Object

Field	Type	Description	Characters
name *	string	Subscriber name.	50
email *	string	Subscriber email.	100
document_number *	string	Subscriber CPF or CNPJ.	14
contract_id	string	Subscriber contract identifier.	100
address *	Object	Subscriber address.	address Object

address Object

Field	Type	Description	Characters
street	string	Street.	-
state	string	State.	-
city	string	City.	-
neighborhood	string	Neighborhood.	-
number	string	Number.	-
postal_code	string	Postal code.	-
complement	string	Complement.	-

retry_configuration Object

Field	Type	Description	Characters
retry_allowed	boolean	Indicates whether retries are allowed.	-
retry_rule	Object	Retry rules.	retry_rule Object

retry_rule Object

Field	Type	Description	Characters
first_retry	Object	First retry configuration.	retry_detail Object
second_retry	Object	Second retry configuration.	retry_detail Object
third_retry	Object	Third retry configuration.	retry_detail Object

retry_detail Object

Field	Type	Description	Characters
day	string	Retry day.	-

Response

STATUS

200

Response Body

{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "pending_confirmation",
    "qr_code_data": {
	    "qr_code_url": "url",
	    "qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
	    "qr_code_image": "imageb64"  
    },
    "created_at": "2021-10-22T20:30:23.459Z"
}

Response Body

Field	Type	Description	Characters
request_control_key	uuid	Request control key sent by the client.	36
recurrence_key	uuid	Unique identifier key for the subscription recurrence.	36
recurrence_status	enumerator	Current recurrence status.	recurrence_status Enumerators
qr_code_data	enumerator	Current recurrence status.	qr_code_data Object
created_at	string	Recurrence creation date and time (ISO 8601 format).	-

qr_code_data Object

Field	Type	Description	Characters
qr_code_url	string	URL of the QR code copy and paste	-
qr_code_key	uuuid	Unique identifier key for the QR code.	36
qr_code_image	string	Base64 of the QR code image	-

recurrence_status Enumerators

Enumerator	Description
pending_confirmation	Recurrence pending confirmation
active	Active recurrence
cancelled	Cancelled recurrence
suspended	Suspended recurrence
expired	Expired recurrence

STATUS

4XX

Response Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}

HTTP Code	QI Code code	Title title	Description (eng) description	Description (ptbr) translation
400	QIT000002	Bad Request	Invalid request schema.	Erro no esquema da requisição.
403	APX000030	Unauthorized Transaction	User is not authorized to create this recurrence.	Usuário não autorizado a criar esta recorrência.
403	APX000018	Endpoint Access Denied	Requester lacks permission to access this endpoint.	Requester não possui permissão para acessar este endpoint.
404	APX000021	Subscription Not Found	Subscription {subscription_key} not found.	Assinatura {subscription_key} não encontrada.
404	APX000002	Recurrence Not Found	Recurrence {recurrence_key} not found.	Recorrência {recurrence_key} não encontrada.
406	APX000027	Invalid Transaction Amount	Transaction amount {minimum_transaction_amount} is invalid.	Valor da transação {minimum_transaction_amount} é inválido.
409	APX000014	Request Control Key Conflict	The request_control_key {request_control_key} is already in use.	A request_control_key {request_control_key} já está em uso.