Create a Pix Cash-In

Dedicated endpoint to create a charge (cash-in) using Pix as a payment method.

POST/v1/chash-in/pix

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 charged. 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.
customer	object	Cliente object.
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.
customer[address]	object	Customer address object.
customer[address][zipcode]	string	CEP (domestic customers - in Brazil) of the customer.
customer[address][country]	string	Customer's nationality, in country acronym format. Only the ISO 3166-1 alpha-2 (two-letter) format will be accepted E.g.: BR, US, CA...
customer[address][state]	string	State of the current customer address, in State acronym format, ISO 3166-1 alpha-2 (two-letter). E.g.: TX, WY, MO...
customer[address][city]	string	City of the customer's address.
customer[address][neighborhood]	string	Neighborhood of the customer's address.
customer[address][street]	string	Street of the customer's address.
customer[address][number]	string	Customer's address number.
customer[address][complement]	string	Optional parameter of the complement of the customer's address.
soft_descriptor	string	Charge payment description that will appear on the customer's bank statement.
simulate_status	string	Optional parameter to "simulate" some statuses during the development phase, since it is not possible to pay a Pix transaction in the Sandbox. Accepted values: paid and failed.
webhook_url	string	Optional parameter to receive notifications about all status changes of a charge.
webhook_auth_token	string	Optional parameter to authenticate the notifications sent to the webhook_url. If the parameter is not informed, the notifications will be sent without authentication.

Response Object

When a successful cash-in 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 pix is active. Default value: active.
date_created	dateTime	Operation creation date in ISODateTime format.
date_updated	dateTime	Operation status updated date in ISODateTime format.
cash_in_id	string	Marlim operation identifier number.
amount	int32 || float	Amount to be charged to the paying customer.
paid_amount	int32 || float	Amount paid by the paying customer. Default value: 0.
customer_name	string	Paying customer name.
customer_document_number	string	Paying customer document number.
pix_copy_paste	string	String for the customer to copy and paste to make the payment in the bank application.
pix_image_base64	string	String to create the QR Code in the UI of your application for the customer to make the payment in the bank application.

Webhooks

The entire process of changing the status of a cash-in 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
paid	Operation paid and successfully captured.
failed	The bank reported a payment failure during capture.
cancelled	For some operational reason this cash-in ID was canceled and can no longer be paid.
expired	After 24 hours without completing the payment, this cash-in expires and can no longer be paid.

If no value is passed in webhook_url, you will be able to consult the current status of the operation in the future using the GET endpoint and filtering the cash-in, using the cash_in_id property.

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 from a payer). 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-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-09-11T12:30:28.746Z",
  "date_updated": "2023-09-11T12:30:28.746Z",
  "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=="
}