Consultar 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 retornar os dados e o status atual de uma cobrança.

GETv3/automatic_pix/charges/:charge_id

Request Variable Path

Atributo	Tipo	Descrição
charge_id	string	ID Marlim da cobrança.

Response Object

Propriedade	Tipo	Descrição
charge_id	string	ID Marlim da cobrança. Guarde este ID: é com ele que você consulta, retenta e cancela a cobrança.
authorization_id	string	ID Marlim da autorização à qual a cobrança pertence.
link_id	string	ID Marlim do link que originou a autorização.
item_id	string	ID da cobrança na sua plataforma.
current_status	string	Status atual da cobrança. Valores possíveis: pending, scheduled, processing, debited, paid, rejected e canceled. Veja Status da Cobrança.
date	date	Data de liquidação agendada, no formato YYYY-MM-DD.
amount	int32	Valor da cobrança em centavos.
description	string	Texto exibido no extrato do cliente.
customer	object	Objeto Pagador.
customer[document_number]	string	CPF ou CNPJ do pagador.
end_to_end_id	string	Identificador Pix da transação (E2E). Retorna null até a cobrança ser enviada para liquidação.
has_retry	boolean	Indica se a cobrança já teve retentativas ou se ela própria é uma retentativa.
original_charge_id	string	Em retentativas, o charge_id da cobrança original. Retorna null nas demais cobranças.
error	object	Preenchido quando a cobrança é rejeitada. Retorna null nos demais casos.
error[code]	string	Código da rejeição. Veja Rejeições de Cobrança.
error[title]	string	Título da rejeição.
error[detail]	string	Detalhe da rejeição, em texto livre enviado pelo banco do cliente.
metadata	object	Objeto livre enviado no agendamento.
date_created	dateTime	Data de criação da cobrança no formato ISODateTime.
date_updated	dateTime	Data de atualização da cobrança no formato ISODateTime.

Atenção

Construa a sua lógica e a comunicação com o cliente a partir do error.code. O campo title é apenas descritivo e o detail é texto livre do banco, que muda de instituição para instituição.

Error Object

Atributo	Tipo	Descrição
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

Cobrança paga

Request

curl -X GET "https://sandbox.api.marlim.co/v3/automatic_pix/charges/cHg4Tn8PqW1zLm6XbY2d" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

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

Cobrança rejeitada

Request

curl -X GET "https://sandbox.api.marlim.co/v3/automatic_pix/charges/cHg4Tn8PqW1zLm6XbY2d" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

{
  "charge_id": "cHg4Tn8PqW1zLm6XbY2d",
  "authorization_id": "aUt7Hq2LmZ9xVb3KcR8s",
  "link_id": "pXq3Lk9TzR2mWb7NcA1e",
  "item_id": "MENSALIDADE_2026_12",
  "current_status": "rejected",
  "date": "2026-12-05",
  "amount": 65000,
  "description": "Mensalidade dezembro",
  "customer": {
    "document_number": "00099988877"
  },
  "end_to_end_id": "E12345678202612050800abcdef65432",
  "has_retry": false,
  "original_charge_id": null,
  "error": {
    "code": "refused_by_bank",
    "title": "Payment refused",
    "detail": "Free text sent by the customer's bank"
  },
  "metadata": {},
  "date_created": "2026-11-25T17:33:06.364Z",
  "date_updated": "2026-12-05T08:01:12.010Z"
}

Cobrança não encontrada

Request

curl -X GET "https://sandbox.api.marlim.co/v3/automatic_pix/charges/AABBCCDD" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response404

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