Create a Cash-Out

Dedicated endpoint for making a bank transfer operation (cash-out) to a user's bank account, using a Pix Key as the destination account identifier.

POST/v1/chash-out

Request Body Params

All parameters listed below are mandatory, with the exception of those marked as optional.

Attribute	Type	Description
amount	int32 || float	Amount to be transferred to the customer's account. If the value contains cents, it must be passed in float format (Ex. 100.12 -> One hundred reais and twelve cents).
item_id	string	Charge/Order ID on your platform.
pix_key	object	Pix key data object.
pix_key[type]	string	Pix key type. Accepted values: EMAIL, CPF, CNPJ, TELEFONE or CHAVE_ALEATORIA.
pix_key[value]	string	Pix key value. It must be informed according to the type of the Pix key.
pix[customer_document_number]	string	Paying user CPF document.
customer	object	Objeto dos dados do cliente responsável pela conta de transferência.
customer[name]	string	Customer name.
customer[email]	string	Customer email.
customer[document_number]	string	Customer document number (Brazilian CPF).
customer[phone_number]	string	Customer phone number.

info

The values TELEFONE and CHAVE_ALEATORIA of the field pix_key[type] need to be passed in PT-BR. The values literally translated into English would be:

TELEFONE = PHONE
CHAVE_ALEATORIA = RANDOM_KEY

Response Object

When a successful cash-out operation is created in our API, below is the payload of the response object.

Property	Type	Description
status	string	Status to validate that the operation was successful and the transfer is in the process of being carried out. Possible values: processing and failed.
status_description	string	Description to clarify about the status of the transfer.
date_created	dateTime	Operation creation date in ISODateTime format.
date_updated	dateTime	Operation status updated date in ISODateTime format.
cash_out_id	string	Marlim operation identifier number.
amount	int32 || float	Amount to be transferred to the customer account.
paid_off_amount	int32 || float	Final amount transferred to the customer's account according to the current status.
customer_name	string	Name of person responsible for the transfer account.
customer_document_number	string	Document number of the person responsible for the transfer account.

Webhooks

The entire process of changing the status of a cash-out operation is asynchronous. Therefore, it is important that you pass a webhook_url during the process of creating an operation so that your application receives all status changes. This url of your application can be opened to receive payloads from Marlim Servers (you can validate the payloads received by our application), or if this url requires authentication, you can pass a webhook_auth_token for Marlim to send the webhooks with authentication in the HEADER of the request.

Value	Description
fulfilled	Operation transferred and completed successfully.
pending	Transaction created at the acquirer and pending finalization.
failed	The bank reported a failure during the transfer.
cancelled	For some operational reason, this Transfer ID has been canceled and can no longer be updated.

Samples

Note

The values used in the examples below are for illustration purposes only and should not be used for testing requests. In a development or testing environment, use data that is closer to a real transaction (real data for a transfer). If you use dummy values the API may not work as expected.

Authorized Operation

Request

curl -X POST "https://api.bet.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-09-11T12:30:28.785Z",
  "date_updated": "2023-09-11T12:30:28.785Z",
  "cash_out_id": "BksUV4Bg0BOX3kEqlOsH",
  "amount": 5,
  "paid_off_amount": 0,
  "customer_name": "Leia S. O. Solo",
  "customer_document_number": "00099988877"
}