Criar recorrência de pagamento

Request

ENDPOINT

/account/ACCOUNT_KEY/incoming_recurrence

MÉTODO

POST

Request Path Params

Campo	Tipo	Descrição	Caracteres
account_key *	uuid4	Chave única de identificação da conta.	36

Request Body

Request Body: Criar recorrência de valor fixo

{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "j1_in_app_only_recurrence",
  "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: Criar recorrência de valor variável

{
  "request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "j1_in_app_only_recurrence",
  "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

Campo	Tipo	Descrição	Caracteres
request_control_key *	uuid	Chave única de identificação da request utilizada pelo cliente no formato uuid4.	36
periodicity *	enumerator	Tipo da periodicidade associada ao pagamento	Enumeradores periodicity
journey_type *	enumerator	Tipo da jornada de solicitação	Enumeradores journey_type
start_date *	string	Data de ínicio da recorrência	-
end_to_end_id *	string	Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix.	32
target_pix_key	string	Chave pix da conta a ser enviada a transação.	100
target_account	Object	Conta destino - Só deve ser enviada em transferências para transferência manuais.	Objeto target_account
transaction_amount	number	Valor da transferência para ocorrência de valor fixo.	10
minimum_transaction_amount	number	Valor mínimo da transferência para ocorrência de valor variável.	10
maximum_transaction_amount	number	Valor máximo da transferência para ocorrência de valor valor variável.	10
end_date	string	Data de término da recorrência, para os casos de tempo indeterminado, enviar como null	-
pix_message	string	Mensagem a ser enviada junto à transferência Pix.	140
is_retry_allowed	boolean	Permissão para retentativa de transação Pix.	-

Enumeradores periodicity

Enumerador	Descrição
weekly	Recorrência semanal
monthly	Recorrência mensal
quarterly	Recorrência trimestral
semiannual	Recorrência semestral
annual	Recorrência anual

Enumeradores journey_type

Enumerador	Descrição
j1_in_app_only_recurrence	Solicitação de autorização mediante uma notificação no aplicativo
j2_recurrence_only_qrcode	Solicitação de autorização mediante a leitura de um QR Code
j3_payment_and_recurrence_qrcode	Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code
j4_recurrence_offer_post_payment	Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência

Objeto target_account

Campo	Tipo	Descrição	Caracteres
account_branch	string	Agência da conta.	6
account_digit	string	Dígito da conta.	1
account_number	string	Número da conta.	20
owner_document_number	string	CPF ou CNPJ (apenas números) do titular da conta.	14
owner_name	string	Nome do titular da conta.	150
account_type	enumerator	Tipo da conta.	Enumerador account_type
ispb	string	Base no CNPJ da instituição financeira (8 dígitos).	8

info

Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes instituições.

Enumerador account_type

Enumerador	Descrição
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta de Pagamentos

Response

STATUS

200

Response Body: Recorrência criada

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

Campo	Tipo	Descrição	Max. Caracteres
incoming_recurrence_key	uuid	Chave única de identificação da autorização	36
incoming_recurrence_status	string	Identificador de status da recorrência	Enumerador incoming_recurrence_status
created_at	string	Horário da criação da solicitação de recorrência	-

Enumerador incoming_recurrence_status

Enumerador	Descrição
pending_confirmation	Recorrência pendente de confirmação
active	Recorrência ativa
cancelled	Recorrência cancelada
suspended	Recorrência suspensa
expired	Recorrência expirada

STATUS

4XX

Response Body

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

Código HTTP	Código QI code	Título title	Descrição (eng) Description	Descrição (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