Create payment recurrence

Request

ENDPOINT

/account/ACCOUNT_KEY/incoming_recurrence

METHOD

POST

Request Path Params

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

Request Body

Request Body: Create fixed amount recurrence

{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-04-01",
  "end_date": "2027-04-01",
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Informação do pagamento",
  "is_retry_allowed": true,
  "transaction_amount": 150.04
}

Request Body: Create variable amount recurrence

{
  "request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-07-01",
  "end_date": null,
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Pagamento da conta de energia elétrica",
  "is_retry_allowed": true,
  "minimum_transaction_amount": 50.00,
  "maximum_transaction_amount": 300.00
}

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 payment	periodicity enumerators
`journey_type` *	enumerator	Type of request journey	journey_type enumerators
`start_date` *	string	Recurrence start date	-
`end_to_end_id` *	string	Idempotency key for a Pix transaction within SPI (Instant Payment System). This key is returned in the Pix key query.	32
`target_pix_key`	string	Pix key of the account to which the transaction will be sent.	100
`target_account`	Object	Target account - Should only be sent for manual transfers.	target_account object
`transaction_amount`	number	Transfer amount for fixed value occurrence.	10
`minimum_transaction_amount`	number	Minimum transfer amount for variable value occurrence.	10
`maximum_transaction_amount`	number	Maximum transfer amount for variable value occurrence.	10
`end_date`	string	Recurrence end date, for indefinite time cases, send as null	-
`pix_message`	string	Message to be sent with the Pix transfer.	140
`is_retry_allowed`	boolean	Permission for Pix transaction retry.	-

periodicity enumerators

Enumerator	Description
`weekly`	Weekly recurrence
`monthly`	Monthly recurrence
`quarterly`	Quarterly recurrence
`semiannual`	Semi-annual recurrence
`annual`	Annual recurrence

journey_type enumerators

Enumerator	Description
`journey_one`	Authorization request through an app notification
`journey_two`	Authorization request through QR Code reading
`journey_three`	Recurrence authorization through an immediate pix via QR Code reading
`journey_four`	Payment or scheduling of a pix with a recurrence authorization request in sequence

target_account object

Field	Type	Description	Characters
`account_branch`	string	Account branch.	6
`account_digit`	string	Account digit.	1
`account_number`	string	Account number.	20
`owner_document_number`	string	CPF or CNPJ (numbers only) of the account holder.	14
`owner_name`	string	Account holder's name.	150
`account_type`	enumerator	Account type.	account_type enumerator
`ispb`	string	Based on the financial institution's CNPJ (8 digits).	8

info

Different enumerators may mean the same account type due to information returned by different institutions.

account_type enumerator

Enumerator	Description
`checking_account`	Checking Account
`salary_account`	Salary Account
`saving_account`	Savings Account
`payment_account`	Payment Account

Response

STATUS

200

Response Body: Recurrence created

{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "pending_confirmation",
  "created_at": "2025-05-22T20:30:23.459Z",
}

Field	Type	Description	Max. Characters
`incoming_recurrence_key`	uuid	Unique authorization identification key	36
`incoming_recurrence_status`	string	Recurrence status identifier	incoming_recurrence_status enumerator
`created_at`	string	Recurrence request creation time	-

incoming_recurrence_status enumerator

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

STATUS

4XX

Response Body

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

HTTP Code	QI Code `code`	Title `title`	Description (eng) `Description`	Description (ptbr) `translation`
400	QIT000001	Bad Request	Schema Error	Erro de Schema
403	APX000025	User is not allowed to do this transaction	User is not allowed to do this transaction	Usuário não tem autorização para fazer essa transação
403	APX000017	Requester not allowed to access this endpoint	Requester has no permission to perform pix transfers on this endpoint	Requester não possui permissão de realizar transações pix através deste endpoint
404	APX000020	Account not Found	Account was not found	Conta {account_key} não foi encontrada.
406	APX000026	Invalid end_to_end_id	The end_to_end_id sent {end_to_end_id} is not valid.	O end_to_end_id enviado {end_to_end_id} não é válido
406	APX000005	Invalid Transaction Amount	Transaction amount of {transaction_amount} is not valid. It must be a positive value with at maximum 2 decimal places	O valor de transação {transaction_amount} não é válido. Deve ser um valor positivo com no máximo duas casas decimais
409	APX000013	Request Control Key Reuse Error	The request_control_key {request_control_key} already in use	A request_control_key {request_control_key} já utilizada

Request​

Request Path Params​

Request Body​

Body Params​

periodicity enumerators​

journey_type enumerators​

target_account object​

account_type enumerator​

Response​

incoming_recurrence_status enumerator​