Paying Pix

This endpoint allows you to make payments from USDT to any given Pix key, which will reflect the balance in seconds into any bank account in Brazil.

Clients will be given a dedicated address to load up funds in USDT and Matic for gas. From those funds payments will be made.

Request Body

Name	Type	Description
pix_key	string	Required. The Pix key of the recipient. Can be a CPF/CNPJ, email, phone number, or random key.
currency	string	Required. Either 'BRL' or 'USDT'. Determines how the amount is interpreted.
amount	float	Required. Amount to be sent. Minimum of 3 BRL is required for payments.
from_address	string	Required. Specifies the sender wallet address.
external_id	string	Recommended. Your internal reference ID for this transaction. Will be returned in status updates and prevents duplicate payments.

Currency Handling: If you set the currency as BRL, the amount will be paid exactly unless the payment hits after the rate changes significantly (tolerance is 50cts USDT). If you set the currency as USDT, it'll be converted into BRL at the time of arrival with the actual exchange rate.

The minimum payment amount is 3 BRL.

Example Request

const url = `${baseURL}/v1/payments/payToPixKey`;
 
const body = {
  "currency": "BRL",
  "amount": 4.10,
  "pix_key": <<CPF/CNPJ/email/Phone/pixkey>>,
  "from_address": "0x1c0aCF853xxxxx9488fEdce1ab4",
  "external_id": "aaa-11112"
};
 
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body)
});

Response

{
  "status": "ok",
  "kamipay_id": "txc_01j3vrcvqbfn7tdsstdrm0xexa",
  "data": {
    "status": "broadcasted",
    "transaction_hash": "0x711e9ccbe828eb8xxxxxxxx9779190042d7c206b350dc98f7e209e1e",
    "usdt_amount": 0.7267
  },
  "external_id": "aaa-11112"
}

Transaction Identifiers

Identifier	Description
`kamipay_id`	A unique identifier provided by kamiPay to monitor a specific transaction until the operation is finalized.
`external_id`	Your own transaction identifier. Important for safely retrying failed payments without risk of duplicates, and for tracking in webhooks and status endpoints.

Handling Parallel Requests

What happens with quick retries?

Status: Created

When making requests to the Pay to Pix endpoint and a previous transaction is still being processed (blockchain transaction in execution):

The API will return a 202 status code
This indicates that the transaction was created but is still processing
The data field in the response will be null
This prevents concurrent transactions from creating conflicts

This commonly occurs when:

Making rapid successive requests
Implementing quick retries without proper delays
The blockchain network is experiencing high latency

Status: Cancelled

If a retry is attempted after the API has failed due to internal blockchain issues:

The API will return a 409 status code (Conflict)
This indicates that the original transaction was cancelled
This applies to both the Pay to Pix endpoint and the status endpoint

The payment process is asynchronous. After receiving a 202 status code, you should monitor the transaction status using the status endpoint to track when the payment is completed, or set up webhooks to receive notifications.

Be careful when specifying Pix keys. Each key type has a specific format, and sending incorrect formats will result in errors or delayed payments.