Docs
Paying Pix v1

Paying Pix v1

This endpoint allows you to make payments from USDt to any given Pixkey, 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

If you set the currency as BRL then the amount will be paid exactly unless the payment hits after the rate changes and the change is significant so payment will be returned. If you set the amount in USDt then it'll be converted into BRL at the time of arrival with the actual exchange rate

❕ Minimum of 3 BRL is required for payments.

kamipay_id: as part of our Pay Service, we provide our users with a kamipay_id that can be used to monitor a specific transaction until operation is finalized.

external_id: users interacting with payments should provide their own id of this operation. This is of great importance as it brings several benefits:

  • if there is any problem during execution of the payment, the api_user can safely retry without risk of payments being executed twice. kamiPay will validate if that external_id was already used and in such case it'll return the original successful response.
  • webhooks and status endpoints can be queried and will include external_id information. Which is a more secure way of interacting with this endpoint.

Body Parameters

currency
required
'BRL' | 'USDT'

If you set the currency as BRL the endpoint will pay the exact number. If the money arrives and the oracle changes in the middle, then the tolerance is 50cts USDT otherwise payment will fail and money will be returned. Note: To avoid this, the oracle provides timeout so if you want to pay an exact number, make sure to only send payments with enough seconds before the oracle rate changes

If you set the currency in USDt, it'll show how many BRL are expected to be paid, but the payment will be made even if the oracle changes. So if you send a payment very close from the timeout, do expect minor fluctuations in the final amount

amount
required
float

Specifies the amount being sent, expressed as a float.

pix_key
required
string

Represents the PIX key for the recipient, which could be CPF, CNPJ, email, phone, or a PIX key.

from_address
required
string

Specifies the sender wallet address.

external_id
optional
string

Our partner's internal transaction identifier.

Handling Parallel Requests

What happens with quick retries?

Status Created

When making requests to the payToPixKey endpoint, you need to be aware of the following behavior:

If you attempt to make a new request while a previous one is still being processed (i.e., while the blockchain transaction is being executed):

  • 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 behavior prevents concurrent transactions from creating conflicts in the API

This situation 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 payToPixKey endpoint and the status endpoint

Note: These status codes will apply to both the payToPixKey endpoint and the tx_status endpoint.

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 samples

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