Autorizar Transação

Disponível apenas em Sandbox

Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para pré-autorização em produção no momento.

Essa rota deve ser usada para autorizar uma transação com cartão sem capturá-la imediatamente. O valor é reservado no cartão do cliente, mas o débito efetivo só ocorre quando a captura for executada.

Esse fluxo é indicado quando sua aplicação precisa confirmar a disponibilidade de saldo antes de efetivar a cobrança — por exemplo, em cenários de reserva de hospedagem, aluguel de veículos ou qualquer operação onde a confirmação do serviço acontece após a autorização.

Após a autorização, você deve escolher entre:

Capturar a transação — efetiva a cobrança e move o status para paid.
Cancelar a transação — libera o valor reservado e move o status para canceled.

POSTv3/transactions/authorize

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 Body Params

Atenção

Todos os campos do tipo string devem ser informados com caracteres alfanuméricos sem acentuação ou caracteres especiais.

Os parâmetros aceitos neste endpoint são idênticos aos do POST v3/transactions. Consulte a documentação de criação de transação para a lista completa de campos disponíveis.

Atributo	Tipo	Descrição
amount	int32	Valor final a ser cobrado do cliente pagador. Deve ser passado em centavos.
installments	string	Número de parcelas da transação, sendo mínimo: 1 e máximo: 24. Por padrão o valor máximo é 12, para habilitar parcelamentos com mais de 12 vezes entre em contato com o nosso suporte.
item_id	string	ID da transação na sua plataforma.
card_holder_name	string	Nome do portador do cartão, apenas letras e espaços sem acentuação ou caracteres especiais. Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_number	string	Número do cartão. Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_expiration_date	string	Data de validade do cartão. Somente números no formato MMAA. Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_cvv	string	Código verificador do cartão. Caso inclua um card_id ou card_hash, esse campo torna-se dispensável.
card_id	string	ID de um cartão salvo e validado anteriormente. Caso inclua um card_hash ou os dados abertos do cartão, esse campo torna-se dispensável.
card_hash	string	Hash de um cartão criptografado manualmente usando uma chave pública. Caso inclua um card_id ou os dados abertos do cartão, esse campo torna-se dispensável.
customer	object	Objeto Cliente.
customer[name]	string	Nome do cliente.
customer[email]	string	E-mail do cliente.
customer[document_number]	string	Número do documento do cliente.
customer[phone]	object	Objeto número do telefone do cliente.
customer[phone][country_code]	string	Código do país do telefone do cliente (DDI), Ex: +55.
customer[phone][area_code]	string	Código do estado do telefone do cliente (DDD).
customer[phone][number]	string	Número do telefone do cliente.
customer[address]	object	Objeto Endereço do Cliente da fatura do cartão ou residência do cliente.
customer[address][country]	string	Nacionalidade do cliente, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: BR, US, UY... Máximo em caracteres: 2
customer[address][state]	string	UF da fatura do cartão ou residência do cliente, no formato sigla do estado. Ex: SP, RJ, MG... Máximo em caracteres: 2
customer[address][city]	string	Cidade da fatura do cartão ou residência do cliente. Máximo em caracteres: 50
customer[address][neighborhood]	string	Bairro da fatura do cartão ou residência do cliente. Máximo em caracteres: 45
customer[address][street]	string	Rua da fatura do cartão ou residência do cliente. Máximo em caracteres: 54
customer[address][number]	string	Número da fatura do cartão ou residência do cliente. Máximo em caracteres: 5
customer[address][complement]	string	*Parâmetro opcional* do complemento da fatura do cartão ou residência do cliente. Máximo em caracteres: 14
customer[address][zipcode]	string	CEP da fatura do cartão ou residência do cliente. Máximo em caracteres: 9
soft_descriptor	string	Descrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
sub_seller_id	string	*Parâmetro opcional* para identificar um sub_seller cadastrado na Marlim anteriormente, responsável pela transação.
split	array	Parâmetro opcional para o array de objetos com os dados do Split de Pagamento.
split[][sub_seller_id]	string	ID do parceiro que fará parte do Split de Pagamento.
split[][amount]	int32	Valor em centavos que o parceiro deverá receber do pagamento. Deve ser passado em centavos.
webhook_url	string	*Parâmetro opcional* para passar o endpoint do seu sistema que receberá informações a cada atualização da transação.
webhook_auth_token	string	Parâmetro opcional para autenticar as notificações enviadas para o `webhook_url`.
net_value	int32	*Parâmetro necessário* caso sua plataforma repasse a taxa de adquirência para o consumidor final. Valor líquido a ser recebido pela transação. Deve ser passado em centavos.
dfp_id	string	ID da URL que compõe o session_id criado na integração com o Antifraude da Marlim.
threeds_authentication_id	string	Parâmetro opcional que define o ID da autenticação 3DS retornado pelo SDK.
chargeback_owner	string	*Parâmetro opcional* que define quem será responsável pelo chargeback da transação. Valores aceitos: `acquirer` ou `seller`. Default: `acquirer`

