Criar Transação com Pix

Para realizar uma cobrança via Pix, utilize esta rota para criar uma nova transação. Nossa API irá retornar entre outros dados o campo pix_copy_paste, responsável por fornecer o Pix Copia e Cola que deve ser disponibilizado ao cliente para que ele efetue o pagamento.

Cada transação Pix possui um tempo de expiração, que pode ser definido no momento da criação da transação através do campo expired. Caso não seja informado, o tempo padrão de expiração é de 24 horas (86.400 segundos). Após esse período, o Pix se torna inválido e não será mais possível realizar o pagamento.

Atenção

Em ambiente de Produção, para atender às normativas do Banco Central do Brasil, é necessário concluir o processo de KYP (Know Your Partner) junto ao nosso parceiro de processamento PIX.

Para esse procedimento, nosso time irá entrar em contato para solicitar as informações necessárias.

Após o envio e validação das informações solicitadas, o prazo estimado para abertura da conta junto ao parceiro é de até 48 horas.

POSTv3/pix

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.

Atributo	Tipo	Descrição
amount	int32	Valor final a ser cobrado do consumidor final. Deve ser passado em centavos.
item_id	string	ID da transação na sua plataforma.
soft_descriptor	string	Descrição que aparecerá na fatura do seu cliente. Máximo de 13 caracteres, sendo alfanuméricos e espaços.
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.
expired	int32	Parâmetro opcional. Tempo de expiração em segundos. Caso não seja informado, utilizamos o padrão de 86400 (24 h).
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`. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.
simulate_status	string	*Parâmetro opcional* que pode ser passado em ambiente de teste para simular o fluxo do Pix. Valores aceitos: `paid`, `failed`, `expired`.
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.

Exemplo de Request Body
{
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expired": 86400,
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11", 
      "number": "999887766"
    }
  }
}

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.

Split de Pagamento

A Marlim oferece a opção de Split de Pagamento para que sua aplicação possa criar uma transação com múltiplos recebedores, basta passar um array de objetos com sub_seller_id e amount no parâmetro split no corpo da requisição.

🕹 Exemplo de Request Body com Split de Pagamento

  {
    "amount": 1000,
    "item_id": "ABC123456789",
    "soft_descriptor": "Marlim Store",
    "expired": 86400,
    "customer": {
      "name": "Luke Skywalker",
      "email": "luke@jedimaster.sw",
      "document_number": "00099988877",
      "phone": {
        "country_code": "+55",
        "area_code": "11", 
        "number": "999887766"
      }
    },
    "split": [
      {
        "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
        "amount": 900
      }
    ]
  }

Response Object

Propriedade	Tipo	Descrição
status	string	Representa o estado atual da transação. Valores possíveis: `waiting_payment`, `failed`.
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.
item_id	string	ID da transação na sua plataforma.
payment_method	string	Método de pagamento utilizado na transação. Valores possíveis: `pix`.
transaction_id	string	Número identificador Marlim da transação.
amount	int32	Valor em centavos a ser cobrado na transação.
payout_amount	int32	Valor em centavos a ser repassado.
paid_amount	int32	Valor em centavos capturado na transação.
refunded_amount	int32	Valor em centavos estornado na transação.
pix_copy_paste	string \| null	Código Pix Copia e Cola que deve ser apresentado ao cliente para pagamento. Retorna `null` quando a transação falha ou é rejeitada.

Exemplo de Response
{
  "status": "waiting_payment",
  "date_created": "2025-07-09T14:46:20.598Z",
  "date_updated": "2025-07-09T14:46:20.598Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "mMaNRQqDAypdGatmyquR",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126360014br.gov.bcb.pix...6304ABCD"
}

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 vai enviar 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.
`failed`	Transação com falha no processo de captura na Adquirente.
`refunded`	Transação estornada.
`expired`	Transação expirou por exceder o tempo limite para pagamento.

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 do 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_

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

curl -X POST "https://suaaplicacao.com.br/pedidos/123456789/webhook" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \ 
-H "Authorization: Bearer 123456" \
-d '{
  "event": "transaction_status_changed",
  "current_status": "paid",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "date_created": "2026-11-03T17:17:45.616Z",
  "date_updated": "2026-11-03T17:17:45.616Z",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 1000,
  "refunded_amount": 0
}'

Exemplos

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 mais próximos de uma transação real.

Pix criado com sucesso
Faltando parâmetro
CPF Inválido
Split de Pagamento

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "paid",
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expiration": 3600,
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto"
}'

Response200

{
  "status": "waiting_payment",
  "date_created": "2026-11-03T17:17:45.616Z",
  "date_updated": "2026-11-03T17:17:45.616Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "mMaNRQqDAypdGatmyquR",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126360014br.gov.bcb.pix...6304ABCD"
}

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "paid",
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expiration": 3600,
  "customer": {
    "name": "Luke Skywalker",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto"
}'

Response200

{
  "errors": {
    "type": "parameter",
    "message": "The parameter [customer][email] is missing."
  }
}

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "simulate_status": "paid",
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expiration": 3600,
  "customer": {
    "name": "Luke Skywalker",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto"
}'

Response200

{
  "errors": {
    "type": "validation",
    "message": "The CPF provided is invalid."
  }
}

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expiration": 3600,
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  },
  "split": [
    {
      "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
      "amount": 900
    }
  ],
  "webhook_url": "https://webhook.site/123-456-789",
  "webhook_auth_token": "seu_token_secreto"
}'

Response200

{
  "status": "waiting_payment",
  "date_created": "2026-11-03T17:17:45.616Z",
  "date_updated": "2026-11-03T17:17:45.616Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "mMaNRQqDAypdGatmyquR",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126360014br.gov.bcb.pix...6304ABCD",
  "split": [
    {
      "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
      "amount": 900
    }
  ]
}

Request Body Params​

Split de Pagamento​

Response Object​

Webhook URL​

Exemplos​

Request Body Params

Split de Pagamento

Response Object

Webhook URL

Exemplos