Agendar Cobrança

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 agendar um débito dentro de uma autorização ativa. A Marlim envia a cobrança ao banco do cliente, que tenta liquidar o valor na data informada.

POSTv3/automatic_pix/authorizations/:authorization_id/charges

Importante

A autorização precisa estar com o current_status igual a authorized, e o valor da cobrança deve respeitar as regras de valor aprovadas pelo cliente.

Prazo de agendamento

A cobrança deve ser agendada com antecedência de 2 a 10 dias da data de liquidação. Pedidos fora desse prazo retornam erro 400 no parâmetro date.

As retentativas de uma cobrança que falhou têm prazos próprios, descritos em Regras de Retentativa.

Request Variable Path

Atributo	Tipo	Descrição
authorization_id	string	ID Marlim da autorização.

Request Body Params

Atributo	Tipo	Descrição
date	date	Data de liquidação no formato YYYY-MM-DD.
amount	int32	Valor da cobrança. Deve ser passado em centavos.
item_id	string	Parâmetro opcional. ID da cobrança na sua plataforma. Recomendado para conciliação.
description	string	Parâmetro opcional. Texto exibido no extrato do cliente.
creditor_account	object	Objeto Conta recebedora.
creditor_account[document_number]	string	CNPJ ou CPF do titular da conta recebedora, somente números.
creditor_account[ispb]	string	ISPB da instituição recebedora (8 dígitos).
creditor_account[agency]	string	Número da agência, sem dígito.
creditor_account[account_number]	string	Número da conta, com o dígito verificador.
creditor_account[type]	string	Tipo da conta. Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento).
customer	object	Parâmetro opcional. Objeto Pagador. Envie quando a cobrança for disparada por uma ação do pagador.
customer[ip_address]	string	Parâmetro opcional do endereço IP público do cliente no formato IPv4 ou IPv6.
metadata	object	Parâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas.

Response Object

Retorna a cobrança com os campos descritos em Consultar Cobrança. As mudanças de status seguintes são enviadas para o webhook_url informado na criação do link.

Error Object

Atributo	Tipo	Descrição
api_reference	string	URL para a documentação. Retornado nos erros de parâmetro.
errors	array	Array com todos os erros encontrados ao processar a requisição.
errors[][type]	string	Tipo de erro ocorrido.
errors[][message]	string	Mensagem detalhada do erro ocorrido.

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.

Cobrança agendada

Request

curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/authorizations/aUt7Hq2LmZ9xVb3KcR8s/charges" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "date": "2026-12-05",
  "amount": 65000,
  "item_id": "MENSALIDADE_2026_12",
  "description": "Mensalidade dezembro",
  "creditor_account": {
    "document_number": "11222333000181",
    "ispb": "12345678",
    "agency": "0001",
    "account_number": "111882220",
    "type": "checking"
  }
}'

Response200

{
  "charge_id": "cHg4Tn8PqW1zLm6XbY2d",
  "authorization_id": "aUt7Hq2LmZ9xVb3KcR8s",
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MENSALIDADE_2026_12",
  "current_status": "scheduled",
  "date": "2026-12-05",
  "amount": 65000,
  "description": "Mensalidade dezembro",
  "customer": {
    "document_number": "00099988877"
  },
  "end_to_end_id": null,
  "has_retry": false,
  "original_charge_id": null,
  "error": null,
  "metadata": {},
  "date_created": "2026-11-25T17:33:06.364Z",
  "date_updated": "2026-11-25T17:33:08.608Z"
}

Autorização não ativa

Request

curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/authorizations/bNm4Jk7LpQ1wRt5YxC9v/charges" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "date": "2026-12-05",
  "amount": 65000,
  "creditor_account": {
    "document_number": "11222333000181",
    "ispb": "12345678",
    "agency": "0001",
    "account_number": "111882220",
    "type": "checking"
  }
}'

Response400

{
  "errors": [
    {
      "type": "status",
      "message": "Only authorizations with authorized status can receive charges."
    }
  ]
}

Data fora do prazo

Request

curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/authorizations/aUt7Hq2LmZ9xVb3KcR8s/charges" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "date": "2026-11-26",
  "amount": 65000,
  "creditor_account": {
    "document_number": "11222333000181",
    "ispb": "12345678",
    "agency": "0001",
    "account_number": "111882220",
    "type": "checking"
  }
}'

Response400

{
  "api_reference": "https://docs.api.marlim.co/automatic-pix/charges/create",
  "errors": [
    {
      "type": "date",
      "message": "The parameter [ date ] must be between 2 and 10 days after the scheduling date."
    }
  ]
}

Valor fora da regra aprovada

Request

curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/authorizations/aUt7Hq2LmZ9xVb3KcR8s/charges" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "date": "2026-12-05",
  "amount": 90000,
  "creditor_account": {
    "document_number": "11222333000181",
    "ispb": "12345678",
    "agency": "0001",
    "account_number": "111882220",
    "type": "checking"
  }
}'

Response400

{
  "api_reference": "https://docs.api.marlim.co/automatic-pix/charges/create",
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] must be between 50000 and 80000, as approved in the authorization."
    }
  ]
}

Autorização não encontrada

Request

curl -X POST "https://sandbox.api.marlim.co/v3/automatic_pix/authorizations/AABBCCDD/charges" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "date": "2026-12-05",
  "amount": 65000,
  "creditor_account": {
    "document_number": "11222333000181",
    "ispb": "12345678",
    "agency": "0001",
    "account_number": "111882220",
    "type": "checking"
  }
}'

Response404

{
  "errors": [
    {
      "type": "not_found",
      "message": "Authorization with id [AABBCCDD] was not found"
    }
  ]
}