Create a Recurrence (Journey 4)

Journey 4 — QR Code + Payment or scheduling + Automatic Pix offer

Overview

What it is

The customer makes a payment or schedules a QR Code and then receives an offer to activate the Automatic Pix recurrence.

When to use

Recommended for invoices, bills or accounts with a recurrence adhesion proposal, but only after the initial payment or scheduling.

How it works

Payer reads the QR Code → pays or schedules the payment → upon completion, receives an invitation to activate the Automatic Pix for that charge (optional).

Benefits

Flexible: the decision about recurrence occurs after payment/scheduling, allowing voluntary and spontaneous adhesion by the payer.

Key considerations

The recurrence offer is made only after payment/scheduling — it can be declined by the customer. If not available for that case, proceed only with the payment, without offering recurrence.

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_four

METHOD

POST

Request Path Params

Field	Type	Description	Characters
account_key*	uuid4	Unique account identification key.	36

Request Body

Request Body: Create Recurrence (Journey 4)

{
    "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": "12345",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        }
    },
    "initial_payment_data": {
        "amount": 22.34,
        "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
        "qr_code_type": "dynamic_term",
        "additional_data": [
            {
                "key_name": "Juros e Multa",
                "value": "Juros 2 ao mes e multa de 1%"
            }	
        ],
        "fine_amount": 3,
        "interest_amount": 2,
        "expiration_date": "2023-03-25",
        "max_payment_days": 128,
        "rebate_amount": 1,
        "discounts": [],
        "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"		
    },
    "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 identification key used by the client in uuid4 format.	36
periodicity *	enumerator	Periodicity type associated with the subscription recurrence.	periodicity Enumerators
minimum_recurrence_amount	float	Minimum transaction amount for variable amount recurrences	-
start_date *	string	Recurrence start date (ISO 8601 format, e.g., "2025-07-01").	-
end_date	string	Recurrence end date; for indefinite time, 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	Settlement date adjustment type	settlement_date_type Enumerators
recurrence_type *	enumerator	Recurrence type	recurrence_type Enumerators
initial_payment_data *	Object	Object with initial charge information to be performed when creating the subscription.	initial_payment_data Object

Attention

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

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	Workdays
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 if 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.	-

initial_payment_data Object

Field	Type	Description	Characters
amount *	number	Main amount of the initial charge in Brazilian Reais (R$).	-
pix_key *	string	Destination Pix key for the payment.	77
qr_code_type*	enumerator	QR Code type for the initial charge.	qr_code_type Enumerators
additional_data*	array	List of objects with additional information related to the charge (e.g., interest, fine).	additional_data Objects
fine_amount	number	Fine amount in case of late payment.	-
interest_amount	number	Interest amount in case of late payment.	-
expiration_date *	string	Initial charge expiration date (ISO 8601 format, e.g., "2023-03-25").	-
max_payment_days	integer	Maximum number of days from the expiration date in which payment can be accepted.	-
rebate_amount	number	Discount amount for early payment.	-
discounts	array	List of additional applicable discounts (if any).	-
receiver_conciliation_id	string	Unique identifier for payment reconciliation by the receiver.	32

qr_code_type Enumerators

Value	Description
dynamic_instant	Generates a dynamic QR Code for instant payment, with immediate expiration.
dynamic_term	Generates a dynamic QR Code with defined payment term (future expiration).

additional_data Object

Field	Type	Description	Characters
key_name	string	Additional information field name (example: "Interest and Fine").	-
value	string	Value or description of the additional information.	-

Response

STATUS

200

Attention

When the payer user receives the notification, they can choose to schedule the Pix or make the transfer at that moment. If the payer makes the payment instantly, the webhook of type baas.automatic_pix.outgoing_recurrence.status_change will be sent with the information filled in; in case of scheduling, the values will be null.

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": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb",
	    "qr_code_image": "imageb64" 
    },
     "initial_payment_data": {
			"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"			  
		},
    "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 subscription recurrence identification key.	36
recurrence_status	enumerator	Current recurrence status.	recurrence_status Enumerators
qr_code_data	enumerator	QR Code data	qr_code_data Object
initial_payment_data	enumerator	Initiated payment information	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	QR code copy and paste URL	-
qr_code_key	uuuid	QR code unique identification key.	36
qr_code_image	string	QR code image base64	-

initial_payment_data Object

Field	Type	Description	Characters
receiver_conciliation_id	string	Unique identifier for payment reconciliation by the receiver.	32

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.