Introduction
Understand general concepts and response codes.

Welcome to the kamiPay documentation! Here you'll find everything you need to integrate kamiPay into your applications.

What is kamiPay?
kamiPay offers a flexible framework to integrate Pix Payment into your existing services. With kamiPay's integration with Pix, you can offer your users the possibility to:

Receive payments from bank accounts in Brazil
Pay to bank accounts in Brazil internationally
Receive payments in local currency or stablecoin
What are kamiPay APIs?
kamiPay API features powerful endpoints that simplify complex Fiat to Crypto operations into a simple set of APIs.

In our API set you will find:

Oracles: Get real-time exchange rate information
Pix Generation: Generate a Pix Payment request
Status: Get information about payment status
WebHooks: Receive push notifications about status changes
Pix Payment: Understand how to pay to a Brazilian account
Pix key Lookup: Verify the owner of a Pix key before making a payment
We also feature additional endpoints where local FIAT offramp is available.

Supported Blockchains
We support Polygon Blockchain for API connectivity. Specific Tron Support can be provided on a demand basis.

Authentication
In order to use our APIs, you will need to be provided with an API-User/Secret.

Note: Please contact us for more information.

If you have already obtained the API-User/Secret, check Authentication to get the access token and start using our APIs.

Base URL
The kamiPay API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP.

When you first connect, you'll get Development Credentials where the base URL is:


https://devnakamotoapi2.kamipay.io
Once your project is ready to go to production, we'll provide you access to:


https://api2.kamipay.io
Response Codes
kamiPay uses standard HTTP codes to indicate the success or failure of your requests.

In general:

2xx HTTP codes correspond to success
4xx codes are for user-related failures
5xx codes are for infrastructure issues
Status	Description
200	Successful request
201	Created
400	Check that the parameters were correct
401	Check that authentication credentials were correct
5xx	Indicates an error with kamiPay servers
Check Error Codes for a comprehensive breakdown of all possible API errors.



Error Codes
Troubleshoot problems with this comprehensive breakdown of all error codes.

Troubleshoot problems with this comprehensive breakdown of all error codes.

Error Schema
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by type.

invalid_required_field
Status: 400
Message: Bad Request
Suggested action: Check the error message to see what went wrong.
missing_api_key
Status: 401
Message: Unauthorized
Suggested action: Include the following header Authorization: apikey : YOUR_API_KEY or/and apiSecret : YOUR_API_SECRET in the request.
HTTP_406_NOT_ACCEPTABLE
Status: 406
Message: Unauthorized
Suggested action: Take a look at the error message as it indicates the value is outside ranges.
internal_server_error
Status: 500
Message: An unexpected error occurred.
Suggested action: Try the request again later.
bad_gateway
Status: 502
Message: Sometimes it's just an internal connection error that will be reported as BAD gateway.
Suggested action: Try the request again later.
service_unavailable
Status: 503
Message: Service is temporarily unavailable due to maintenance.
Suggested action: Try the request again later.




Authentication
Learn how to authenticate with the kamiPay API

All our endpoints are authenticated using JWT token standard. A specific endpoint will be provided so you can request for new tokens every time. Token Duration will depend on the specific use case ranging from an hour to 1 day. Custom durations can be evaluated on a case by case basis.

You will be provided a user and password that will be used to retrieve tokens. Tokens will then be used as bearer token for authentication through all the endpoints that you have been given access to.

Getting an Access Token
You can get the token authorization using the following step:

Node.js
Python
Go

const url = "baseURL/auth/token";
 
// Create a new FormData object
const body = new FormData();
 
// Append your data to the FormData object
body.append("username", "YOUR_USERNAME");
body.append("password", "YOUR_PASSWORD");
 
const response = await fetch(url, {
  method: "POST",
  body
});
Response
200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJrYW1pcGF5LWJhY2tlb",
  "token_type": "bearer"
}
Using the Token
After obtaining the access token, include it in the Authorization header for all API requests:


Authorization: Bearer YOUR_ACCESS_TOKEN



Oracle
Get real-time currency rates for your payments.

This is the endpoint provides the exchange rates between supported currencies. Supported currency pairs indicate what the input and output numbers mean, example USDTBRL means that the input amount is in USDT and the output will be the converted BRL amount at the current rate. Oracle Rates for USDBRL are fixed for a specific amount of time provided in the timeout key in the response.

