Criar Transação

Essa rota deve ser usada para criar uma transação Ouro Minas (pagamento via TEF no terminal PinPad).

O resultado do pagamento (aprovado/recusado) é enviado de forma assíncrona para o webhook_url informado no body.

POSTv1/om/transactions

Request Body Params

Atenção

Todos os campos do tipo string devem ser informados com caracteres alfanuméricos sem acentuação ou caracteres especiais. Valores monetários e de quantidade devem ser informados em centavos. O paid_amount deve coincidir com o retorno de GET /v1/om/installments para o mesmo net_amount (equivalente ao net_value do GET) e método de pagamento: use payment_method=debit no GET para débito e omita ou use payment_method=credit para crédito, conforme a documentação de parcelas.

Atributo	Tipo	Descrição
item_id	string	*Parâmetro opcional*. ID do item/request no sistema do cliente.
agent_terminal_id	string	ID do terminal Marlim (PinPad). Ex.: `AB12345AB1A`.
net_amount	int32	Valor líquido a ser cobrado. Deve ser passado em centavos. Ex.: R$ 10,00 = 1000.
paid_amount	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.
installments	string	Número de parcelas. No débito, a API trata sempre como 1x (à vista); envie `"1"` e alinhe o `paid_amount` ao GET /v1/om/installments?payment_method=debit. No crédito, de 1 a 12.
payment_method	string	Método de pagamento. Valores Aceitos: credit, debit e pix.
customer_name	string	Nome do cliente.
customer_document_number	string	Número do documento do cliente (apenas dígitos).
customer_document_type	string	Tipo do documento do cliente referente ao `customer_document_number` informado. Valores Aceitos: cpf, cnpj e passaporte.
customer_email	string	E-mail do cliente. Obrigatório para credit e debit.
customer_phone_number	string	Telefone do cliente, apenas números. Ex.: `11988776655`.
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 ao webhook_url. Caso não seja informado, as notificações serão enviadas sem autenticação.

Exemplo de Request Body

{
  "item_id": "123456789",
  "agent_terminal_id": "A0BC",
  "net_amount": 100000,
  "paid_amount": 104221,
  "installments": "3",
  "payment_method": "credit",
  "customer_name": "Luke Skywalker",
  "customer_document_number": "12345678900",
  "customer_document_type": "cpf",
  "customer_email": "luke@jedimaster.sw",
  "customer_phone_number": "11988776655",
  "webhook_url": "https://seu-dominio.com/webhook/om",
  "webhook_auth_token": "seu_token"
}

O paid_amount do débito deve ser o amount retornado por GET /v1/om/installments?net_value={net_amount}&payment_method=debit (a taxa de débito difere da primeira parcela de crédito).

Exemplo de Request Body (débito, 1x)

{
  "item_id": "123456789",
  "agent_terminal_id": "A0BC",
  "net_amount": 100000,
  "paid_amount": 101574,
  "installments": "1",
  "payment_method": "debit",
  "customer_name": "Luke Skywalker",
  "customer_document_number": "12345678900",
  "customer_document_type": "cpf",
  "customer_email": "luke@jedimaster.sw",
  "customer_phone_number": "11988776655",
  "webhook_url": "https://seu-dominio.com/webhook/om",
  "webhook_auth_token": "seu_token"
}

Importante

Nossa API não aceita em nenhum endpoint valores null, undefined ou string vazia. Caso você passe um parâmetro com algum desses 3 valores, irá retornar um erro. Se o parâmetro não for obrigatório e você não quiser que ele seja computado, basta remover da request.

Response Object

Propriedade	Tipo	Descrição
marlim_transaction_id	string	ID da transação na Marlim. Use para consultas e estorno.
status	string	Sempre created na resposta síncrona.

Exemplo de Response

{
  "marlim_transaction_id": "jvZXFHgHTc5Akefp7KBF",
  "status": "created"
}

Resposta assíncrona (webhook)

Quando a transação é finalizada no terminal, a Marlim envia um POST para o webhook_url com o payload completo.

Retry automático e consulta do último envio

Se o POST ao seu webhook_url falhar (rede, timeout, resposta 5xx, etc.), a API agenda novas tentativas automaticamente, com intervalo de cerca de 60 segundos entre cada uma, até um limite máximo configurado no servidor.

Para consultar o mesmo corpo JSON do POST ao seu webhook (sem metadados de retry), use GET /v1/om/webhooks/:transaction_id com a mesma API key da transação. Detalhes em Consultar último webhook.

Propriedade	Tipo	Descrição
card_emv_response	string	Resposta EMV do cartão.
status	string	Estado final. Valores: `paid`, `refused`.
authorization_code	string	Código de autorização da bandeira.
nsu	string	Identificador na adquirente.
acquirer_response_code	string	Resposta da adquirente. Valores: `0000`, `1000`, `1011`, `1016`, `5000`.
marlim_transaction_id	string	ID da transação (mesmo da resposta síncrona).
date_created	string	Data de criação (ISODate).
payment_method	string	Método de pagamento.
installments	string	Número de parcelas. Em transações debit, será sempre `"1"` (à vista).
authorized_amount	int32	Valor autorizado em centavos.
paid_amount	int32	Valor capturado em centavos.
paid_per_month	int32	Valor mensal em centavos.
interest_rate	float32	Taxa de adquirência (%).
interest_rate_per_month	int32	Taxa mensal em centavos.
interest_rate_total	int32	Taxa total em centavos.
card_last_digits	string	Últimos dígitos do cartão.
card_first_digits	string	Primeiros dígitos do cartão.

Importante

