Criar Assinatura

curl --request POST \
  --url https://zeus-sandbox.autorizou.dev/api/v1/charges/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "code": "<string>",
  "mcc": "<string>",
  "notification_url": "<string>",
  "plan_id": "<string>",
  "interval": "<string>",
  "start_at": "<string>",
  "best_charge_day": 123,
  "trial_days": 123,
  "next_charge_amount": 123,
  "customer": {
    "customer.id": "<string>",
    "customer.name": "<string>",
    "customer.email": "<string>",
    "customer.documents": [
      {
        "customer.documents[].type": "<string>",
        "customer.documents[].value": "<string>"
      }
    ],
    "customer.phone": {
      "customer.phone.type": "<string>",
      "customer.phone.ddi": "<string>",
      "customer.phone.ddd": "<string>",
      "customer.phone.number": "<string>"
    },
    "customer.addresses": [
      {
        "customer.addresses[].type": "<string>",
        "customer.addresses[].postal_code": "<string>",
        "customer.addresses[].line_1": "<string>",
        "customer.addresses[].line_2": "<string>",
        "customer.addresses[].number": "<string>",
        "customer.addresses[].neighborhood": "<string>",
        "customer.addresses[].city": "<string>",
        "customer.addresses[].state": "<string>",
        "customer.addresses[].country": "<string>"
      }
    ]
  },
  "payment": {
    "payment.amount": 123,
    "payment.currency": "<string>",
    "payment.payment_method": "<string>",
    "payment.installments": 123,
    "payment.credit_card": {
      "payment.credit_card.id": "<string>",
      "payment.credit_card.statement_descriptor": "<string>",
      "payment.credit_card.capture": true,
      "payment.credit_card.processing_model": "<string>"
    },
    "payment.bank_slip": {
      "payment.bank_slip.due_at": "<string>"
    },
    "payment.pix": {
      "payment.pix.expires_at": "<string>"
    },
    "payment.pix_recurring": {
      "payment.pix_recurring.recurring_statement": "<string>",
      "payment.pix_recurring.recurring_amount": 123,
      "payment.pix_recurring.min_amount": 123,
      "payment.pix_recurring.retry_policy": true
    },
    "payment.google_pay": {
      "payment.google_pay.google_pay_token": "<string>",
      "payment.google_pay.statement_descriptor": "<string>",
      "payment.google_pay.capture": true,
      "payment.google_pay.capture_delay_hours": 123
    },
    "payment.split": [
      {
        "payment.split[].recipient_id": 123,
        "payment.split[].amount": 123,
        "payment.split[].type": "<string>",
        "payment.split[].allow_charge_processing_fee": true,
        "payment.split[].allow_charge_remainder_fee": true,
        "payment.split[].is_liable": true
      }
    ]
  },
  "items": [
    {
      "items[].name": "<string>",
      "items[].description": "<string>",
      "items[].quantity": 123,
      "items[].amount": 123
    }
  ]
}
'

{
  "message": "Os dados fornecidos são inválidos",
  "errors": {
    "payment.amount": ["O campo amount é obrigatório quando plan_id não é fornecido"],
    "customer.id": ["Cliente não encontrado"],
    "payment.credit_card.id": ["Cartão não encontrado ou não pertence ao cliente"]
  }
}

POST

api

charges

subscriptions

Criar Assinatura

