kamiPay LogokamiPay Docs

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 Error

Response Fields

FieldTypeDescription
wallet_idintegerWallet identifier. Use this when creating a checkout.
wallet_descstringHuman-readable description of the wallet.
addressstringBlockchain address where settlements are sent.
network_idintegerThe 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

NameTypeDescription
addressstringRequired. The wallet address on Polygon.
chainstringRequired. The wallet's network. Send "polygon".
countrystringRequired. 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_typestringRequired. The type of the holder's identity document: a type that country issues, as Document Types shows. The API ignores letter case.
tax_idstringRequired. 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_namestringRequired. The holder's name. If the request creates a store, this is also the store name.
emailstringRequired. The holder's email address.
phonestringRequired. The holder's phone number, with the country code ("+5491112345678").
wallet_descstringRequired. A description of the wallet. It is also the description of the checkout.
postal_addressstringRequired. The postal address. If the request creates a store, this is the store address.
store_idintegerOptional. An existing store of your merchant account. If you do not send it, the request creates a new store.
checkout_idintegerOptional. 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):

typeExample msg
missingField required
value_errorcountry must be an ISO 3166-1 alpha-3 code
value_errorcountry must be BRA for a CPF
value_errordocument_type must be one of CE, CI, CNPJ, CPF, CPP, CUIL, CUIT, CURP, DNI, INE, NIT, OTHER, PASSPORT, RFC, RUC, RUT
value_errordocument_type CUIT is not valid for country CHL
value_errortax_id is not a valid CUIT
{
  "detail": "unexpected error"
}

Response Fields

FieldTypeDescription
store_nrintegerThe store of the checkout: the store_id that you sent, or the new store.
checkout_idintegerThe checkout linked to the wallet.
whitelist_statusstring"address whitelisted" for a new address, or "address was already whitelisted in the system".
detailstringA confirmation message.

On this page