Pular para o conteúdo principal

Criar uma Recorrência (Jornada 3)

Jornada 3 — QR Code + Primeiro Pagamento (ativação imediata da recorrência)

Visão geral

O que é

Um único QR Code que permite pagar agora e ativar a recorrência no mesmo fluxo.

Quando usar

Casos com cobrança inicial obrigatória (ex.: adesão, matrícula, primeira mensalidade).

Como funciona

O pagador lê o QR → realiza o primeiro pagamento → autoriza a recorrência imediatamente.

Benefícios

Receita imediata + recorrência configurada, reduzindo fricção e inadimplência.

Fluxo da Jornada 3​

1. Ler o QR Code

O usuário escaneia o QR dinâmico gerado para a cobrança inicial.

2. Pagar Agora

O pagamento imediato é processado, registrando a cobrança inicial.

3. Autorizar Recorrência

Na mesma experiência, o usuário confirma a autorização da recorrência.

4. Recorrência Ativa

Próximos ciclos são automatizados; você só precisa conciliar valores quando necessário.

Request​

ENDPOINT
/account/account_key/outgoing_recurrence/journey_three
MÉTODO
POST

Path Params​

CampoTipoDescriçãoCaracteres
account_keyuuid4Chave única de identificação da conta.36

Body Params​

CampoTipoDescriçãoCaracteres
request_control_keyuuidChave única da requisição (uuid4).36
periodicityenumeratorPeriodicidade da recorrência.Enumeradores periodicity
minimum_recurrence_amountfloatValor mínimo por transação (recorrências variáveis).-
start_datestringData de início (ISO 8601).-
end_datestringData de término ou null para indeterminado.-
pix_messagestringMensagem exibida na transação Pix.140
debtor_dataObjectDados do assinante.Objeto debtor_data
retry_configurationObjectRegras de retentativa.Objeto retry_configuration
settlement_date_typeenumeratorAjuste da data de liquidação.Enumeradores settlement_date_type
recurrence_typeenumeratorTipo da recorrência.Enumeradores recurrence_type
initial_payment_dataObjectDados da cobrança inicial.Objeto initial_payment_data
Atenção: para recorrência de valor variável, informe minimum_recurrence_amount. Para valor fixo, envie recurrence_amount e ajuste o enumerador recurrence_type de acordo.

Enumeradores periodicity​

EnumeradorDescrição
weeklyRecorrência semanal
monthlyRecorrência mensal
quarterlyRecorrência trimestral
semiannualRecorrência semestral
annualRecorrência anual

Enumeradores settlement_date_type​

EnumeradorDescrição
workdaysDias úteis
calendar_daysDias corridos

Enumeradores recurrence_type​

EnumeradorDescrição
fixed_amountRecorrência de Valor Fixo
variable_amountRecorrência de Valor Variável

Objeto debtor_data​

CampoTipoDescriçãoCaracteres
namestringNome do assinante.50
emailstringE-mail do assinante.100
document_numberstringCPF/CNPJ do assinante.14
contract_idstringIdentificador do contrato.100
addressObjectEndereço do assinante.Objeto address

Objeto address​

CampoTipoDescrição
streetstringRua
statestringEstado
citystringCidade
neighborhoodstringBairro
numberstringNúmero
postal_codestringCEP
complementstringComplemento

Objeto retry_configuration​

CampoTipoDescrição
retry_allowedbooleanHabilita retentativas
retry_ruleObjectRegras de retentativa

Objeto retry_rule​

CampoTipoDescrição
first_retryObjectPrimeira retentativa
second_retryObjectSegunda retentativa
third_retryObjectTerceira retentativa

Objeto retry_detail​

CampoTipoDescrição
daystringDia da retentativa

Objeto initial_payment_data​

CampoTipoDescriçãoCaracteres
amountnumberValor da cobrança inicial (R$).-
pix_keystringChave Pix de destino.77
qr_code_typeenumeratorTipo de QR Code da cobrança inicial.Enumeradores qr_code_type
additional_dataarrayLista de dados adicionais (ex.: juros/multa).Objetos additional_data
fine_amountnumberMulta por atraso.-
interest_amountnumberJuros por atraso.-
expiration_datestringData de expiração (ISO 8601).-
max_payment_daysintegerDias máximos após expiração para aceitar o pagamento.-
rebate_amountnumberDesconto por antecipação.-
discountsarrayDescontos adicionais.-
receiver_conciliation_idstringIdentificador para conciliação pelo recebedor.32

Enumeradores qr_code_type​

ValorDescrição
dynamic_instantQR dinâmico para pagamento imediato
dynamic_termQR dinâmico com prazo (vencimento futuro)

Objetos additional_data​

CampoTipoDescrição
key_namestringRótulo da informação (ex.: Juros e Multa)
valuestringValor/descrição

Response​

STATUS
200
Response Body (exemplo)
{
  "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": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
    "qr_code_image": "imageb64"
  },
  "initial_payment_data": {
    "receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
  },
  "created_at": "2021-10-22T20:30:23.459Z"
}

Campos do Response​

CampoTipoDescriçãoCaracteres
request_control_keyuuidChave de controle enviada pelo cliente36
recurrence_keyuuidIdentificação da recorrência de assinatura36
recurrence_statusenumeratorStatus da recorrênciaEnumeradores recurrence_status
qr_code_dataObjectDados do QR gerado para o primeiro pagamentoObjeto qr_code_data
initial_payment_dataObjectInformações do pagamento inicialObjeto initial_payment_data
created_atstringData/hora de criação (ISO 8601)-

Objeto qr_code_data​

CampoTipoDescriçãoCaracteres
qr_code_urlstringURL do copia e cola-
qr_code_keyuuidIdentificador do QR36
qr_code_imagestringImagem (Base64)-

Objeto initial_payment_data​

CampoTipoDescriçãoCaracteres
receiver_conciliation_idstringID de conciliação do pagamento32

Enumeradores recurrence_status​

EnumeradorDescrição
pending_confirmationPendente de confirmação
activeAtiva
cancelledCancelada
suspendedSuspensa
expiredExpirada

Dicas e Boas Práticas​

✓Conciliação em recorrência variável: para variable_amount, concilie o valor de 10 a 3 dias antes da data de cobrança.

✓Mensagens Pix: utilize pix_message com até 140 caracteres para explicar claramente a cobrança inicial.

⚠Segurança: valide documentos/contas e trate erros de rede e de integrações externas com retentativas idempotentes.