Path Parameters
Name	Type	Description
pair	string	Required. BRLUSDT / USDTBRL / ARSBRL / BRLARS / USDTARS. The first pair is the one we put the amount for, and the second is the amount expected as output
type	string	Required. When you are receiving a payment is 'charge', if you are paying is 'pay'
amount	float	Required. Floating number
exchange	string	Optional. If you are using ARSBRL pair, you can add what specific rate from a local exchange you want to use. Default value will be taken from Yadio Average but if you want to select a specific local exchange you can add the key exchange=xxxx and you can type fiwind, lemoncash, belo, etc.
chain	string	Optional. Default value is polygon, but if you are operating with Tron you can also select Tron. While rates are the same it's safer to use the right chain in case there are are policy changes in future.
Example Request
Node.js
Python
Go

const pair = "BRLUSDT"
const type = "charge"
const amount = 100
 
const url = `${baseURL}/v2/oracle?pair=${pair}&type=${type}&amount=${amount}`
 
const response = await fetch(url, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
});
Response
200
400
401
500
503

{
  "status_code": 200,
  "msg": "Request ok",
  "data": {
    "total_brl": 100.0,
    "total_usdt": 19.37735,
    "rate": 0.193773,
    "timeout": 178
  }
}
Response Details
The response includes:

total_brl/total_usdt: The total amount you quoted and the expected amount after conversion. For instance, if I use 100 BRLUSDT, then I'll get total_brl: 100, and total_usdt: 19.37 meaning that this will be the amount I would get after receiving the payment.

If instead of type=charge you use type=pay, and you put BRLUSDT, it means that you will be setting the exact amount to be paid and it'll output the amount of USDt you need to send. If you put USDTBRL, you are defining how much USDt you want to send and it'll output how much BRL will be paid.



QR Code Creation
This is the main endpoint to generate QR Codes to receive payments in USDt.

This endpoint enables Dynamic QR Code Generation. These QR Codes require an amount to be set as well as an expiration in seconds and it will respond with a String that should be rendered as a QR Code for the payor to pay from its banking application.

Body Parameters
Name	Type	Description
address	string	Required. Specifies where to deposit the payment in USDt
expire	integer	Required. Expressed in seconds. Note: Cannot exceed 24 hours duration.
amount	float	Required. The amount to charge in BRL. Note: Cannot have more than 2 decimals.
external_reference	string	Optional. In this value you can pass any string that you consider relevant. It can be an internal identification in your system or any other text. The idea is to use it as link in case we need to do some verifications with your database.
Extra Body Parameters
After QR Codes are paid, USDTs will be sent directly to the specified wallet.

You can chose to receive all payments from your specific users/clients to the same wallet of yours and then distribute, or you can chose to send usdt directly to your clients. In case money needs to be distributed to different users, there are some extra body parameters like store, checkout that can be set specifically.

Contact Us for more details on these type of configurations so we can provide you with support on how best to implement depending on your use cae.

By default you should add one address to receive payments to. That address needs to be previously whitelisted with kamiPay to receive payments. Then you can also setup the duration of the QR code and the amount in BRL to be charged to the payor.

Name	Type	Description
store_id	integer	Optional. Store Id corresponds to an internal kamipay mapping to your api_user. Default value is 1 if this key is empty.
checkout_id	integer	Optional. Checkout Id corresponds to an internal kamipay mapping to your api_user. Default value is 1 if this key is empty.
chain	string	Optional. Default value is polygon. In case you are operating with Tron you can add 'tron'.
Example Request
Node.js
Python
Go

const url = "baseURL/v2/charge/create_dynamic_pix_b2b"
 
const body = {
  address: "0x46d52020**********1fbdcc297d",
  expire: 300,
  amount: 150,
};
 
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
Response
200
400
401
500
503

{
  "emv": "b74eb616ab32414aba182b58232e823a5204000053039865802BR592kamiPayInc",
  "operation_id": "1697640236643",
  "amount_brl": 150,
  "amount_usdt": 28.60243,
  "rate": 5.24431,
  "date": 1697640243,
  "expiration": 1697640543
}
Response Details
As a result of this process, you will get two very important inputs:

emv: This is what you will need to render into a QR code, so the payor can scan.

operation_id: This is the tracking number so you can then monitor status of this payment.



Tx Status
Charge
This endpoints should be used for manual inspection of different transactions.

Charge Status
kamiPay will automatically send webhooks for status update notifications but we recommend all integration to have this endpoint configured in case webhook was not properly received.

The main information about status progress will be found within the "data" key in the response.

So main status will be "ok" meaning, we acknowledge that we have that transaction and then within the data key you will have specific details of that transaction.

