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.

POSTv3/pix

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`.

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.

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": "2025-11-04T18:29:37.729Z",
  "date_updated": "2025-11-04T18:29:37.729Z",
  "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

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": "2025-11-04T18:29:37.729Z",
  "date_updated": "2025-11-04T18:29:37.729Z",
  "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 Body Params​

Response Object​

Webhook URL​

Exemplos​

Request Body Params

Response Object

Webhook URL

Exemplos