Create a Recurrence (Journey 3)

Journey 3 — QR Code + First Payment (immediate recurrence activation)

Overview

What it is

A single QR Code that allows pay now and activate recurrence in the same flow.

When to use

Cases with mandatory initial charge (e.g., registration, enrollment, first payment).

How it works

The payer scans the QR → makes the first payment → authorizes recurrence immediately.

Benefits

Immediate revenue + configured recurrence, reducing friction and delinquency.

Journey 3 Flow

1. Read QR Code

The user scans the dynamic QR generated for the initial charge.

2. Pay Now

The immediate payment is processed, recording the initial charge.

3. Authorize Recurrence

In the same experience, the user confirms the recurrence authorization.

4. Active Recurrence

Next cycles are automated; you only need to reconcile amounts when necessary.

---

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_three

METHOD

POST

Path Params

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

Request Body

Request Body: Create Recurrence (Journey 3)

{
  "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 key (uuid4).	36
periodicity*	enumerator	Recurrence periodicity.	Periodicity enumerators
minimum_recurrence_amount	float	Minimum amount per transaction (variable recurrences).	-
start_date*	string	Start date (ISO 8601).	-
end_date	string	End date or null for indefinite.	-
pix_message*	string	Message displayed in Pix transaction.	140
debtor_data*	Object	Subscriber data.	debtor_data object
retry_configuration*	Object	Retry rules.	retry_configuration object
settlement_date_type*	enumerator	Settlement date adjustment.	settlement_date_type enumerators
recurrence_type*	enumerator	Type of recurrence.	recurrence_type enumerators
initial_payment_data*	Object	Initial charge data.	initial_payment_data object

Attention: for variable amount recurrence, provide minimum_recurrence_amount. For fixed amount, send recurrence_amount and adjust the recurrence_type enumerator accordingly.

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/CNPJ.	14
contract_id	string	Contract identifier.	100
address*	Object	Subscriber address.	address object

address object

Field	Type	Description
street	string	Street
state	string	State
city	string	City
neighborhood	string	Neighborhood
number	string	Number
postal_code	string	ZIP Code
complement	string	Complement

retry_configuration object

Field	Type	Description
retry_allowed	boolean	Enable retries
retry_rule	Object	Retry rules

retry_rule object

Field	Type	Description
first_retry	Object	First retry
second_retry	Object	Second retry
third_retry	Object	Third retry

retry_detail object

Field	Type	Description
day	string	Retry day

initial_payment_data object

Field	Type	Description	Characters
amount*	number	Initial charge amount (R$).	-
pix_key*	string	Destination Pix key.	77
qr_code_type*	enumerator	Type of QR Code for initial charge.	qr_code_type enumerators
additional_data*	array	List of additional data (e.g., interest/fine).	additional_data objects
fine_amount	number	Late fee.	-
interest_amount	number	Interest for late payment.	-
expiration_date*	string	Expiration date (ISO 8601).	-
max_payment_days	integer	Maximum days after expiration to accept payment.	-
rebate_amount	number	Early payment discount.	-
discounts	array	Additional discounts.	-
receiver_conciliation_id	string	Identifier for receiver reconciliation.	32

qr_code_type enumerators

Value	Description
dynamic_instant	Dynamic QR for immediate payment
dynamic_term	Dynamic QR with term (future due date)

additional_data objects

Field	Type	Description
key_name	string	Information label (e.g., Interest and Fine)
value	string	Value/description

---

Response

STATUS

200

Response Body (example)

{
  "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"
  },
  "initial_payment_data": {
    "receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
  },
  "created_at": "2021-10-22T20:30:23.459Z"
}

Response Fields

Field	Type	Description	Characters
request_control_key	uuid	Control key sent by client	36
recurrence_key	uuid	Subscription recurrence identification	36
recurrence_status	enumerator	Recurrence status	recurrence_status enumerators
qr_code_data	Object	QR generated data for the first payment	qr_code_data object
initial_payment_data	Object	Initial payment information	initial_payment_data object
created_at	string	Creation date/time (ISO 8601)	-

qr_code_data object

Field	Type	Description	Characters
qr_code_url	string	Copy and paste URL	-
qr_code_key	uuid	QR identifier	36
qr_code_image	string	Image (Base64)	-

initial_payment_data object

Field	Type	Description	Characters
receiver_conciliation_id	string	Payment reconciliation ID	32

recurrence_status enumerators

Enumerator	Description
pending_confirmation	Pending confirmation
active	Active
cancelled	Cancelled
suspended	Suspended
expired	Expired

---

Tips and Best Practices

✓Reconciliation in variable recurrence: for variable_amount, reconcile the amount 10 to 3 days before the charge date.

✓Pix messages: use pix_message with up to 140 characters to clearly explain the initial charge.

⚠Security: validate documents/accounts and handle network and external integration errors with idempotent retries.