Criar Transação (Ouro Minas)

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. A resposta imediata do POST contém apenas marlim_transaction_id e status: "created".

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 net_amount e número de parcelas escolhidos.

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.: `CB91495AA9B`.
net_amount	int32	Valor líquido a ser cobrado. Deve ser passado em centavos. Ex.: R$ 10,00 = 1000.
paid_amount	int32	Valor total em centavos a cobrar do cliente (com juros). Deve ser igual ao retorno de GET /v1/om/installments. Obrigatório para credit e debit.
installments	string	Número de parcelas. Mínimo: 1, máximo: 12. Ex.: `"1"` à vista. Obrigatório para credit e debit.
payment_method	string	Método de pagamento. Valores aceitos: credit, debit, 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. Valores aceitos: cpf, cnpj, 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á o resultado da transação (aprovado/recusado) via POST.
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.
om_sale_me_quantity	int32	Quantidade em moeda estrangeira. Deve ser passado em centavos.
om_sale_iof	float	Valor do IOF. Deve ser passado em valor decimal (ex.: 18.0).

Headers obrigatórios

Header	Descrição
api_key	Chave de API Marlim.
Content-Type	`application/json`

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",
  "om_sale_me_quantity": 30000,
  "om_sale_iof": 18.0000
}

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

Resposta síncrona (200)

A resposta imediata do POST contém apenas:

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.

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.

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.
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_brand	string	Bandeira do cartão.
card_last_digits	string	Últimos dígitos do cartão.
card_first_digits	string	Primeiros dígitos do cartão.

Códigos da adquirente

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.

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}

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_brand": "mastercard",
    "card_last_digits": "5364",
    "card_first_digits": "5364",
  }'

Atenção

Você deve validar a origem do webhook, ou seja, se ele foi realmente enviado pelos servidores da Marlim. Para isso, a Marlim envia no Header do POST os valores User-Agent (sempre Marlim/1.0.0) e Marlim-Api-Signature (sua api_key sem os prefixos 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": "validation",
      "message": "The expected value of the installments for 2 does not match the forecast.."
    }
  ]
}

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",
    "om_sale_me_quantity": 30000,
    "om_sale_iof": 18
  }'

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_brand": "mastercard",
  "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_brand": "mastercard",
  "card_last_digits": "5364",
  "card_first_digits": "5364"
}

Request Body Params​

Atenção

Headers obrigatórios​

Importante

Response Object​

Resposta síncrona (200)​

Resposta assíncrona (webhook)​

Atenção

Error Object​

Exemplos em Transações​

ATENÇÃO

Sucesso​

Request Body Params

Headers obrigatórios

Response Object

Resposta síncrona (200)

Resposta assíncrona (webhook)

Error Object

Exemplos em Transações

Sucesso