Create a Recurrence (Journey 1)

Journey 1 — Without QR Code (app notification)

Overview

What it is

Authorization requested from the payer directly in the bank app, without QR Code reading.

When to use

Active contact (phone, chat, in-person) or existing relationship with the customer.

How it works

Receiver creates the recurrence with payer's account data → the payer receives a notification in the app → approves the recurrence → future charges can be scheduled.

Benefits

Simple and direct experience; doesn't require QR Code display.

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_one

METHOD

POST

Request Path Params

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

Request Body

Request Body: Create Recurrence (Journey 1)

{
    "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": "Contrato de pagamento recorrente",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "account_data": {
            "account_number": "123456",
            "account_digit": "7",
            "account_branch": "0001",
            "ispb": "31872495"
        }
    },
    "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	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 duration, send as null.	-
pix_message *	string	Message to be sent along 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 minimum_recurrence_amount field is optional and should only be provided for variable amount recurrences. If the recurrence is fixed amount, the recurrence_amount field must be sent, with the recurrence value. As well as the recurrence_type enumerator, which should correspond to the type of recurrence (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
account_data *	Object	Subscriber banking data.	account_data 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.	-

account_data Object

Field	Type	Description	Characters
account_number	string	Account number.	-
account_digit	string	Account digit.	-
account_branch	string	Account branch.	-
ispb	string	Financial institution ISPB.	-

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

Response

STATUS

200

Response Body

{
    "request_control_key": "a7b9e3c1-f2d4-4a8b-9c7e-123456789abc",
    "recurrence_key": "b2c3d4e5-f6g7-4h8i-9j0k-l1m2n3o4p5q6",
    "recurrence_status": "pending_confirmation",
    "created_at": "2025-06-16T23:52:00.000Z"
}

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
created_at	string	Recurrence creation date and time (ISO 8601 format).	-

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.