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

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:

{
  "detail": "detailed error will be provided here"
}

This response indicates a bad request. Typically occurs when required parameters are missing or invalid.

Pay

On this page