Capturar Transação

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

Contas com Cross Border

Esta rota não está disponível para contas com Cross Border habilitado e retorna 403 com o erro forbidden. Nessas contas, as transações são feitas pelas rotas de Cross Border.

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-11-04T14:39:43.467Z",
  "date_updated": "2026-11-04T14:39:43.467Z",
  "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."
    }
  ]
}