Pay Status

kamiPay sends every status change of a payout through Webhooks. Even so, we strongly recommend that every integration can also inspect a transaction on demand, in case a webhook was not captured.

To look up a payout, use one of these identifiers:

kamipay_id: unique identifier kamiPay returns when you create the payment (txc_...).
external_id: your own transaction identifier, sent when you create the payment. We strongly recommend always sending one.

Payouts can only be looked up by kamipay_id or external_id. Payouts don't have an on-chain transaction, so tx_id doesn't apply. operation_id and e2e_id don't resolve payouts either.

Query Parameters

Name	Type	Description
target	string	Required. `kamipay_id` or `external_id`
type	string	Required. `pay`
id	string	Required. Value of the identifier selected in `target`
chain	string	Optional. `polygon` \| `tron`. Not needed for payouts.

Example Request

const target = "kamipay_id"
const type = "pay"
const id = "txc_01jranqegkf509bq5svh03ztt8"

const url = `${baseURL}/v2/status/tx_status?target=${target}&type=${type}&id=${id}`

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

import requests

target = "kamipay_id"
type = "pay"
id = "txc_01jranqegkf509bq5svh03ztt8"

url = f"{base_url}/v2/status/tx_status?target={target}&type={type}&id={id}"

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

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

package main

import (
  "fmt"
  "net/http"
)

func main() {
  target := "kamipay_id"
  typeParam := "pay"
  id := "txc_01jranqegkf509bq5svh03ztt8"

  url := fmt.Sprintf("%s/v2/status/tx_status?target=%s&type=%s&id=%s",
                    baseURL, target, typeParam, id)

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

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

Response

The response depends on the current state of the payout. The data.status field can take these values:

`data.status`	HTTP	Meaning
`created`	`201`	The payment was received and is being prepared. It hasn't reached the bank yet.
`canceled`	`200`	The payment was canceled before reaching the bank. No funds were debited.
`processing`	`200`	The bank received the payment and is settling it.
`confirming`	`200`	The payment is being confirmed with the bank.
`done`	`200`	The payment was completed successfully.
`failed`	`200`	The payment failed. The funds are returned to your balance.

A payout that was later refunded (for example, through a MED) still reports done here. To see the refund, use the Refund status endpoint or the Refund webhook.

Processing, Confirming, Done and Failed

These four states return the same fields:

API Response Code: 200

{
  "status": "ok",
  "msg": "Request ok",
  "data": {
    "status": "done",
    "service_type": "prepaid",
    "operation_id": "txc_01jranqegkf509bq5svh03ztt8",
    "address_in": "0x1c0acf85329f8985a46656dfa159488fedce1ab4",
    "txid": null,
    "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"
  }
}

Field	Description
`service_type`	Always `prepaid`.
`operation_id`	Identifier of the payment at the settling bank.
`address_in`	Your active vault address. It can be `null`.
`txid`	Always `null`. Payouts don't have an on-chain transaction.
`amount_usdt`	USDT amount debited, as a string with up to 6 decimals.
`amount_brl`	BRL amount paid, as a string with up to 2 decimals (for example `"50.0"`).
`bank_txid`	Pix End-to-End ID. It can be `null` until the bank assigns it.
`name`	Name of the Pix key owner.
`pix_key`	Destination Pix key.

failed doesn't include the failure reason (error_code, error_message, error_category) here. You receive it in the synchronous payout response and in the failed webhook. See Payout Failure Reasons.

The webhook also includes recipient_document, recipient_ispb, recipient_bank_name and timestamp. This endpoint doesn't return them yet.

Created

Description: The payment was received but hasn't reached the bank yet. This usually shows up when you check the status right after, or in parallel with, the payment request.

API Response Code: 201

{
  "status": "ok",
  "msg": "transaction in progress",
  "data": {
    "status": "created",
    "txid": null,
    "usdt_amount": null,
    "kamipay_id": "txc_01jkg5vktaer5aew712kjgrsn2",
    "external_id": "idemptency-1"
  }
}

Several fields are missing or null until the payment moves to the next state. Wait and check the status again.

Canceled

Description: The payment was canceled before reaching the bank. This happens when there is a failure on our side right after the payment request, such as a timeout. No funds were debited.

API Response Code: 200

{
  "status": "ok",
  "msg": "transaction canceled",
  "data": {
    "status": "canceled",
    "txid": null,
    "usdt_amount": null,
    "kamipay_id": "txc_01jkg5vktaer5aew712kjgrsn2",
    "external_id": "idemptency-1"
  }
}

The payment was not processed. If you still want to make it, send a new payment request.

Error Responses

{
  "detail": "Could not validate credentials"
}

Authentication failure. Check that your token is valid and that your credentials have access to this endpoint.

{
  "detail": "transaction with kamipay_id: 'txc_01jkg5vktaer5aew712kjgrsn2' does not exist"
}

No payout exists with that identifier. An external_id is only found among your own payouts.

{
  "detail": "An unexpected error occurred."
}

Server-side error. If this persists, please contact kamiPay support with details of your request.

Pay

On this page