Pular para o conteúdo principal

Criar Link de Autorização

Disponível apenas em Sandbox

Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para Pix Automático em produção no momento.

Use esta rota para criar o link onde o cliente revisa e aprova o Pix Automático. A resposta traz a authorization_url para onde o cliente deve ser enviado.

POSTv3/automatic_pix/links
Atenção

Faça esta chamada sempre a partir do seu servidor.

Request Body Params​

AtributoTipoDescrição
item_idstringParâmetro opcional. ID do link na sua plataforma.
contract_idstringIdentificador do contrato no seu sistema (ex.: número da matrícula, apólice ou contrato de crédito). Aparece para o cliente no banco.
descriptionstringParâmetro opcional. Texto exibido ao cliente na tela de autorização.
intervalstringPeriodicidade das cobranças.

Valores aceitos: weekly, monthly, quarterly, semester e yearly.
reference_start_datedateData de referência do primeiro ciclo de cobrança, no formato YYYY-MM-DD.
fixed_amountint32Parâmetro opcional. Valor fixo de cada cobrança. Deve ser passado em centavos. Use quando o valor não varia.
min_variable_amountint32Parâmetro opcional. Valor mínimo por cobrança, quando o valor é variável. Deve ser passado em centavos.
max_variable_amountint32Parâmetro opcional. Valor máximo por cobrança, quando o valor é variável. Deve ser passado em centavos. O cliente pode definir um teto menor no banco dele.
is_retry_acceptedbooleanParâmetro opcional. Indica se o cliente aceita retentativas em caso de falha. Padrão: false. Recomendamos true.
expires_atdateTimeParâmetro opcional. Data de expiração do link no formato ISODateTime. Após esse momento o cliente não consegue mais autorizar.
start_date_timedateTimeParâmetro opcional. Início da vigência da autorização no formato ISODateTime. Preencha somente para datas futuras.
expiration_date_timedateTimeParâmetro opcional. Fim da vigência da autorização no formato ISODateTime. Se omitido, a autorização vale por prazo indeterminado.
customerobjectObjeto Pagador, titular da conta que será debitada.
customer[name]stringParâmetro opcional. Nome do pagador.
customer[document_number]stringCPF ou CNPJ do pagador, somente números.
customer[ip_address]stringParâmetro opcional do endereço IP público do cliente ao acessar a sua página de checkout no formato IPv4 ou IPv6. Recomendado, pois é usado na análise de risco.
contract_debtorobjectObjeto Devedor do contrato. Pode ser diferente do pagador (ex.: o pai paga a mensalidade do filho).
contract_debtor[name]stringNome do devedor do contrato.
contract_debtor[document_number]stringCPF ou CNPJ do devedor do contrato, somente números.
creditorsarrayRecebedor(es) exibidos ao cliente na autorização.
creditors[][name]stringNome do recebedor.
creditors[][document_number]stringCNPJ ou CPF do recebedor, somente números.
business_entityobjectParâmetro opcional. Use quando o pagador for pessoa jurídica.
business_entity[document_number]stringCNPJ da empresa pagadora, somente números.
first_paymentobjectParâmetro opcional. Primeira cobrança, liquidada junto com a autorização.
first_payment[amount]int32Valor da primeira cobrança. Deve ser passado em centavos.
first_payment[date]dateParâmetro opcional. Data de liquidação no formato YYYY-MM-DD.
first_payment[description]stringParâmetro opcional. Texto exibido no extrato do cliente.
first_payment[creditor_account]objectObjeto Conta recebedora da primeira cobrança.
first_payment[creditor_account][ispb]stringISPB da instituição recebedora (8 dígitos).
first_payment[creditor_account][agency]stringNúmero da agência, sem dígito.
first_payment[creditor_account][account_number]stringNúmero da conta, com o dígito verificador.
first_payment[creditor_account][type]stringTipo da conta.

Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento).
participant_idstringParâmetro opcional. Banco do pagador, se já conhecido. Pula a etapa de escolha do banco na jornada.
debtor_accountobjectParâmetro opcional. Objeto Conta do pagador, se já conhecida.
debtor_account[ispb]stringISPB do banco do pagador (8 dígitos).
debtor_account[agency]stringNúmero da agência, sem dígito.
debtor_account[account_number]stringNúmero da conta, com o dígito verificador.
redirect_urlstringParâmetro opcional. URL para onde o cliente volta após concluir a autorização. Recomendado quando a jornada começa no seu site ou app. Se omitido, a jornada termina na tela de conclusão da Marlim.
redirect_on_error_urlstringParâmetro opcional. URL para onde o cliente volta em caso de erro na jornada. Se omitido, é usada a redirect_url.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá as mudanças de status do link, da autorização e das cobranças. Veja Webhooks.
webhook_auth_tokenstringParâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.
metadataobjectParâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas.
Importante

Envie ou o fixed_amount ou a faixa min_variable_amount e max_variable_amount, nunca os dois. Todos os valores do Pix Automático são em centavos.

Response Object​

PropriedadeTipoDescrição
link_idstringID Marlim do link de autorização. Guarde este ID: é com ele que você consulta e cancela o link.
item_idstringID do link na sua plataforma.
current_statusstringStatus atual do link. No momento da criação, sempre created. Veja Status do Link.
authorization_urlstringURL para onde o cliente deve ser enviado para aprovar o Pix Automático.
date_createddateTimeData de criação do link no formato ISODateTime.
expires_atdateTimeData de expiração do link no formato ISODateTime.

Error Object​

AtributoTipoDescrição
api_referencestringURL para a documentação. Retornado nos erros de parâmetro.
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.

Redirecione o cliente para a authorization_url pelo servidor ou exiba um botão na sua página. Botões com âncora <a> costumam converter melhor do que redirecionamentos automáticos.

// Pelo servidor
redirect(link.authorization_url)

// Pela interface
<a href={link.authorization_url}>Autorizar Pix Automático</a>

A partir daqui, acompanhe o resultado pelos webhooks ou pela consulta do link.

Exemplos​

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real.

Request
curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "item_id": "MATRICULA_2026_00123",
  "contract_id": "CTR_2026_00123",
  "description": "Mensalidade Academia Jedi",
  "interval": "monthly",
  "reference_start_date": "2026-12-01",
  "min_variable_amount": 50000,
  "max_variable_amount": 80000,
  "is_retry_accepted": true,
  "expires_at": "2026-11-20T23:59:59.000Z",
  "customer": {
    "name": "Luke Skywalker",
    "document_number": "00099988877",
    "ip_address": "200.150.10.20"
  },
  "contract_debtor": {
    "name": "Luke Skywalker",
    "document_number": "00099988877"
  },
  "creditors": [
    {
      "name": "Academia Jedi Ltda",
      "document_number": "11222333000181"
    }
  ],
  "redirect_url": "https://suaaplicacao.com.br/obrigado",
  "webhook_url": "https://suaaplicacao.com.br/webhook",
  "webhook_auth_token": "1234567890",
  "metadata": {
    "plano": "anual"
  }
}'
Response200
{
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MATRICULA_2026_00123",
  "current_status": "created",
  "authorization_url": "https://checkout.marlim.co/automatic-pix/pXq3Lk9TzR2mWb7NcA1e",
  "date_created": "2026-11-12T14:19:18.051Z",
  "expires_at": "2026-11-20T23:59:59.000Z"
}