Criar um Cash-In Pix

Endpoint dedicado para criação de cobrança (cash-in) utilizando Pix como forma de pagamento.

POST/v1/chash-in/pix

Request Body Params

Todos os parâmetros listados abaixo são obrigatórios, com exceção daqueles marcados como opcionais.

Propriedade	Tipo	Descrição
amount	int32 || float	Valor a ser cobrado. Caso o valor contenha centavos, deverá ser passado no formato float (Ex. 100.12 -> Cem reais e doze centavos).
item_id	string	ID de cobrança/pedido em sua plataforma.
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 CPF do cliente.
customer[phone_number]	string	Número de telefone do cliente.
customer[address]	objeto	Objeto endereço do cliente.
customer[address][zipcode]	string	CEP do endereço do cliente.
customer[address][country]	string	Nacionalidade do cliente, no formato da sigla do país. Somente o formato ISO 3166-1 alfa-2 (duas letras) será aceito Ex.: BR, US, CA...
customer[address][state]	string	Estado do endereço atual do cliente, no formato da sigla do estado, ISO 3166-1 alpha-2 (duas letras). Ex.: TX, WY, MO...
customer[address][city]	string	Cidade do endereço do cliente.
customer[address][neighborhood]	string	Bairro do endereço do cliente.
customer[address][street]	string	Rua do endereço do cliente.
customer[address][number]	string	Número do endereço do cliente.
customer[address][complement]	string	Parâmetro opcional do complemento do endereço do cliente.
soft_descriptor	string	Descrição do pagamento da cobrança que aparecerá no extrato bancário do cliente.
expiration	int32	Parâmetro opcional do tempo de expiração em segundos após criação. Se não for passado nenhum valor o tempo será o padrão de 86400 segundos (24 horas).
simulate_status	string	Parâmetro opcional para "simular" alguns status durante a fase de desenvolvimento, uma vez que não é possível pagar uma transação Pix em Sandbox. Valores aceitos: paid, failed e expired.
webhook_url	string	Parâmetro opcional para receber notificações sobre todas as alterações de status de uma cobrança.
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.

Response Object

Quando uma operação de saque bem-sucedida é criada em nossa API, abaixo está o payload do objeto de resposta.

Propriedade	Tipo	Descrição
status	string	Status para validar que a operação foi bem-sucedida e o pix está ativo. Valor padrão: active.
date_created	dateTime	Data de criação da operação no formato ISODateTime.
date_updated	dateTime	Data de atualização do status da operação no formato ISODateTime.
cash_in_id	string	Número identificador da operação Marlim.
amount	int32 || float	Valor a ser cobrado do cliente pagante.
paid_amount	int32 || float	Valor pago pelo cliente pagante. Valor padrão: 0.
customer_name	string	Nome do cliente pagante.
customer_document_number	string	Número do documento do cliente pagador.
pix_copy_paste	string	String para o cliente copiar e colar para efetuar o pagamento no aplicativo do banco.
pix_image_base64	string	String para criar o QR Code na UI da sua aplicação para o cliente efetuar o pagamento no aplicativo do banco.

Webhooks

Todo o processo de alteração do status de uma operação de saque é assíncrono. Portanto, é importante que você passe um webhook_url durante o processo de criação de uma operação para que sua aplicação receba todas as alterações de status. Esta url da sua aplicação pode ser aberta para receber payloads dos Servidores Marlim (você pode validar os payloads recebidos pela nossa aplicação), ou caso esta url exija autenticação, você pode passar um webhook_auth_token para o Marlim enviar os webhooks com autenticação no HEADER da requisição.

Valor	Descrição
paid	Operação paga e capturada com sucesso.
failed	O banco relatou uma falha no pagamento durante a captura.
cancelled	Por algum motivo operacional, este ID de cash-in foi cancelado e não pode mais ser pago.
expired	Após 24 horas sem concluir o pagamento, esse cash-in expira e não pode mais ser pago.

info

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 no Header da requisição: Authorization: Bearer {webhook_auth_token}.

Caso nenhum valor seja passado em webhook_url, você poderá consultar o status atual da operação futuramente utilizando o endpoint GET e filtrando o cash-in, utilizando a propriedade cash_in_id.

Exemplos

Nota

Os valores usados nos exemplos abaixo são apenas para fins ilustrativos e não devem ser usados para solicitações de teste. Num ambiente de desenvolvimento ou teste, utilize dados mais próximos de uma transação real (dados reais de um pagador). Se você usar valores fictícios, a API poderá não funcionar conforme o esperado.

Operação Autorizada

Request

curl -X POST "https://api.pix.marlim.co/v1/chash-in/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 10,
  "item_id": "123456789",
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone_number": "+5511988776655",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Some Neighborhood",
      "street": "Some Street",
      "number": "1234",
      "zipcode": "05544001"
    }
  },
  "soft_descriptor": "Star Wars Company"
}'

Response200

{
  "status": "active",
  "date_created": "2023-10-05T12:51:47.430Z",
  "date_updated": "2023-10-05T12:51:47.430Z",
  "cash_in_id": "os7WT0bCGbWxAjAv2eT6",
  "amount": 10,
  "paid_amount": 0,
  "customer_name": "Luke Skywalker",
  "customer_document_number": "00099988877",
  "pix_copy_paste": "00020101021226930014 --- 6304B67D",
  "pix_image_base64": "iVBORw0KGgoAAAANSUhE --- rkJggg=="
}