If at the top, the status says "failed" it means we don't have this transaction in our records yet. It may eventually be processed or received shortly after.

Path Parameters
Name	Type	Description
target	string	Required. tx_id or operation_id
type	string	Required. When you are receiving a payment is 'charge'
id	string	Required. Transaction hash or operation id
chain	string	Required. 'polygon' | 'tron'
Example Request
Node.js
Python
Go

const target = "tx_id"
const type = "charge"
const id = "0x36**************b2d3"
const chain = "polygon"
 
const url = `${baseURL}/v2/status/tx_status?target=${target}&type=${type}&id=${id}&chain=${chain}`
 
const response = await fetch(url, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
});
Response
There will be cases where a transaction is returned to the payor. When this happens, it'll occur within a few seconds and you will receive a response with "status": "ok" at the top level, but inside the data object there will be "status": "failed" as shown in the (Returned) example below. This means the money was successfully returned to the payor.

200 (Success)
200 (Returned)
400
401
500

{
  "status": "ok",
  "msg": "Request ok",
  "data": {
    "status": "done",
    "txid": "<<TxId>>",
    "operation_id": "1692110031865",
    "bank_txid": "E607Q5A3F-1572",
    "bank_account_nr": "690-5813-004",
    "internal_pix_id": "kk6g23**********aby004",
    "amount_brl": "188.16",
    "amount_usdt": "37.632000",
    "address_in": "kk6g232xxxxx13k550931",
    "address_out": "0x29edfcexxxxxfh13e3",
    "name": "PAULO SERGIO"
  }
}


Tx Status
Pay
Monitor payments you are sending to Brazilian accounts

Pay Status
Similar to Charge Service, kamiPay will provide all status information through Webhooks. Nonetheless it's strongly recommended all our integrations to have a way to manually/automatically inspect a transaction in case webhook was not captured.

For Pay Service, we include important types of identifiers:

kamipay_id: This is a unique identifier provided by kamiPay for this transaction

external_id: It's strongly recommended all our integrations to pass their own internal transaction_id when making payments so this can be used here for status update checks

tx_id: This is the transaction hash

operation_id: It's an internal banking number. Not typically used for validation in PayService

Path Parameters
Name	Type	Description
target	string	Required. external_id, kamipay_id, tx_id or operation_id
type	string	Required. When you are paying is 'pay'
id	string	Required. Specific transaction identifier based on target type
chain	string	Required. 'polygon' | 'tron'
Example Request
Node.js
Python
Go

const target = "tx_id"
const type = "pay"
const id = "0x36**************b2d3"
const chain = "polygon"
 
const url = `${baseURL}/v2/status/tx_status?target=${target}&type=${type}&id=${id}&chain=${chain}`
 
const response = await fetch(url, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
});
Response
When querying transaction status, you'll receive different responses depending on the current state of the transaction. Below are the possible status types and their meanings:

Processing Status
Description: The transaction has been sent to the blockchain and is in process. The bank field won't appear until the transaction is confirmed.

When it occurs: After a successful submission to the blockchain but before confirmation.

API Response Code: 200


{
  "status": "ok",
  "msg": "Request ok",
  "data": {
    "status": "processing",
    "operation_id": "1744115063604",
    "address_in": "0x1c0acf85329f8985a46656dfa159488fedce1ab4",
    "txid": "0x233c86e9a23ca44d229d9c9a62439e237a6c5dd2675b2418f44d339c75e15eab",
    "amount_usdt": "0.54103",
    "amount_brl": "3.15",
    "bank_txid": null,
    "name": "kamiPay Inc",
    "kamipay_id": "txc_01jranqegkf509bq5svh03ztt8",
    "external_id": "test235",
    "pix_key": "info@kamipay.io"
  }
}
Done Status
Description: The transaction has been completed successfully.

API Response Code: 200


{
  "status": "ok",
  "msg": "Request ok",
  "data": {
    "status": "done",
    "operation_id": "1744115063604",
    "address_in": "0x1c0acf85329f8985a46656dfa159488fedce1ab4",
    "txid": "0x233c86e9a23ca44d229d9c9a62439e237a6c5dd2675b2418f44d339c75e15eab",
    "amount_usdt": "0.54103",
    "amount_brl": "3.15",
    "bank_txid": "E200181832025020717363pzCRpHTszu",
    "name": "kamiPay Inc",
    "kamipay_id": "txc_01jranqegkf509bq5svh03ztt8",
    "external_id": "test235",
    "pix_key": "info@kamipay.io"
  }
}
Failed Status - (In transaction data)
Description: The payment was processed by the blockchain but failed, typically requiring a transaction refund.