curl --request POST \
  --url https://zeus-sandbox.autorizou.dev/api/v1/charges/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "code": "<string>",
  "mcc": "<string>",
  "notification_url": "<string>",
  "plan_id": "<string>",
  "interval": "<string>",
  "start_at": "<string>",
  "best_charge_day": 123,
  "trial_days": 123,
  "next_charge_amount": 123,
  "customer": {
    "customer.id": "<string>",
    "customer.name": "<string>",
    "customer.email": "<string>",
    "customer.documents": [
      {
        "customer.documents[].type": "<string>",
        "customer.documents[].value": "<string>"
      }
    ],
    "customer.phone": {
      "customer.phone.type": "<string>",
      "customer.phone.ddi": "<string>",
      "customer.phone.ddd": "<string>",
      "customer.phone.number": "<string>"
    },
    "customer.addresses": [
      {
        "customer.addresses[].type": "<string>",
        "customer.addresses[].postal_code": "<string>",
        "customer.addresses[].line_1": "<string>",
        "customer.addresses[].line_2": "<string>",
        "customer.addresses[].number": "<string>",
        "customer.addresses[].neighborhood": "<string>",
        "customer.addresses[].city": "<string>",
        "customer.addresses[].state": "<string>",
        "customer.addresses[].country": "<string>"
      }
    ]
  },
  "payment": {
    "payment.amount": 123,
    "payment.currency": "<string>",
    "payment.payment_method": "<string>",
    "payment.installments": 123,
    "payment.credit_card": {
      "payment.credit_card.id": "<string>",
      "payment.credit_card.statement_descriptor": "<string>",
      "payment.credit_card.capture": true,
      "payment.credit_card.processing_model": "<string>"
    },
    "payment.bank_slip": {
      "payment.bank_slip.due_at": "<string>"
    },
    "payment.pix": {
      "payment.pix.expires_at": "<string>"
    },
    "payment.pix_recurring": {
      "payment.pix_recurring.recurring_statement": "<string>",
      "payment.pix_recurring.recurring_amount": 123,
      "payment.pix_recurring.min_amount": 123,
      "payment.pix_recurring.retry_policy": true
    },
    "payment.google_pay": {
      "payment.google_pay.google_pay_token": "<string>",
      "payment.google_pay.statement_descriptor": "<string>",
      "payment.google_pay.capture": true,
      "payment.google_pay.capture_delay_hours": 123
    },
    "payment.split": [
      {
        "payment.split[].recipient_id": 123,
        "payment.split[].amount": 123,
        "payment.split[].type": "<string>",
        "payment.split[].allow_charge_processing_fee": true,
        "payment.split[].allow_charge_remainder_fee": true,
        "payment.split[].is_liable": true
      }
    ]
  },
  "items": [
    {
      "items[].name": "<string>",
      "items[].description": "<string>",
      "items[].quantity": 123,
      "items[].amount": 123
    }
  ]
}
'

{
  "message": "Os dados fornecidos são inválidos",
  "errors": {
    "payment.amount": ["O campo amount é obrigatório quando plan_id não é fornecido"],
    "customer.id": ["Cliente não encontrado"],
    "payment.credit_card.id": ["Cartão não encontrado ou não pertence ao cliente"]
  }
}

Permite criar assinaturas recorrentes (semanal, mensal ou anual) com cobrança automática. Ideal para serviços SaaS, academias, escolas e outros modelos de negócio baseados em recorrência.

Parâmetros da Requisição

Dados Básicos

description

string

required

Descrição da assinatura (aparece na fatura)Máximo: 255 caracteres

code

string

required

Identificador único da assinatura no seu sistemaMáximo: 255 caracteres

mcc

string

required

Código MCC (Merchant Category Code) do seu negócioExemplo: "5734" (Software as a Service)

notification_url

string

URL para receber webhooks sobre eventos da assinaturaFormato: URL válida

Plano e Recorrência

plan_id

string

UUID do plano cadastrado (se usar plano pré-configurado)

interval

string

Intervalo de cobrança (obrigatório se plan_id não fornecido)Valores: weekly, monthly, yearly

start_at

date

Data de início da assinaturaFormato: YYYY-MM-DDPadrão: data atual

best_charge_day

integer

Melhor dia do mês para cobrança (1-31)Padrão: dia da criação

trial_days

integer

Dias de período de teste gratuitoMínimo: 0 | Máximo: 365

next_charge_amount

integer

required

Valor da próxima cobrança em centavosImportante: Para PIX Recorrente, se não especificado, será usado o valor de payment.pix_recurring.recurring_amount ou payment.amountExemplo: 4990 = R$ 49,90

Cliente

customer

object

required

Show Dados do cliente

customer.id

string

UUID do cliente cadastrado (ou crie um novo fornecendo os dados abaixo)

customer.name

string

Nome completo (obrigatório se criando cliente)Máximo: 64 caracteres

customer.email

string

Email válido (obrigatório se criando cliente)Máximo: 64 caracteres

customer.documents

array

Lista de documentos (obrigatório se criando cliente)

Show Documento

customer.documents[].type

string

Valores: cpf, cnpj, passport, rg, other

customer.documents[].value

string

Número do documento

customer.phone

object

Telefone do cliente (opcional)

Show Dados do telefone

customer.phone.type

string

Valores: residential, mobile, commercial, public

customer.phone.ddi

string

Código DDI (ex: "55")

customer.phone.ddd

string

Código DDD (ex: "11")

customer.phone.number

string

Número do telefone

customer.addresses

array

Endereços do cliente (opcional)

Show Dados do endereço

customer.addresses[].type

string

Valores: billing, shipping

customer.addresses[].postal_code

string

CEP (apenas números)

customer.addresses[].line_1

string

Logradouro

customer.addresses[].line_2

string

Complemento

customer.addresses[].number

string

Número

customer.addresses[].neighborhood

string

Bairro

customer.addresses[].city

