---
updatedAt: 2026-11-12T11:25:11.000Z
agentTools:
  projectIndex: https://docs.decentro.tech/llms.txt
---

# Transaction Status Callback v2

This callback is triggered by Decentro to a custom end-point of the platform for each incoming and outgoing transaction initiated through Decentro, once it reaches its terminal status.

> 🙌 Important Note
>
> Please use only **Staging Credentials** on each API Reference page to test the APIs directly from our Documentation.

### API Endpoints

| Environment       | Endpoint                           |
| :---------------- | :--------------------------------- |
| Staging / Sandbox | <https://your.custom.endpoint.com> |
| Production        | <https://your.custom.endpoint.com> |

<br />

Salient points:

* Maximum 3 attempts to post the callback, post which the explicit Get status call has to be made for obtaining the transaction status.
* It is mandatory to adhere to the response structure as specified in the examples.
* It is recommended that you whitelist Decentro's originating IP.
* It is recommended that you share your auth of preference with us, which will then be propagated as part of the callback request.
* Callbacks will be triggered only in case of terminal statuses (failure or success) and not while the transaction is pending.
* BeneficiaryName and bankReferenceNumber will be present only when Decentro's banking partners respond accordingly.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "your_custom_endpoint",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://your.custom.endpoint.com"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/transactionStatus": {
      "post": {
        "summary": "Transaction Status Callback",
        "description": "",
        "operationId": "payments_api-payout-transaction-status-callback",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transaction_status": {
                    "type": "string",
                    "description": "The status of the transaction. Values passed: SUCCESS and FAILURE"
                  },
                  "transaction_amount": {
                    "type": "integer",
                    "description": "The transaction amount.",
                    "format": "int32"
                  },
                  "bank_reference_number": {
                    "type": "string",
                    "description": "Bank Reference Number of the transaction"
                  },
                  "callback_attempt": {
                    "type": "integer",
                    "description": "A numerical value that indicates the attempt no. of the callback",
                    "format": "int32"
                  },
                  "callback_timestamp": {
                    "type": "string",
                    "description": "Timestamp of the callback. Not the timestamp of the transaction."
                  },
                  "callback_txn_id": {
                    "type": "string",
                    "description": "A URN created for the transaction status callback"
                  },
                  "consumer_urn": {
                    "type": "string",
                    "description": "Unique urn assigned to client that they pass in request payload"
                  },
                  "decentro_txn_id": {
                    "type": "string",
                    "description": "The unique transaction identifier, passed against the payout request, by Decentro at the time of transaction initiation."
                  },
                  "orginal_callback_txn_id": {
                    "type": "string",
                    "description": "Unique identifier mapped to the first callback attempt."
                  },
                  "payer_account_number": {
                    "type": "string",
                    "description": "The Virtual Account from which the payout transaction took place."
                  },
                  "payer_account_ifsc": {
                    "type": "string",
                    "description": "The Virtual Account IFSC"
                  },
                  "payee_account_number": {
                    "type": "string",
                    "description": "The beneficiary account number of the payout request"
                  },
                  "payee_account_ifsc": {
                    "type": "string",
                    "description": "The beneficiary account IFSC"
                  },
                  "payee_vpa": {
                    "type": "string",
                    "description": "The beneficiary UPI ID will be present here."
                  },
                  "transaction_status_description": {
                    "type": "string",
                    "description": "The transaction message after the transaction is completed."
                  },
                  "purpose_message": {
                    "type": "string",
                    "description": "The purpose message passed in the payout request"
                  },
                  "transfer_type": {
                    "type": "string",
                    "description": "IMPS, UPI, NEFT and RTGS will be present here."
                  },
                  "reference_id": {
                    "type": "string",
                    "description": "The URN created by the platform in the Initiate Payout API"
                  },
                  "beneficiary_name": {
                    "type": "string",
                    "description": "The beneficiary name will be present here"
                  },
                  "provider_message": {
                    "type": "string",
                    "description": "Decentro recommends not to use this parameter"
                  },
                  "transaction_message": {
                    "type": "string",
                    "description": "Decentro recommends not to use this parameter"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Correct Acknowledgement": {
                    "value": "{\n  \"response_code\": \"CB_S00000\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "response_code": {
                      "type": "string",
                      "example": "CB_S00000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Incorrect Acknowledgement": {
                    "value": "{\n  \"response_code\": \"CB_E00009\"\n}"
                  },
                  "Unauthorised Access": {
                    "value": "{\n  \"response_code\": \"CB_E00013\"\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "title": "Incorrect Acknowledgement",
                      "type": "object",
                      "properties": {
                        "response_code": {
                          "type": "string",
                          "example": "CB_E00009"
                        }
                      }
                    },
                    {
                      "title": "Unauthorised Access",
                      "type": "object",
                      "properties": {
                        "response_code": {
                          "type": "string",
                          "example": "CB_E00013"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/transactionstatus": {
      "post": {
        "summary": "Transaction Status Callback v2",
        "description": "This callback is triggered by Decentro to a custom end-point of the platform for each incoming and outgoing transaction initiated through Decentro, once it reaches its terminal status.",
        "operationId": "payments_api-transaction-callbacks",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "attempt",
                  "timestamp",
                  "callbackTxnId",
                  "originalCallbackTxnId",
                  "transactionStatus",
                  "referenceId",
                  "decentroTxnId",
                  "transactionMessage",
                  "transferType",
                  "bankReferenceNumber",
                  "beneficiaryName",
                  "transactionAmount",
                  "providerMessage"
                ],
                "properties": {
                  "attempt": {
                    "type": "integer",
                    "description": "A numerical value that indicates the attempt no. of the callback",
                    "default": 1,
                    "format": "int32"
                  },
                  "timestamp": {
                    "type": "string",
                    "description": "Timestamp of the CALLBACK. Not the transaction itself."
                  },
                  "callbackTxnId": {
                    "type": "string",
                    "description": "A URN created for the transaction status callback",
                    "default": "D43F5G6H47UJ5G4F3R"
                  },
                  "originalCallbackTxnId": {
                    "type": "string",
                    "description": "The callback URN of the 1st attempt will be present here.",
                    "default": "D43F5G6H47UJ5G4F3R"
                  },
                  "transactionStatus": {
                    "type": "string",
                    "description": "The status of the transaction will be present here. \"success\" and \"failure\"",
                    "default": "success"
                  },
                  "referenceId": {
                    "type": "string",
                    "description": "The URN created by the platform in the Initiate Payout API",
                    "default": "1eeedb6d-b5ca-48ee-ac93-fbe9c11bc55e"
                  },
                  "decentroTxnId": {
                    "type": "string",
                    "description": "The URN provided by Decentro for the transaction",
                    "default": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                  },
                  "transactionMessage": {
                    "type": "string",
                    "description": "The purpose message will be present here",
                    "default": "test txn"
                  },
                  "transferType": {
                    "type": "string",
                    "description": "IMPS, UPI, NEFT and RTGS will be present here",
                    "default": "IMPS"
                  },
                  "bankReferenceNumber": {
                    "type": "string",
                    "description": "The bank reference number will be present here. (Note: If the transaction fails without a bank reference number, then this parameter will not be present)",
                    "default": "227715217094"
                  },
                  "beneficiaryName": {
                    "type": "string",
                    "description": "The beneficiary name will be present here",
                    "default": "someone"
                  },
                  "transactionAmount": {
                    "type": "integer",
                    "description": "The transaction amount will be present here",
                    "default": 100,
                    "format": "int32"
                  },
                  "providerMessage": {
                    "type": "string",
                    "description": "The provider message of the transaction will be present here.",
                    "default": "fundTransfer successfully processed"
                  }
                }
              },
              "examples": {
                "Successful Transaction": {
                  "value": {
                    "attempt": 1,
                    "timestamp": "2020-09-16 22:22:22",
                    "callbackTxnId": "CLBACKxx",
                    "originalCallbackTxnId": "CLBACKxx",
                    "transactionStatus": "success",
                    "referenceId": "company_reference_id_1",
                    "decentroTxnId": "DCTRTXxx",
                    "transactionMessage": "This is the message for a successful transaction",
                    "transferType": "IMPS",
                    "bankReferenceNumber": "abcdefghijk",
                    "beneficiaryName": "some_beneficiary_name",
                    "transactionAmount": 5,
                    "providerMessage": "Processed successfully"
                  }
                },
                "Failure Transaction": {
                  "value": {
                    "attempt": 1,
                    "timestamp": "2022-11-20T19:46:46.519395",
                    "callbackTxnId": "CLBACKxx",
                    "originalCallbackTxnId": "CLBACKxx",
                    "transactionStatus": "failure",
                    "referenceId": "company_reference_id_1",
                    "decentroTxnId": "DCTRTXxx",
                    "transactionMessage": "This is the message for a failure transaction",
                    "transferType": "IMPS",
                    "bankReferenceNumber": "abcdefghijk",
                    "beneficiaryName": "some_beneficiary_name",
                    "transactionAmount": 5,
                    "providerMessage": "Failed transaction"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Successfull Callback": {
                    "value": "{\n  \"response_code\": \"CB_S00000\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "response_code": {
                      "type": "string",
                      "example": "CB_S00000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Failed Callback": {
                    "value": "{\n  \"response_code\": \"CB_E00009\"\n}"
                  },
                  "Unauthourized Callbacks": {
                    "value": "{\n  \"response_code\": \"CB_E00013\"\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "title": "Failed Callback",
                      "type": "object",
                      "properties": {
                        "response_code": {
                          "type": "string",
                          "example": "CB_E00009"
                        }
                      }
                    },
                    {
                      "title": "Unauthourized Callbacks",
                      "type": "object",
                      "properties": {
                        "response_code": {
                          "type": "string",
                          "example": "CB_E00013"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```