When it occurs: After the blockchain has attempted to process the transaction but encountered an error.

API Response Code: 200


{
  "status": "ok",
  "msg": "Tx Failed, returned",
  "data": {
    "status": "failed",
    "refund_txid": "0x96a48088522ccaae8f60afa7d66290d0c2b3ebd3bb70630df79f105258d36547",
    "original_txid": "0xd17c0947a0ba00e932176b25f4dd0b42c6a51510e28355f433bb5f7391fc9833",
    "external_id": 123456789,
    "kamipay_id": "txc_01jjvpcdcwees8kfnvk9mq4gna"
  }
}
Failed Status - (In main status)
Description: A status that may appear when the transaction was sent but the bank has not yet started processing it.

When it occurs: This status can appear after the transaction has been sent, but before the bank has received or started processing it.

API Response Code: 200


{
  "status": "failed",
  "msg": "TX not found"
}
Wait and check the status again. This is an intermediate state that requires monitoring.

Less Common Status Codes
These status codes may occur in specific situations but are not part of the typical transaction flow.

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

Accepted Status
Description: The transaction with the specified kamipay_id or external_id is in process but has not yet been sent to the blockchain.

When it occurs: This status typically appears when a status check is performed very quickly after, or in parallel with, the payment request.

API Response Code: 201


{
  "status": "ok",
  "msg": "transaction in progress",
  "data": {
    "status": "accepted",
    "txid": null,
    "amount_usdt": null,
    "kamipay_id": "txc_01jkg5vktaer5aew712kjgrsn2",
    "external_id": "idemptency-1"
  }
}
This is part of the initial processing phase. Some fields in the response will be null until the transaction advances to the next stage. Wait and check the status again later.

Canceled Status
Description: The transaction was not sent to the blockchain and therefore does not require a refund as no funds were used.

When it occurs: This happens when there is a failure in the endpoint, such as a timeout in some part of our backend after a payment request was initiated. The operation is typically canceled at that point.

API Response Code: 200


{
  "status": "ok",
  "msg": "transaction canceled",
  "data": {
    "status": "canceled",
    "txid": null,
    "amount_usdt": null,
    "kamipay_id": "txc_01jkg5vktaer5aew712kjgrsn2",
    "external_id": "idemptency-1"
  }
}
The transaction was not processed. A new payment request may be necessary if you still want to make the payment. Since the transaction was canceled before blockchain processing, no funds were debited from your account.

Error Responses
When using the status endpoint, you may encounter these common error responses:

400
401
500

{
  "detail": "detailed error will be provided here"
}
This response indicates a bad request. Typically occurs when required parameters are missing or invalid.

Charge GET



Tx Status Lot
Query multiple transaction statuses within a time period

This is an endpoint specific for certain type of integrations. It allows the user to check all confirmed charge transactions in a given time period up to 24 hours range per request. It's only available for Charge Service at this point and it'll return a list with a dictionary inside providing all the information for each of the different payments received including external_reference key for validations.

Path Parameters
Name	Type	Description
store_id	int[]	Optional. You can pass a list of integers [1, 2, 3] to identify store. If not provided it's assume all.
checkout_id	int[]	Optional. You can pass a list of integers [1, 2, 3] to identify checkout. If not provided it's assume all.
start	EPOCH	Optional. Starting point of the selected time period.
end	EPOCH	Optional. End of the selected time period.
Example Request
Node.js
Python
Go

const store_id = [1, 2, 3]
const checkout_id = [1, 2, 3]
const start = 1718472442
const end = 1718418515
 
const url = `${baseURL}/v2/status/tx_status_lot?store_id=${store_id}&checkout_id=${checkout_id}&start=${start}&end=${end}`
 
const response = await fetch(url, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
});
Response
200
401
406
500

[
  {
    "store_id": "1",
    "checkout_id": "1",
    "operation_id": "1718462463281",
    "tx_hash": "txid5",
    "brl_requested": "25.00",
    "usdt_credited": "5.00000",
    "external_data": "Factura 6",
    "request_datetime": "1718472442.872",
    "credit_datetime": "1718472443.872"
  },
  {
    "store_id": "1",
    "checkout_id": "1",
    "operation_id": "1718399849145",
    "tx_hash": "txid1",
    "brl_requested": "150.00",
    "usdt_credited": "20.00000",
    "external_data": "Factura 2",
    "request_datetime": "1718418514.401",
    "credit_datetime": "1718418515.401"
  }
]
This endpoint is limited to returning transactions within a 24-hour period. For longer time ranges, make multiple requests with different start/end periods.


