Lots

Lots are batched on-chain transfers that group multiple payouts together for efficient blockchain settlement. This endpoint allows you to query lot details for reconciliation and transparency.

Lots are only available for payout (pay) transactions. Each lot contains one or more payouts and may include associated refunds.

List Lots

GET /v1/lots

List lots by date range. Returns a paginated list of lots for the authenticated user.

Query Parameters

Name	Type	Description
start_date	datetime	Required. Start of date range (ISO 8601 format).
end_date	datetime	Required. End of date range (ISO 8601 format).
limit	int	Maximum results to return (1-1000). Default: 100.
offset	int	Pagination offset. Default: 0.

Maximum date range is 31 days. For longer periods, make multiple requests with different date ranges.

Example Request

const params = new URLSearchParams({
  start_date: '2026-01-01T00:00:00Z',
  end_date: '2026-01-28T23:59:59Z',
  limit: '100',
  offset: '0'
});

const url = `${baseURL}/v1/lots?${params}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});

import requests

params = {
    'start_date': '2026-01-01T00:00:00Z',
    'end_date': '2026-01-28T23:59:59Z',
    'limit': 100,
    'offset': 0
}

url = f"{base_url}/v1/lots"

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

response = requests.get(url, params=params, headers=headers)

package main

import (
  "fmt"
  "net/http"
  "net/url"
)

func main() {
  baseURL := "https://api.kamipay.io"
  params := url.Values{}
  params.Add("start_date", "2026-01-01T00:00:00Z")
  params.Add("end_date", "2026-01-28T23:59:59Z")
  params.Add("limit", "100")
  params.Add("offset", "0")

  url := fmt.Sprintf("%s/v1/lots?%s", baseURL, params.Encode())

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", access_token))
  req.Header.Add("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "lots": [
    {
      "lot_id": "9c030c8b-6d68-445b-8048-1bacd91012fa",
      "transaction_hash": "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf",
      "usdt_amount": "10027.79968000",
      "created_at": "2025-05-07T19:36:52.907905Z",
      "status": "MINED"
    },
    {
      "lot_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "transaction_hash": "0xprocessing123456789012345678901234567890123456789012345678901234",
      "usdt_amount": "100.00000000",
      "created_at": null,
      "status": "PROCESSING"
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}

Date range validation error

{
  "detail": "Date range cannot exceed 31 days"
}

Invalid date order

{
  "detail": "end_date must be after start_date"
}

{
  "detail": "Incorrect Credentials"
}

Get Lot Details

GET /v1/lots/{lot_identifier}

Get complete lot details including all payouts and refunds associated with the lot.

Path Parameters

Name	Type	Description
lot_identifier	string	Required. Either a `lot_id` or a `transaction_hash`.

Flexible lookup: You can use either the lot ID or the blockchain transaction hash to retrieve lot details.

lot_id: UUID format (e.g., 9c030c8b-6d68-445b-8048-1bacd91012fa)
transaction_hash: 0x-prefixed, 66 characters (e.g., 0x812f8c44...5bdf)

Example Request

// Using lot_id (UUID)
const lot_identifier = "9c030c8b-6d68-445b-8048-1bacd91012fa";
// Or using transaction hash
// const lot_identifier = "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf";

const url = `${baseURL}/v1/lots/${lot_identifier}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});

import requests

# Using lot_id (UUID)
lot_identifier = "9c030c8b-6d68-445b-8048-1bacd91012fa"
# Or using transaction hash
# lot_identifier = "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf"

url = f"{base_url}/v1/lots/{lot_identifier}"

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

response = requests.get(url, headers=headers)

package main

import (
  "fmt"
  "net/http"
)