A propriedade acquirer_response_code, se constitue na seguinte tabela:

Prefixo	Significado
0000	Transação paga ou estornada.
1000	Transação não aprovada pelo banco.
1011	Senha incorreta.
1016	Cartão sem saldo.
5000	Erro bancário genérico. O cliente deve entrar em contato com o Banco Emissor.

Webhook URL

Todo o processo de mudança de status de uma transação é assíncrono. Por isso, é importante que você passe um webhook_url durante o processo de criação de uma transação para que sua aplicação receba todas as mudanças de status.

Se for passado algum valor no parâmetro webhook_auth_token a Marlim envia o token para a sua aplicação usando o padrão Authorization: Bearer no Header da requisição:

Authorization: Bearer {webhook_auth_token}

Abaixo, a tabela com os valores possíveis de status recebidos no webhook_url.

Status	Significado
paid	Transação paga e capturada com sucesso.
refused	Transação recusada pelo banco emissor.

Exemplo do BODY de um WEBHOOK da Marlim para a sua aplicação

curl -X POST "https://suaaplicacao.com.br/webhook/om" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token" \
  -d '{
    "card_emv_response": "B029841DC7A33FE0",
    "status": "paid",
    "authorization_code": "300164",
    "nsu": "17661083300164",
    "acquirer_response_code": "0000",
    "marlim_transaction_id": "jvZXFHgHTc5Akefp7KBF",
    "date_created": "2026-03-17T14:43:38.932Z",
    "payment_method": "credit",
    "installments": "2",
    "authorized_amount": 1063,
    "paid_amount": 1063,
    "paid_per_month": 532,
    "interest_rate": 3.12,
    "interest_rate_per_month": 32,
    "interest_rate_total": 63,
    "card_last_digits": "5364",
    "card_first_digits": "5364",
  }'

ATENÇÃO

Você deve validar a origem do webhook, isto é, se ele foi realmente enviado pelos servidores da Marlim. Para isso, enviamos no HEADER do POST dois valores:

User-Agent: sempre com o valor Marlim/1.0.0
Marlim-Api-Signature: o final da sua api_key removendo os valores mak_test_ e mak_live_

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://api.om.marlim.co/v1/om/transactions",
  "errors": [
    {
      "type": "wrong_card",
      "message": "The expected amount in 2 installments is not matching the expected value."
    }
  ]
}

Exemplos em Transações

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 válidos e o webhook_url para receber o resultado da transação.

Sucesso

Transação criada (resposta síncrona)
Webhook - paid
Webhook - refused

Request


  curl POST https://api.om.marlim.co/v1/om/transactions
  --H "Content-Type": "application/json"
  --H "api_key": "api_key_value"
  --data-raw '{
    "item_id": "123456789",
    "agent_terminal_id": "A0BC",
    "net_amount": 100000,
    "paid_amount": 104221,
    "installments": "3",
    "payment_method": "credit",
    "customer_name": "Luke Skywalker",
    "customer_document_number": "12345678900",
    "customer_document_type": "cpf",
    "customer_email": "luke@jedimaster.sw",
    "customer_phone_number": "11988776655",
    "webhook_url": "https://seu-dominio.com/webhook/om",
    "webhook_auth_token": "seu_token"
  }'

Response

{
  "marlim_transaction_id": "jvZXFHgHTc5Akefp7KBF",
  "status": "created"
}

Request


  curl POST Enviado ao seu webhook_url
  --H "Content-Type": "application/json"
  --H "api_key": "api_key_value"
  --data-raw '{
    "_info": "Payload enviado pela Marlim quando o pagamento é aprovado."
  }'

Response

{
  "card_emv_response": "B029841DC7A33FE0",
  "status": "paid",
  "authorization_code": "300164",
  "nsu": "17661083300164",
  "acquirer_response_code": "0000",
  "marlim_transaction_id": "jvZXFHgHTc5Akefp7KBF",
  "date_created": "2026-03-17T14:43:38.932Z",
  "payment_method": "credit",
  "installments": "2",
  "authorized_amount": 1063,
  "paid_amount": 1063,
  "paid_per_month": 532,
  "interest_rate": 3.12,
  "interest_rate_per_month": 32,
  "interest_rate_total": 63,
  "card_last_digits": "5364",
  "card_first_digits": "5364"
}

Request


  curl POST Enviado ao seu webhook_url
  --H "Content-Type": "application/json"
  --H "api_key": "api_key_value"
  --data-raw '{
    "_info": "Payload enviado pela Marlim quando o pagamento é recusado."
  }'

Response

{
  "card_emv_response": "",
  "status": "refused",
  "authorization_code": null,
  "nsu": "17661083300165",
  "acquirer_response_code": "1016",
  "marlim_transaction_id": "jvZXFHgHTc5Akefp7KBF",
  "date_created": "2026-03-17T14:44:00.000Z",
  "payment_method": "credit",
  "installments": "2",
  "authorized_amount": 0,
  "paid_amount": 0,
  "paid_per_month": 0,
  "interest_rate": 0,
  "interest_rate_per_month": 0,
  "interest_rate_total": 0,
  "card_last_digits": "5364",
  "card_first_digits": "5364"
}

Request Body Params​

Atenção

Importante

Response Object​

Resposta assíncrona (webhook)​

Retry automático e consulta do último envio

Importante

Webhook URL​

ATENÇÃO

Error Object​

Exemplos em Transações​

ATENÇÃO

Sucesso​

Request Body Params

Response Object

Resposta assíncrona (webhook)

Webhook URL

Error Object

Exemplos em Transações

Sucesso