Paying Pix
Send payments to Brazilian bank accounts via 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
Node.js
Python
Go

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
200
201
400
401
409
500
503

{
  "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.


Withdraw
Send USDT or Matic back to your whitelisted address

This endpoint allows you to withdraw USDT or Matic from your kamiPay wallet to a previously whitelisted address.

Instructions are simple, just add the chain, token, amount, the address from and address to. If the addresses are not previously mapped to your user, the endpoint will fail with status 400.

Request Body
Name	Type	Description
chain	string	Required. Indicates the blockchain network in use. Currently only 'polygon' is supported.
token	string	Required. Represents the token to withdraw: 'usdt' or 'matic'.
amount	float	Required. Specifies the amount to withdraw, expressed as a float.
from_address	string	Required. Represents the sending wallet's address.
to_address	string	Required. Represents the receiving wallet's address. Must be previously whitelisted.
The receiving address must be previously whitelisted for your account. Non-whitelisted addresses will result in a 400 error.

Example Request
Node.js
Python
Go

const url = `${baseURL}/v1/wallet/withdraw`;
 
const body = {
  "chain": "polygon",
  "token": "usdt",
  "amount": 0.10,
  "from_address": "0x1c0aCxxxxxx488fEdce1ab4",
  "to_address": "0x6Fe712cxxxxxx0E72988e68"
};
 
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
Response
200
400
401
500

{
  "status": "ok",
  "msg": "transaction succesful",
  "data": {
    "status": "mined",
    "transactionHash": "0x0c5fabf2a7c76c809b345b6xxxxxd2d414b405033619067c9b425",
    "to": "00x6Fe712cxxxxxx0E72988e68",
    "usdt amount": 0.1
  }
}
Withdrawal transactions are processed on the blockchain and may take some time to complete depending on network conditions.

Always double-check the receiving address before initiating a withdrawal, as blockchain transactions cannot be reversed once confirmed.



Address Balance
Check the balance of a specific wallet address

This endpoint allows you to check the balance in a given address. Balance will be provided for Matic and USDT only.

Query Parameters
Name	Type	Description
chain	string	Required. Only 'polygon' is accepted.
address	string	Required. Address to check. It must be a previously assigned address to your user.
Example Request
Node.js
Python
Go

const chain = "polygon";
const address = "0x1c0aCFxxxxxxxxxxA8fEdce1ab4";
 
const url = `${baseURL}/v1/wallet/get_address_balance?address=${address}&chain=${chain}`;
 
const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});
Response
200
401
500

{
    "status": "ok",
    "msg": "Matic and USDt Balance",
    "data": {
        "address": "0x1c0aCFxxxxxxxxxxA8fEdce1ab4",
        "tokens": [
            {
                "token": "MATIC",
                "balance": 0.35916607409480106
            },
            {
                "token": "USDT",
                "balance": 1.758236
            }
        ]
    }
}
This endpoint provides real-time balance information for both MATIC (gas token) and USDT in the specified wallet address.



Pix Key Validation
Verify the owner of a Pix key before making a payment

Before sending money with our payment solution, it's important to ensure you are paying to the right person and no mistake is made with Pix Keys.

Pix Keys refer to the alias or ID used by Pix to route the payment to the appropriate bank account. Pix Keys can be of different forms:

CPF or CNPJ: local personal or company IDs (use only numbers without special symbols)
Email address
Phone number (include with country code, +55)
Random key (alphanumeric)
With this endpoint, passing the pix key you will receive the name of the bank account owner for verification.

Query Parameters
Name	Type	Description
pix_key	string	Required. The Pix key to validate (CPF/CNPJ, email, phone, or random key)
Validating a Pix key before making a payment helps ensure that funds are sent to the intended recipient and reduces the risk of errors.

Example Request
Node.js
Python
Go

const pixKey = "mati@kamipay.io";
 
const url = `${baseURL}/v1/payments/pixKeyValidation?pix_key=${pixKey}`;
 
const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});
Response
200
400
401
500
503

{
  "msg": "valid pix_key",
  "reformated_key": "mati@kamipay.io",
  "name": "PAULO SERGIO"
}
Response Fields
Field	Description
msg	Status message indicating if the Pix key is valid
reformated_key	The validated and potentially reformatted Pix key
name	The name of the bank account owner associated with the Pix key