Wallets
List the wallets available to your merchant account, and register a new wallet.
Wallets are registered during onboarding, or with Register Wallet, and determine where USDt settlements are sent after a payment is received. Each checkout must be linked to one wallet. Use the endpoint below to retrieve your available wallets before creating a checkout, and pick one on Polygon (network_id 5).
Access: every Account Administration endpoint needs credentials with the pay-in scope (the ones kamiPay gives you have it) and a user with a management role, which they normally have; otherwise 401 without the scope, or 403 without the role, so contact support.
List Wallets
GET /v2/merchants/wallets
Returns all wallets associated with your merchant account.
Example Request
const url = `${baseURL}/v2/merchants/wallets`
const response = await fetch(url, {
method: "GET",
headers: {
Authorization: `Bearer ${access_token}`,
},
});import requests
url = f"{base_url}/v2/merchants/wallets"
headers = {
"Authorization": f"Bearer {access_token}",
}
response = requests.get(url, headers=headers)package main
import (
"fmt"
"net/http"
)
func main() {
url := baseURL + "/v2/merchants/wallets"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", accessToken))
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error making request:", err)
return
}
defer resp.Body.Close()
}Response
[
{
"wallet_id": 1,
"wallet_desc": "Main wallet",
"address": "0x46d52020**********1fbdcc297d",
"network_id": 5
},
{
"wallet_id": 2,
"wallet_desc": "Secondary wallet",
"address": "0x8fa31120**********3acde918f",
"network_id": 5
}
]With an invalid or expired token:
{
"detail": "Could not validate credentials"
}With a valid token without the pay-in scope:
{
"detail": "Token Profile Not Authorized for this Endpoint"
}{
"detail": "User role not authorized for this endpoint"
}A plain-text body, not JSON:
Internal Server ErrorResponse Fields
| Field | Type | Description |
|---|---|---|
| wallet_id | integer | Wallet identifier. Use this when creating a checkout. |
| wallet_desc | string | Human-readable description of the wallet. |
| address | string | Blockchain address where settlements are sent. |
| network_id | integer | The wallet's blockchain network. 5 is Polygon, the only network a checkout takes. Any other value is a deprecated network, such as 3: assigning such a wallet to a checkout is rejected with 400 and "Wallet network deprecated", whether through Create Checkout, Update Checkout or the wallet_id or address of Create Printed Dynamic QR. |
Register Wallet
POST /v1/admin/sign_up/address_whitelistB2B
Registers a wallet on Polygon and links it to a checkout of your merchant account. Settlements of that checkout go to this wallet.
Access: this endpoint needs credentials with the pay-in scope. It does not check the user role.
Since 2026-10-21, country and document_type are required. They identify the wallet holder's identity document, together with tax_id. A request without them returns 422. A request that worked before that date must now add these two fields.
Request Body
| Name | Type | Description |
|---|---|---|
| address | string | Required. The wallet address on Polygon. |
| chain | string | Required. The wallet's network. Send "polygon". |
| country | string | Required. The country that issued the holder's identity document, as an ISO 3166-1 alpha-3 code ("ARG"). It is required for every document type, also for a CPF or CNPJ. With a CPF or CNPJ, it must be "BRA". |
| document_type | string | Required. The type of the holder's identity document: a type that country issues, as Document Types shows. The API ignores letter case. |
| tax_id | string | Required. The number of the holder's identity document. It must have the format of document_type, and a correct check digit if the type has one. The API ignores spaces, dots, dashes and slashes, so 20-12345678-6 and 20123456786 are the same CUIT. |
| company_name | string | Required. The holder's name. If the request creates a store, this is also the store name. |
| string | Required. The holder's email address. | |
| phone | string | Required. The holder's phone number, with the country code ("+5491112345678"). |
| wallet_desc | string | Required. A description of the wallet. It is also the description of the checkout. |
| postal_address | string | Required. The postal address. If the request creates a store, this is the store address. |
| store_id | integer | Optional. An existing store of your merchant account. If you do not send it, the request creates a new store. |
| checkout_id | integer | Optional. The checkout to create in the store, linked to this wallet. If you do not send it, the value is 1. The store must not already have a checkout with this ID. |
Example Request
const url = `${baseURL}/v1/admin/sign_up/address_whitelistB2B`
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${access_token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
address: "0x46d52020a1b2c3d4e5f60718293a4b5c1fbdcc29",
chain: "polygon",
country: "ARG",
document_type: "CUIT",
tax_id: "20123456786",
company_name: "Example Store SRL",
email: "payments@example.com",
phone: "+5491112345678",
wallet_desc: "Main wallet",
postal_address: "Av. Corrientes 1234, CABA",
}),
});import requests
url = f"{base_url}/v1/admin/sign_up/address_whitelistB2B"
headers = {
"Authorization": f"Bearer {access_token}",
}
body = {
"address": "0x46d52020a1b2c3d4e5f60718293a4b5c1fbdcc29",
"chain": "polygon",
"country": "ARG",
"document_type": "CUIT",
"tax_id": "20123456786",
"company_name": "Example Store SRL",
"email": "payments@example.com",
"phone": "+5491112345678",
"wallet_desc": "Main wallet",
"postal_address": "Av. Corrientes 1234, CABA",
}
response = requests.post(url, headers=headers, json=body)Response
{
"store_nr": 3,
"checkout_id": 1,
"whitelist_status": "address whitelisted",
"detail": "merchant/wallet addedd succesfully"
}If the address was already registered, whitelist_status is "address was already whitelisted in the system", and the request still creates the checkout.
store_id is greater than the last store of your merchant account:
{
"detail": "incorrect store_id"
}The store already has a checkout with checkout_id:
{
"detail": "store and checkout combination already exist"
}With an invalid or expired token:
{
"detail": "Could not validate credentials"
}With a valid token without the pay-in scope:
{
"detail": "Endpoint Not Authorized"
}The API returns all the errors of the request in one response. A field that is not in the body returns missing, and the API checks the other values only when all the required fields are present. For example, a request without document_type returns:
{
"detail": [
{
"type": "missing",
"loc": ["body", "document_type"],
"msg": "Field required",
"input": {
"address": "0x46d52020a1b2c3d4e5f60718293a4b5c1fbdcc29",
"chain": "polygon",
"country": "ARG",
"tax_id": "20123456786",
"company_name": "Example Store SRL",
"email": "payments@example.com",
"phone": "+5491112345678",
"wallet_desc": "Main wallet",
"postal_address": "Av. Corrientes 1234, CABA"
}
}
]
}The holder errors that you can get, each with one example of its msg (the document type or country in it changes):
type | Example msg |
|---|---|
missing | Field required |
value_error | country must be an ISO 3166-1 alpha-3 code |
value_error | country must be BRA for a CPF |
value_error | document_type must be one of CE, CI, CNPJ, CPF, CPP, CUIL, CUIT, CURP, DNI, INE, NIT, OTHER, PASSPORT, RFC, RUC, RUT |
value_error | document_type CUIT is not valid for country CHL |
value_error | tax_id is not a valid CUIT |
{
"detail": "unexpected error"
}Response Fields
| Field | Type | Description |
|---|---|---|
| store_nr | integer | The store of the checkout: the store_id that you sent, or the new store. |
| checkout_id | integer | The checkout linked to the wallet. |
| whitelist_status | string | "address whitelisted" for a new address, or "address was already whitelisted in the system". |
| detail | string | A confirmation message. |