Capturar Transação

Disponível apenas em Sandbox

Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para captura de transações em produção no momento.

Use esta rota para capturar uma transação previamente autorizada com o endpoint POST v3/transactions/authorize. A captura efetiva a cobrança no cartão do cliente, movendo o status da transação de authorized para paid.

Atenção

Somente transações com status authorized podem ser capturadas. Tentar capturar uma transação com qualquer outro status retornará um erro 403.

POSTv3/transactions/:transaction_id/capture

Request Variable Path

Atributo	Tipo	Descrição
transaction_id	string	ID Marlim da transação com status authorized.

cuidado

É necessário salvar o transaction_id que a Marlim retorna na solicitação de autorização na sua aplicação. Somente com este id será possível prosseguir com a captura.

Este endpoint não requer body na requisição.

Response Object

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Para este endpoint, o valor retornado será paid.
amount	int32	Valor em centavos cobrado na transação.
net_value	int32	Parâmetro opcional do valor líquido a ser recebido pela transação.
authorized_amount	int32	Valor em centavos autorizado na transação.
paid_amount	int32	Valor em centavos capturado na transação.
refunded_amount	int32	Valor em centavos estornado na transação.
installments	string	Número de parcelas em que o cliente pagou.
nsu	string	Código que identifica a transação na adquirente.
authorization_code	string	Código de autorização retornado pelo banco emissor.
transaction_id	string	Número identificador Marlim da transação.
item_id	string	ID da transação na sua plataforma.
payment_method	string	Método de pagamento utilizado na transação. Valores possíveis: credit_card.
date_created	dateTime	Data de criação da transação no formato ISODateTime.
date_updated	dateTime	Data de atualização do status da transação no formato ISODateTime.
card_holder_name	string	Nome do portador do cartão utilizado no pagamento.
card_brand	string	Bandeira do cartão utilizado no pagamento. Valores possíveis: visa, mastercard, amex, hipercard e elo.
card_first_digits	string	Primeiros 6 dígitos do cartão utilizado no pagamento.
card_last_digits	string	Últimos 4 dígitos do cartão utilizado no pagamento.
acquirer_status_code	string	Código identificador da resposta do Banco Emissor.
acquirer_status_message	string	Mensagem referente ao código da resposta do Banco Emissor.

Exemplo de Response

{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:01.000Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}

Error Object

Atributo	Tipo	Descrição
api_reference	string	Url para a documentaçã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.

Exemplo de Response — Transação não autorizada

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be captured."
    }
  ]
}

Exemplos

Captura com Sucesso

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/capture" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

{
  "status": "paid",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-05-04T19:16:28.362Z",
  "date_updated": "2026-05-04T19:16:28.362Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 1000,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "credit_card",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}

Status inválido

Request

curl -X POST "https://api.marlim.co/v3/transactions/HcDscltTIVK3VMAAOj7J/capture" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response403

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "status",
      "message": "Only transactions with authorized status can be captured."
    }
  ]
}