Criar um Cash-Out

Endpoint dedicado para realizar uma operação de transferência bancária (cash-out) para a conta bancária do usuário, utilizando uma Chave Pix como identificador da conta de destino.

POST/v1/chash-out

Request Body Params

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

Atributo	Tipo	Descrição
quantidade	int32 || float	Valor a ser transferido para a conta do cliente. 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.
pix_key	object	Objeto de dados da chave Pix.
pix_key[type]	string	Tipo de chave Pix. Valores aceitos: EMAIL, CPF, CNPJ, TELEFONE ou CHAVE_ALEATORIA.
pix_key[value]	string	Valor da chave Pix. Deve ser informado de acordo com o tipo de chave Pix.
pix[customer_document_number]	string	Documento CPF do usuário pagante.
customer	object	Objeto dos dados do cliente responsável pela conta de transferência.
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.
webhook_url	string	Parâmetro opcional para receber notificações sobre todas as alterações de status de uma transferência.
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 cash-out bem-sucedida é criada em nossa API, abaixo segue o payload do objeto de resposta.

Propriedade	Tipo	Descrição
status	string	Status para validar que a operação foi bem sucedida e a transferência está em processo de execução. Valores possíveis: processing e failed.
status_description	string	Descrição para esclarecer sobre o status da transferência.
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_out_id	string	Número identificador da operação Marlim.
amount	int32 || float	Valor a ser transferido para a conta do cliente.
paid_off_amount	int32 || float	Valor final transferido para a conta do cliente de acordo com o status atual.
customer_name	string	Nome da pessoa responsável pela conta de transferência.
customer_document_number	string	Número do documento do responsável pela conta de transferência.

Webhooks

Todo o processo de alteração do status de uma operação de chash-out é 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
fulfilled	Operação transferida e concluída com sucesso.
pending	Transação criada na adquirente e finalização pendente.
failed	O banco relatou uma falha durante a transferência.
cancelled	Por algum motivo operacional, este ID de transferência foi cancelado e não pode mais ser atualizado.

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-out, utilizando a Ppropriedade cash_out_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 uma transferência). 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-out" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 5,
  "item_id": "987654321",
  "pix_key": {
    "type": "CPF",
    "value": "00099988877",
    "customer_document_number": "00099988877"
  },
  "customer": {
    "name": "Leia S. O. Solo",
    "email": "leia@jedimaster.sw",
    "document_number": "00099988877",
    "phone_number": "+5511988776655"
  }
}'

Response200

{
  "status": "processing",
  "status_description": "Transfer successfully created and queued for processing.",
  "date_created": "2023-10-05T12:51:47.465Z",
  "date_updated": "2023-10-05T12:51:47.465Z",
  "cash_out_id": "BksUV4Bg0BOX3kEqlOsH",
  "amount": 5,
  "paid_off_amount": 0,
  "customer_name": "Leia S. O. Solo",
  "customer_document_number": "00099988877"
}