string

Cidade

customer.addresses[].state

string

Estado (sigla de 2 caracteres)

customer.addresses[].country

string

País (código ISO alpha-2, ex: "BR")

Pagamento

payment

object

required

Show Configurações de pagamento

payment.amount

integer

Valor da assinatura em centavos (obrigatório se não usar plan_id)Exemplo: 5000 = R$ 50,00

payment.currency

string

required

Moeda da transaçãoValor: BRL

payment.payment_method

string

required

Método de pagamentoValores: credit_card, pix, pix_recurring, bank_slip, google_pay

payment.installments

integer

required

Número de parcelas (1-12)Padrão: 1

payment.credit_card

object

Configurações do cartão de crédito (obrigatório se payment_method = "credit_card")

Show Dados do cartão

payment.credit_card.id

string

required

UUID do cartão salvo do cliente

payment.credit_card.statement_descriptor

string

required

Nome que aparecerá na fatura (máx 22 caracteres)

payment.credit_card.capture

boolean

required

Se deve capturar automaticamentePadrão: true

payment.credit_card.processing_model

string

required

Modelo de processamentoValores: customer_initiated, merchant_initiated, merchant_initiated_subscription

payment.bank_slip

object

Configurações do boleto (obrigatório se payment_method = "bank_slip")

Show Dados do boleto

payment.bank_slip.due_at

string

required

Data de vencimento (ISO 8601)Exemplo: "2024-02-01T23:59:59Z"

payment.pix

object

Configurações do PIX (obrigatório se payment_method = "pix")

Show Dados do PIX

payment.pix.expires_at

string

required

Data/hora de expiração (ISO 8601)Exemplo: "2024-01-15T18:00:00Z"

payment.pix_recurring

object

Configurações do PIX Recorrente (obrigatório se payment_method = "pix_recurring")

Show Dados do PIX Recorrente

payment.pix_recurring.recurring_statement

string

required

Descrição que aparecerá na fatura recorrente do clienteMáximo: 35 caracteresExemplo: "Assinatura Mensal - Meu App"

payment.pix_recurring.recurring_amount

integer

Valor recorrente em centavos (se diferente do valor inicial)Exemplo: 9990 = R$ 99,90

payment.pix_recurring.min_amount

integer

Valor mínimo aceito em centavos para pagamentos recorrentesExemplo: 5000 = R$ 50,00

payment.pix_recurring.retry_policy

boolean

Se deve tentar novamente em caso de falhaPadrão: true | Máximo de tentativas: 3

payment.google_pay

object

Configurações do Google Pay (obrigatório se payment_method = "google_pay")

Show Dados do Google Pay

payment.google_pay.google_pay_token

string

required

Token do Google Pay

payment.google_pay.statement_descriptor

string

required

Nome na fatura (máx 22 caracteres)

payment.google_pay.capture

boolean

required

Se deve capturar automaticamente

payment.google_pay.capture_delay_hours

integer

Horas para aguardar captura (se capture = false)

payment.split

array

Divisão do pagamento entre destinatários (opcional)

Show Configuração do split

payment.split[].recipient_id

integer

required

ID do destinatário cadastrado

payment.split[].amount

integer

required

Valor em centavos para este destinatário

payment.split[].type

string

required

Tipo do splitValores: flat, percentage

payment.split[].allow_charge_processing_fee

boolean

required

Se este destinatário paga taxas de processamento

payment.split[].allow_charge_remainder_fee

boolean

required

Se este destinatário paga taxas restantes

payment.split[].is_liable

boolean

required

Se este destinatário é responsável por chargebacks

Itens (Opcional)

items

array

Lista de itens da assinatura (opcional, para controle interno)

Show Dados do item

items[].name

string

Nome do item (máx 64 caracteres)

items[].description

string

Descrição do item (máx 256 caracteres)

items[].quantity

integer

Quantidade (mínimo 1)

items[].amount

integer

Valor unitário em centavos

Exemplos de Requisição

curl -X POST https://zeus-sandbox.autorizou.dev/api/v1/charges/subscriptions \
  -H "Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Assinatura Mensal Premium",
    "code": "SUB_PREMIUM_001",
    "mcc": "5734",
    "interval": "monthly",
    "best_charge_day": 10,
    "trial_days": 7,
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "payment": {
      "amount": 9990,
      "currency": "BRL",
      "payment_method": "credit_card",
      "installments": 1,
      "credit_card": {
        "id": "card_abc123def456",
        "statement_descriptor": "MINHAEMPRESA PREMIUM",
        "capture": true,
        "processing_model": "merchant_initiated_subscription"
      }
    }
  }'

Resposta

