Criar uma Recorrência (Jornada 1)

Jornada 1 — Sem QR Code (notificação no app)

Visão geral

O que é

Autorização solicitada ao pagador diretamente no app do banco, sem leitura de QR Code.

Quando usar

Contato ativo (telefone, chat, presencial) ou relacionamento já existente com o cliente.

Como funciona

Recebedor cria a recorrência com dados da conta do pagador → o pagador recebe uma notificação no app → aprova a recorrência → futuras cobranças podem ser agendadas.

Benefícios

Experiência simples e direta; não exige exibição de QR Code.

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_one

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 (Jornada 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

Campo	Tipo	Descrição	Caracteres
request_control_key *	uuid	Chave única de identificação da requisição utilizada pelo cliente no formato uuid4.	36
periodicity *	enumerator	Tipo da periodicidade associada à recorrência da assinatura.	Enumeradores periodicity
minimum_recurrence_amount	number	Valor mínimo da transação para recorrências de valor variável (em centavos).	-
start_date *	string	Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01").	-
end_date	string	Data de término da recorrência; para tempo indeterminado, enviar como null.	-
pix_message *	string	Mensagem a ser enviada junto à transação Pix.	140
debtor_data *	Object	Dados do devedor (assinante).	Objeto debtor_data
retry_configuration *	Object	Configuração de retentativas para transações não concluídas.	Objeto retry_configuration
settlement_date_type *	enumerator	Tipo de ajuste da data de liquidação	Enumeradores settlement_date_type
recurrence_type *	enumerator	Tipo de recorrência	Enumeradores recurrence_type

Atenção

O campo minimum_recurrence_amount é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo recurrence_amount, com o valor da recorrência. Assim como o enumerador recurrence_type, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).

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 settlement_date_type

Enumerador	Descrição
workdays	Dias úteis
calendar_days	Dias corridos

Enumeradores recurrence_type

Enumerador	Descrição
fixed_amount	Recorrência de Valor Fixo
variable_amount	Recorrência de Valor Variável

Objeto debtor_data

Campo	Tipo	Descrição	Caracteres
name *	string	Nome do assinante.	50
email *	string	E-mail do assinante.	100
document_number *	string	CPF ou CNPJ do assinante.	14
contract_id	string	Identificador do contrato do assinante.	100
address *	Object	Endereço do assinante.	Objeto address
account_data *	Object	Dados bancários do assinante.	Objeto account_data

Objeto address

Campo	Tipo	Descrição	Caracteres
street	string	Rua.	-
state	string	Estado.	-
city	string	Cidade.	-
neighborhood	string	Bairro.	-
number	string	Número.	-
postal_code	string	CEP.	-
complement	string	Complemento.	-

Objeto account_data

Campo	Tipo	Descrição	Caracteres
account_number	string	Número da conta.	-
account_digit	string	Dígito da conta.	-
account_branch	string	Agência da conta.	-
ispb	string	ISPB da instituição financeira.	-

Objeto retry_configuration

Campo	Tipo	Descrição	Caracteres
retry_allowed	boolean	Indica se retentativas são permitidas.	-
retry_rule	Object	Regras de retentativa.	Objeto retry_rule

Objeto retry_rule

Campo	Tipo	Descrição	Caracteres
first_retry	Object	Configuração da primeira retentativa.	Objeto retry_detail
second_retry	Object	Configuração da segunda retentativa.	Objeto retry_detail
third_retry	Object	Configuração da terceira retentativa.	Objeto retry_detail

Objeto retry_detail

Campo	Tipo	Descrição	Caracteres
day	string	Dia da retentativa.	-

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

Campo	Tipo	Descrição	Caracteres
request_control_key	uuid	Chave de controle da requisição enviada pelo cliente.	36
recurrence_key	uuid	Chave única de identificação da recorrência de assinatura.	36
recurrence_status	enumerator	Status atual da recorrência.	Enumeradores recurrence_status
created_at	string	Data e hora de criação da recorrência (formato ISO 8601).	-

Enumeradores 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 Error

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

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