Criar uma Recorrência (Jornada 4)

Jornada 4 — QR Code + Pagament ou agendamento + Oferta do pix automático

Visão geral

O que é

O cliente realiza o pagamento ou agendamento de um QR Code e, depois, recebe a oferta para ativar a recorrência Pix Automático.

Quando usar

Indicado para faturas, boletos ou contas com proposta de adesão à recorrência, mas só após o pagamento ou agendamento inicial.

Como funciona

Pagador lê o QR Code → paga ou agenda o pagamento → ao concluir, recebe convite para ativar o Pix Automático para aquela cobrança (opcional).

Benefícios

Flexível: a decisão sobre a recorrência ocorre após o pagamento/agendamento, permitindo adesão voluntária e espontânea pelo pagador.

Pontos de atenção

A oferta de recorrência é feita somente após o pagamento/agendamento — pode ser recusada pelo cliente. Se não disponível para aquele caso, prossiga apenas com o pagamento, sem oferecer recorrência.

Request

ENDPOINT

/account/account_key/outgoing_recurrence/journey_four

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 4)

{
    "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_composed",
        "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

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	float	Valor mínimo da transação para recorrências de valor variável	-
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
initial_payment_data *	Object	Objeto com informações da cobrança inicial a ser realizada na criação da assinatura.	Objeto initial_payment_data

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

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

Objeto initial_payment_data

Campo	Tipo	Descrição	Caracteres
amount *	number	Valor principal da cobrança inicial em reais (R$).	-
pix_key *	string	Chave Pix de destino para o pagamento.	77
qr_code_type*	enumerator	Tipo de QR Code para a cobrança inicial.	Enumeradores qr_code_type
additional_data*	array	Lista de objetos com informações adicionais relacionadas à cobrança (ex: juros, multa).	Objetos additional_data
fine_amount	number	Valor da multa, caso ocorra atraso no pagamento.	-
interest_amount	number	Valor dos juros, caso ocorra atraso no pagamento.	-
expiration_date *	string	Data de expiração da cobrança inicial (formato ISO 8601, e.g., "2023-03-25").	-
max_payment_days	integer	Número máximo de dias, a partir da data de expiração, em que o pagamento pode ser aceito.	-
rebate_amount	number	Valor do desconto para pagamento antecipado.	-
discounts	array	Lista de descontos adicionais aplicáveis (se houver).	-
receiver_conciliation_id	string	Identificador único para conciliação do pagamento pelo recebedor.	32

Enumeradores qr_code_type

Valor	Descrição
dynamic_instant_composed	Gera um QR Code dinâmico para pagamento instantâneo, com vencimento imediato.
dynamic_term_composed	Gera um QR Code dinâmico com prazo definido para pagamento (vencimento futuro).

Objeto additional_data

Campo	Tipo	Descrição	Caracteres
key_name	string	Nome do campo adicional de informação (exemplo: "Juros e Multa").	-
value	string	Valor ou descrição da informação adicional.	-

Response

STATUS

200

Atenção

Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo baas.automatic_pix.outgoing_recurrence.status_change com as informações preenchidas, em caso de agendamento os valores serão null.

Response Body

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

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
qr_code_data	enumerator	Dados do QRCode	Objeto qr_code_data
initial_payment_data	enumerator	Informações do pagamento iniciado	Objeto qr_code_data
created_at	string	Data e hora de criação da recorrência (formato ISO 8601).	-

Objeto qr_code_data

Campo	Tipo	Descrição	Caracteres
qr_code_url	string	URL do copia e cola do qr_code	-
qr_code_key	uuuid	Chave Única de identificação do qr_code.	36
qr_code_image	string	Base64 da imagem do qr_code	-

Objeto initial_payment_data

Campo	Tipo	Descrição	Caracteres
receiver_conciliation_id	string	Identificador único para conciliação do pagamento pelo recebedor.	32

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.