--- agentTools: projectIndex: https://docs.decentro.tech/llms.txt --- # Account Balance This callback is triggered at a virtual account level every time there's a change in the balance > 🙌 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 | | | Production | | Via this callback, it is possible to get realtime updates to the [account balances](https://docs.decentro.tech/docs/virtual_accounts-callbacks). Salient points: * 3 times maximum retry, post which the explicit Get account balance call has to be made for obtaining the current account balance. * 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. * The type parameter can either be credit or debit. * The keys in the request will be in snake/ camel case based on the company configuration (defaulting to camel case if nothing opted). Response, however, has to be in snake case always. * The keys payeeAccountNumber, payeeAccountIfsc, payeeVpa, payerAccountNumber, payerAccountIfsc, payerVpa,payerName, payerMobileNumber will be present when the corresponding values are available, i.e. they are optional. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "", "version": "1.0" }, "servers": [ { "url": "https://your.custom.endpoint.com" } ], "security": [ {} ], "paths": { "/custom_endpoint": { "post": { "summary": "Account Balance", "description": "This callback is triggered at a virtual account level every time there's a change in the balance", "operationId": "virtual_accounts_api-account-balance", "parameters": [ { "name": "your_custom_key_1", "in": "header", "description": "The header token shared by you should not contain any unsanitized values like @ # $ % ^ & * ! ; : ' \\\" ~ ` ? = + ) (", "schema": { "type": "string" } }, { "name": "your_custom_key_1", "in": "header", "description": "The header token shared by you should not contain any unsanitized values like @ # $ % ^ & * ! ; : ' \\\" ~ ` ? = + ) (", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attempt": { "type": "integer", "description": "The callback attempt from Decentro when triggered to the platform's endpoint.", "default": 1, "format": "int32" }, "timestamp": { "type": "string", "description": "The timestamp when Decentro triggered the callback to the platform.", "format": "date-time" }, "callbackTxnId": { "type": "string", "description": "Decentro's unique ID for the callback attempt." }, "originalCallbackTxnId": { "type": "string", "description": "Decentro's unique ID for the 1st callback attempt." }, "accountNumber": { "type": "string", "description": "The virtual account number against which the callback is being triggered." }, "balance": { "type": "number", "description": "The updated balance of the virtual account after the transaction.", "default": 100000, "format": "float" }, "transactionMessage": { "type": "string", "description": "The associated transaction related message leading to change in balance.", "default": "Payment" }, "type": { "type": "string", "description": "The type of transaction that led of change in the balance." }, "transferType": { "type": "string", "description": "The type of transaction which resulted in change in balance. Values: RTGS, NEFT, IMPS, UPI", "default": "RTGS" }, "transactionAmount": { "type": "number", "description": "The transaction amount that resulted in change in balance.", "default": 10000, "format": "float" }, "decentroTxnId": { "type": "string", "description": "The unique ID passed by Decentro if the transaction was initiated through Decentro." }, "payeeName": { "type": "string", "description": "The name of the beneficiary who's receiving the funds. Can be the platform or the beneficiary.", "default": "Decentro" }, "payeeAccountNumber": { "type": "string", "description": "The virtual account number against which the callback is being triggered." }, "payeeAccountIfsc": { "type": "string", "description": "The IFSC code of the virtual against which the callback is being triggered." }, "payerVpa": { "type": "string", "description": "The VPA (UPI ID) of the payer who undertook a transaction. Only if the transaction is UPI collection.", "default": "sample@upi" }, "bankReferenceNumber": { "type": "string", "description": "The unique transaction reference number received by Decentro from its bank partner.", "default": "1234567890" }, "transactionType": { "type": "string", "description": "The type of transaction against which the callback is being triggered. Values - MAIN, COMMISSION, MAIN REVERSAL, COMMISSION REVERSAL", "default": "MAIN" }, "payerName": { "type": "string", "description": "The name of the payer from whom the transaction originated. Can be the platform or their user.", "default": "Decentro" } } }, "examples": { "Success: IMPS/NEFT/RTGS Credit": { "value": { "attempt": 1, "timestamp": "2020-09-16 23:23:23", "callbackTxnId": "CLBACKxx", "originalCallbackTxnId": "CLBACKxx", "accountNumber": "XXXXXXXXXXXXXXXXXX", "balance": 345, "transactionMessage": "message denoting the origination of balance update", "type": "credit", "transferType": "IMPS", "transactionAmount": 5, "decentroTxnId": "DCTRTXxx", "payerName": "", "payerAccountNumber": "", "payerAccountIfsc": "", "payeeName": "", "payeeAccountIfsc": "YESBXXXXXXXX", "providerCode": "YESB", "bankReferenceNumber": "" } }, "Success: UPI Credit": { "value": { "attempt": 1, "timestamp": "2020-09-16 23:23:23", "callbackTxnId": "CLBACKxx", "originalCallbackTxnId": "CLBACKxx", "accountNumber": "XXXXXXXXXXXXXXXXXX", "balance": 345, "transactionMessage": "message denoting the origination of balance update", "type": "credit", "transferType": "UPI", "transactionAmount": 5, "decentroTxnId": "DCTRTXxx", "payerAccountNumber": "", "payerAccountIfsc": "", "payerVpa": "" } }, "Success: Debit": { "value": { "attempt": 1, "timestamp": "2020-09-16 23:23:23", "callbackTxnId": "CLBACKxx", "originalCallbackTxnId": "CLBACKxx", "accountNumber": "XXXXXXXXXXXXXXXXXX", "balance": 345, "transactionMessage": "message denoting the origination of balance update", "type": "debit", "transferType": "IMPS", "transactionAmount": 5, "decentroTxnId": "DCTRTXxx", "payeeAccountNumber": "", "payeeAccountIfsc": "YESBXXXXXXXX", "providerCode": "YESB" } }, "Failure: Unauthorized": { "value": { "attempt": 1, "timestamp": "2020-09-16 23:23:23", "callbackTxnId": "CLBACKxx", "originalCallbackTxnId": "CLBACKxx", "accountNumber": "XXXXXXXXXXXXXXXXXX", "balance": 345, "transactionMessage": "message denoting the origination of balance update", "type": "credit", "transferType": "IMPS", "transactionAmount": 5, "decentroTxnId": "DCTRTXxx", "payerAccountNumber": "", "payerAccountIfsc": "", "payeeAccountIfsc": "YESBXXXXXXXX", "providerCode": "YESB", "bankReferenceNumber": "" } }, "Failure: Failed Callback": { "value": { "attempt": 1, "timestamp": "2020-09-16 23:23:23", "callbackTxnId": "CLBACKxx", "originalCallbackTxnId": "CLBACKxx", "accountNumber": "XXXXXXXXXXXXXXXXXX", "balance": 345, "transactionMessage": "message denoting the origination of balance update", "type": "credit", "transferType": "IMPS", "transactionAmount": 5, "decentroTxnId": "DCTRTXxx", "payerAccountNumber": "", "payerAccountIfsc": "", "payeeAccountIfsc": "YESBXXXXXXXX", "providerCode": "YESB", "bankReferenceNumber": "" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Success: For IMPS/NEFT/RTGS credit (200, 201)": { "value": "{\n \"response_code\": \"CB_S00000\"\n}" }, "Success": { "value": "{\n \"response_code\": \"CB_S00000\"\n}" } }, "schema": { "oneOf": [ { "title": "Success: For IMPS/NEFT/RTGS credit (200, 201)", "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_S00000" } } }, { "title": "Success", "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_S00000" } } } ] } } } }, "202": { "description": "202", "content": { "application/json": { "examples": { "Result": { "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": { "Success: For IMPS/NEFT/RTGS debit (200, 201)": { "value": "{\n \"response_code\": \"CB_S00000\"\n}" } }, "schema": { "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_S00000" } } } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Failure: Unauthorized Callback": { "value": "{\n \"response_code\": \"CB_E00013\"\n}" } }, "schema": { "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_E00013" } } } } } }, "2XX": { "description": "2XX", "content": { "application/json": { "examples": { "Success: For UPI credit (200, 201)": { "value": "{\n \"response_code\": \"CB_S00000\"\n}" } }, "schema": { "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_S00000" } } } } } }, "4XX": { "description": "4XX", "content": { "application/json": { "examples": { "Failed: Other (4xx)": { "value": "{\n \"response_code\": \"CB_E00009\"\n}" } }, "schema": { "type": "object", "properties": { "response_code": { "type": "string", "example": "CB_E00009" } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true, "_id": "6284a0ea1128220021979c1c:628b2cd019dc01002c188146" } ```