string

UUID único da assinatura

hash

string

Hash único da assinatura

status

string

Status atual da assinaturaValores: trial_started, payment_pending, payment_approved, canceled, etc.

plan_id

string

UUID do plano (se usado)

interval

string

Intervalo de cobrança: weekly, monthly, yearly

next_charge_amount

integer

Valor da próxima cobrança em centavos

installments

integer

Número de parcelas

next_charge_at

string

Data/hora da próxima cobrança (formato: DD/MM/YYYY HH:mm:ss)

start_at

string

Data de início da assinatura

end_at

string

Data de término (se aplicável)

trial_days

integer

Dias de período de teste

current_cycle

integer

Ciclo atual da assinatura

payment

object

Show Dados do pagamento inicial

payment.id

string

UUID do pagamento

payment.hash

string

Hash do pagamento

payment.status

string

Status do pagamento

payment.payment_method

string

Método de pagamento usado

payment.amount

integer

Valor em centavos

payment.installments

integer

Número de parcelas

payment.currency

string

Moeda

payment.description

string

Descrição

payment.credit_card

object

Dados do cartão (quando aplicável)

payment.pix

object

Dados do PIX (quando aplicável)

payment.pix_recurring

object

Dados do PIX Recorrente (quando aplicável)

Show Estrutura do PIX Recorrente

payment.pix_recurring.qr_code

string

Código QR Code para o primeiro pagamento

payment.pix_recurring.qr_code_url

string

URL do QR Code em formato imagem

payment.pix_recurring.charge_code

string

Código de autorização recorrente para cobranças futuras

payment.pix_recurring.recurring_statement

string

Descrição exibida na fatura recorrente

payment.pix_recurring.expires_at

string

Data/hora de expiração do QR Code inicial

payment.bank_slip

object

Dados do boleto (quando aplicável)

payment.created_at

string

Data de criação

payment.updated_at

string

Data de atualização

fee

object

Show Taxas aplicadas

fee.fixed_fee_amount

integer

Valor da taxa fixa em centavos

fee.platform_fee_percentage

number

Percentual da taxa da plataforma

fee.platform_fee_amount

integer

Valor da taxa da plataforma em centavos

customer

object

Show Dados do cliente

customer.id

string

UUID do cliente

customer.name

string

Nome do cliente

customer.email

string

Email do cliente

Exemplo de Resposta

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hash": "SUB_abc123xyz789",
  "status": "payment_approved",
  "plan_id": null,
  "interval": "monthly",
  "next_charge_amount": 9990,
  "installments": 1,
  "next_charge_at": "10/02/2024 10:00:00",
  "start_at": "10/01/2024",
  "end_at": null,
  "trial_days": 7,
  "current_cycle": 1,
  "payment": {
    "id": "pay_def456ghi789",
    "hash": "PAY_xyz123abc456",
    "merchant_reference": "SUB_PREMIUM_001",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount": 9990,
    "installments": 1,
    "currency": "BRL",
    "description": "Assinatura Mensal Premium",
    "metadata": null,
    "credit_card": {
      "id": "card_abc123def456",
      "brand": "visa",
      "last_four_digits": "4242",
      "holder_name": "MARIA SILVA"
    },
    "created_at": "10/01/2024 10:00:00",
    "updated_at": "10/01/2024 10:00:05"
  },
  "fee": {
    "fixed_fee_amount": 39,
    "platform_fee_percentage": 3.99,
    "platform_fee_amount": 399
  },
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Maria Silva",
    "email": "maria@exemplo.com.br"
  }
}

Códigos de Status

{
  "message": "Os dados fornecidos são inválidos",
  "errors": {
    "payment.amount": ["O campo amount é obrigatório quando plan_id não é fornecido"],
    "customer.id": ["Cliente não encontrado"],
    "payment.credit_card.id": ["Cartão não encontrado ou não pertence ao cliente"]
  }
}

PIX Recorrente - Como Funciona

O PIX Recorrente permite cobranças automáticas recorrentes usando o PIX como método de pagamento, sem a necessidade de cartão de crédito.

Fluxo de Pagamento

Primeiro Pagamento (Autorização)
- Cliente escaneia QR Code e realiza o primeiro pagamento via PIX
- Esse pagamento autoriza cobranças futuras automáticas
- Um charge_code único é gerado para identificar a autorização recorrente
Cobranças Recorrentes Automáticas
- O sistema agenda automaticamente os pagamentos futuros
- Pagamentos são processados 2-10 dias antes da data de vencimento.
- Cliente é notificado antes de cada cobrança
Política de Retry (Tentativas)
- Em caso de falha, o sistema tenta novamente automaticamente
- Até 3 tentativas com intervalo de 1 dia entre cada
- Tentativas ocorrem em até 7 dias da data original