Exemplo de Request Body
{
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "1225",
  "card_cvv": "123",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  }
}

Importante

Nossa API não aceita null, undefined ou empty em valores de string em qualquer endpoint. Se passar um parâmetro com qualquer um destes 3 valores, será retornado um erro. Caso o parâmetro não seja obrigatório e você não queira que ele seja computado, basta removê-lo da requisição.

Response Object

O objeto de resposta é idêntico ao do POST v3/transactions, com a diferença de que o campo status retornará authorized em vez de paid.

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Para este endpoint, o valor retornado será sempre `authorized`.
amount	int32	Valor em centavos a ser 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. Retorna `0` enquanto a transação estiver com status `authorized`.
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. Guarde este valor para utilizar nos endpoints de captura e cancelamento.
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.
card_id	string \| null	ID do cartão gerado pela Marlim após a autorização.
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": "authorized",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:00.000Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this 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 um Response com Erro
{
  "api_reference": "https://docs.api.marlim.co/transactions/create/card",
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] is missing."
    }
  ]
}

Webhook URL

Assim como no endpoint de criação de transação, você pode passar um webhook_url para receber notificações a cada mudança de status.

Status	Significado
`authorized`	Transação autorizada pelo banco emissor. O valor foi reservado no cartão, mas ainda não foi capturado.
`paid`	Transação capturada com sucesso após chamada ao endpoint POST v3/transactions/:transaction_id/capture.
`canceled`	Autorização cancelada antes da captura. O valor reservado foi liberado no cartão.
`refused`	Transação recusada pelo banco emissor.
`failed`	Transação com falha no processo de autorização na Adquirente.

Fluxo de Pré-Autorização

O fluxo completo de pré-autorização funciona em 3 etapas:

1º Autorizar
2º Capturar
2º Cancelar (alternativa)

Request

curl -X POST "https://api.marlim.co/v3/transactions/authorize" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "installments": "1",
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "card_id": "card_jedi123master4amidala5son",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    },
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "República",
      "street": "Rua Aurora",
      "number": "123",
      "complement": "Apto 42",
      "zipcode": "01209001"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789"
}'

Response200

{
  "status": "authorized",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-11-03T17:17:45.513Z",
  "date_updated": "2026-11-03T17:17:45.513Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The bank has authorized this amount on the card."
}

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-03T17:17:45.513Z",
  "date_updated": "2026-11-03T17:17:45.513Z",
  "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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The acquirer captured the amount on the card."
}

Request

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

Response200

{
  "status": "canceled",
  "nsu": "98765432",
  "authorization_code": "112233",
  "date_created": "2026-11-03T17:17:45.513Z",
  "date_updated": "2026-11-03T17:17:45.513Z",
  "amount": 1000,
  "authorized_amount": 1000,
  "paid_amount": 0,
  "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",
  "card_id": "card_123456789",
  "acquirer_status_code": "0000",
  "acquirer_status_message": "The authorization has been canceled."
}

Atenção

É necessário salvar o transaction_id retornado neste endpoint na sua aplicação. Somente com este ID será possível capturar ou cancelar a autorização posteriormente.

Request Body Params​

Response Object​

Error Object​

Webhook URL​

Fluxo de Pré-Autorização​

Request Body Params

Response Object

Error Object

Webhook URL

Fluxo de Pré-Autorização