Para criar um Pix Automático pela API, use o endpoint de assinaturas POST /api/v1/subscriptions com type: PIX_RECURRING. Abaixo estão os campos que a API exige e os que são opcionais.

Antes de começar: o Pix Automático precisa estar habilitado na sua conta. Se não estiver, a API responde com o erro "Pix Automatic not enabled for this company, talk with our support". Nesse caso, fale com o nosso suporte pelo chat.

Campos obrigatórios

Campo O que enviar
value Valor da assinatura em centavos (ex.: 1990 para R$ 19,90). Mínimo de 1 centavo.
type Sempre PIX_RECURRING. Sem esse campo, a API cria uma assinatura comum, não um Pix Automático.
customer.name Nome do pagador. Obrigatório quando o pagador ainda não existe na sua conta.
customer.taxID CPF ou CNPJ do pagador. É por ele que a Woovi identifica o cliente.
pixRecurringOptions.journey A jornada escolhida: ONLY_RECURRENCY (jornada 2) ou PAYMENT_ON_APPROVAL (jornada 3).
pixRecurringOptions.retryPolicy Política de retentativa: NON_PERMITED (sem retentativa) ou THREE_RETRIES_7_DAYS (até 3 retentativas em 7 dias).

Campos opcionais

Campo O que acontece se não enviar
frequency Usa MONTHLY (mensal). Aceita WEEKLY, MONTHLY, QUARTERLY, SEMIANNUALLY e ANNUALLY. BIMONTHLY não é aceito no Pix Automático.
dayGenerateCharge Usa o dia 5. Aceita um dia do mês (1 a 31) ou uma data ISO 8601.
dayDue Quantos dias a cobrança fica válida (de 3 a 7).
comment Texto do contrato da recorrência. Se enviar, use até 30 caracteres.
name Nome da assinatura, para você identificar no painel.
correlationID Seu identificador da assinatura. Não pode repetir.
pixRecurringOptions.minimumValue Só para valor variável. Veja o link no fim do artigo.
customer.email e customer.phone Recomendados, mas não obrigatórios.
customer.address Não é obrigatório. Veja a seção abaixo.

Regras de data por jornada

  • Jornada 3 (PAYMENT_ON_APPROVAL): o dayGenerateCharge precisa ser o dia de hoje, porque o pagador paga a primeira parcela ao autorizar.
  • Jornada 2 (ONLY_RECURRENCY): o dayGenerateCharge precisa estar pelo menos 3 dias à frente de hoje.

Se o dia informado já passou no mês atual, a primeira cobrança fica para o mês seguinte.

Endereço do pagador

O customer.address pode ser omitido. Você consegue criar a assinatura só com nome, CPF/CNPJ e e-mail.

Se decidir enviar o endereço, ele precisa estar completo: zipcode, street, number, neighborhood, city e state (o complement é opcional). Endereço incompleto faz a API recusar o pedido.

Se não tiver o endereço completo do pagador, não envie o campo address.

Pagador que já existe

A Woovi procura o pagador pelo CPF/CNPJ (taxID) dentro da sua conta:

  • Já existe: o cadastro é reaproveitado e o name não precisa ser reenviado. Se você mandar um endereço, ele atualiza o do cliente.
  • Não existe: um novo cliente é criado com os dados enviados.

Se a API recusar

Quando falta um campo obrigatório ou algum valor é inválido, a API responde com erro 400 e uma mensagem dizendo o que corrigir. Nesse caso, nada é criado e não há cobrança de tarifa.

Exemplo mínimo

{
  "value": 1990,
  "type": "PIX_RECURRING",
  "frequency": "MONTHLY",
  "customer": {
    "name": "Maria Silva",
    "taxID": "12345678909",
    "email": "[email protected]"
  },
  "pixRecurringOptions": {
    "journey": "PAYMENT_ON_APPROVAL",
    "retryPolicy": "NON_PERMITED"
  }
}

Na jornada 3, como no exemplo, você pode omitir o dayGenerateCharge só se hoje for dia 5. Nos outros dias, envie o dia de hoje.