Status do Ciclo de Vida do Pagamento PIX Recorrente

Os status de pagamento do PIX Recorrente seguem um fluxo específico diferente dos outros métodos.

Status	Descrição	Quando Ocorre
`waiting_payment`	Aguardando o primeiro pagamento PIX	Após criação da assinatura, QR Code gerado
`scheduled`	Pagamento agendado para processamento	3 dias antes da data de cobrança
`processing`	Pagamento sendo processado	2 dias antes da data de cobrança
`authorized`	Pagamento autorizado com sucesso	Após confirmação do pagamento
`refused`	Pagamento recusado (saldo insuficiente, limite excedido, etc.)	Quando a cobrança falha
`expired`	QR Code ou cobrança expirou	Após período de expiração sem pagamento
`settled`	Pagamento liquidado	Após processamento final e transferência

Transições de Status Permitidas

PIX Recorrente - Primeiro Pagamento:

waiting_payment → authorized (pagamento confirmado)
waiting_payment → scheduled (para PIX recorrente, quando inicia ciclo)
waiting_payment → expired (QR code expirou)

PIX Recorrente - Cobranças Automáticas:

scheduled → processing (enviado para processadora)
scheduled → authorized (cobrança aprovada)
scheduled → refused (cobrança recusada)
scheduled → error (erro no processamento)

refused → scheduled (retry automático, se retry_policy = true)

Regras Importantes

Janela de Processamento: Pagamentos PIX Recorrentes devem ser enviados entre 2 e 10 dias antes da data de vencimento.

Valor Mínimo: Defina min_amount para evitar cobranças abaixo de um valor específico
Período de Trial: Pode ser usado com trial_days > 0, mas o primeiro pagamento deve ser amount = 0
Política de Retry: Com retry_policy = true, até 3 tentativas automáticas em caso de falha
Charge Code: Obrigatório e único por assinatura, usado para identificar a autorização recorrente

Exemplo de Resposta com PIX Recorrente

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hash": "SUB_pixrec123xyz",
  "status": "waiting_payment",
  "interval": "monthly",
  "next_charge_amount": 4990,
  "installments": 1,
  "next_charge_at": "10/02/2024 10:00:00",
  "start_at": "10/01/2024",
  "trial_days": 0,
  "current_cycle": 1,
  "payment": {
    "id": "pay_pixrec456def",
    "hash": "PAY_pixrec789ghi",
    "merchant_reference": "SUB_PIX_REC_001",
    "status": "waiting_payment",
    "payment_method": "pix_recurring",
    "amount": 4990,
    "installments": 1,
    "currency": "BRL",
    "description": "Assinatura Mensal Premium PIX",
    "pix_recurring": {
      "qr_code": "00020126580014br.gov.bcb.pix...",
      "qr_code_url": "https://api.autorizou.dev/qr/pixrec456def.png",
      "charge_code": "CHG_REC_abc123xyz789",
      "recurring_statement": "Assinatura Premium - MeuApp",
      "expires_at": "2024-01-15T23:59:59Z"
    },
    "created_at": "10/01/2024 10:00:00",
    "updated_at": "10/01/2024 10:00:00"
  },
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  }
}

Próximos Passos

Após criar uma assinatura:

Cancelar assinatura quando necessário
Consultar pagamentos da assinatura
Configurar webhooks para acompanhar eventos de cobrança recorrente
Para PIX Recorrente: exibir QR Code ao cliente e aguardar primeiro pagamento

Criar Pedido Cancelar Assinatura

​Parâmetros da Requisição

​Dados Básicos

​Plano e Recorrência

​Cliente

​Pagamento

​Itens (Opcional)

​Exemplos de Requisição

​Resposta

​Exemplo de Resposta

​Códigos de Status

​PIX Recorrente - Como Funciona

​Fluxo de Pagamento

​Status do Ciclo de Vida do Pagamento PIX Recorrente

​Transições de Status Permitidas

​Regras Importantes

​Exemplo de Resposta com PIX Recorrente

​Próximos Passos

Parâmetros da Requisição

Dados Básicos

Plano e Recorrência

Cliente

Pagamento

Itens (Opcional)

Exemplos de Requisição

Resposta

Exemplo de Resposta

Códigos de Status

PIX Recorrente - Como Funciona

Fluxo de Pagamento

Status do Ciclo de Vida do Pagamento PIX Recorrente

Transições de Status Permitidas

Regras Importantes

Exemplo de Resposta com PIX Recorrente

Próximos Passos