func main() {
  // Using lot_id (UUID)
  lotIdentifier := "9c030c8b-6d68-445b-8048-1bacd91012fa"
  // Or using transaction hash
  // lotIdentifier := "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf"

  url := fmt.Sprintf("%s/v1/lots/%s", baseURL, lotIdentifier)

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", access_token))
  req.Header.Add("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "lot_id": "9c030c8b-6d68-445b-8048-1bacd91012fa",
  "transaction_hash": "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf",
  "usdt_amount": "260.71233200",
  "created_at": "2025-05-07T19:36:52.907905Z",
  "status": "MINED",
  "payouts": [
    {
      "kamipay_id": "txc_01jrazd7a9fqpp0bym8km1dbd6",
      "external_id": "client-ref-001",
      "amount": "150.00000000",
      "currency": "usdt",
      "brl_amount": "834.00",
      "created_at": "2025-05-07T19:07:19.720238Z"
    },
    {
      "kamipay_id": "txc_01jrazd9c2gqr7sb8x0p4n5tea",
      "external_id": "client-ref-002",
      "amount": "75.50000000",
      "currency": "usdt",
      "brl_amount": "419.78",
      "created_at": "2025-05-07T19:07:19.720510Z"
    },
    {
      "kamipay_id": "txc_01jrazdb71hs8cv9q6m2r3wxky",
      "external_id": "client-ref-003",
      "amount": "8.14761900",
      "currency": "usdt",
      "brl_amount": "45.30",
      "created_at": "2025-05-07T19:07:19.720568Z"
    },
    {
      "kamipay_id": "txc_01jrazdf04js2pq7r1n9w8z6vh",
      "external_id": "client-ref-004",
      "amount": "42.81471300",
      "currency": "usdt",
      "brl_amount": "238.05",
      "created_at": "2025-05-07T19:08:02.114820Z"
    }
  ],
  "refunds": [
    {
      "kamipay_refund_id": "rpt_01jrazf2k7mvb5td3y4x9c1pgs",
      "kamipay_id": "txc_01jrazd7a9fqpp0bym8km1dbd6",
      "amount": "12.50000000",
      "currency": "usdt",
      "refund_brl_amount": "69.50",
      "created_at": "2025-05-07T19:24:47.821896Z"
    },
    {
      "kamipay_refund_id": "rpt_01jrazf5h9nxc8wd6a2b0e3qmt",
      "kamipay_id": "txc_01jrazdb71hs8cv9q6m2r3wxky",
      "amount": "3.25000000",
      "currency": "usdt",
      "refund_brl_amount": "18.07",
      "created_at": "2025-05-07T19:24:47.822305Z"
    }
  ]
}

{
  "detail": "Incorrect Credentials"
}

{
  "detail": "Lot not found"
}

Lot Fields

Field	Type	Description
`lot_id`	string	UUID identifier of the lot.
`transaction_hash`	string	On-chain transaction hash for the lot's batched transfer.
`usdt_amount`	string	Net amount of the lot in USDT (8 decimals). Equals the sum of `payouts[].amount` minus the sum of `refunds[].amount`, matching the value transferred on-chain in `transaction_hash`.
`created_at`	datetime \| `null`	Timestamp when the lot was settled on-chain. `null` while the lot has not yet been mined.
`status`	string	Lot status. See Lot Status Values.

Payout Fields

Field	Type	Description
`kamipay_id`	string	kamiPay identifier of the payout transaction.
`external_id`	string	Client-supplied identifier sent in the original `payToPixKey` call.
`amount`	string	Payout amount in USDT (8 decimals).
`currency`	string	Currency of the payout. Currently `"usdt"`.
`brl_amount`	string	Payout amount in BRL (2 decimals) liquidated to the PIX recipient.
`created_at`	datetime	Timestamp when the payout transaction was created.

Refund Fields

Field	Type	Description
`kamipay_refund_id`	string	kamiPay identifier of the refund transaction.
`kamipay_id`	string	`kamipay_id` of the original payout that was refunded. The original payout may live in a different lot than the one being queried.
`amount`	string	Refund amount in USDT (8 decimals).
`currency`	string	Currency of the refund. Currently `"usdt"`.
`refund_brl_amount`	string	Refund amount in BRL (2 decimals), as reported by the gateway.
`created_at`	datetime	Timestamp when the refund was registered by the gateway.

A payout may have multiple partial refunds: each one appears as a separate row in refunds, all sharing the same kamipay_id pointing at the original payout.

Lot Status Values

Status	Description
`PENDING`	Lot is created but not yet sent on-chain.
`PROCESSING`	Lot transaction is being processed on the blockchain.
`MINED`	Lot transaction has been confirmed on-chain.
`FAILED`	Lot transaction failed. Individual payouts may be retried in a new lot.

Use Cases

Reconciliation

Use the lots endpoint to reconcile your payout records with on-chain transactions:

Query lots for a date range using GET /v1/lots.
For each lot, verify transaction_hash on-chain. The transferred amount matches usdt_amount (the net of payouts and refunds in the lot).
Match payouts[].kamipay_id (or external_id) with your internal records.
Match refunds[].kamipay_id with your original payouts. A refund may live in a different lot than its payout.

Tracking a payout or its refund across lots

A payout settles on-chain in one lot, but any refund for that payout may settle in a later lot. To trace a payout end-to-end:

Query GET /v1/lots for the date range.
Search payouts[].kamipay_id to find the lot where the payout was settled.
Search refunds[].kamipay_id across all lots in your range to find any refunds linked to that payout (they may live in different lots than the original).

Tip: Store the lot_id or transaction_hash when you receive the payout webhook for easier future lookups.

Lots

On this page