Terminal Transaction Status Callback/Webhook

post https://your.custom.endpoint.com/transaction_status/clientcustomendpoint

This callback is used by Decentro to trigger the status of a transaction to pre-configured endpoint of the platform.

Overview

This callback allows the platform to proactively receive a transaction's status without having to check it from their end, thus reducing the computational burden and making it more efficient to propagate the status to the payer.

This callback allows a platform to receive the status of a transaction undertaken through any of the flows below.

The platform can share the endpoint for configuring this callback before going live at support@decentro.tech.

Points to Note

Key points to note.

This callback isn't triggered in case of a static QR code-based or push transaction.
This callback is triggered 3 times per transaction
This callback only propagates the transaction status
This callback is triggered when a transaction status moves to one of SUCCESS, FAILURE, EXPIRED.

Flow

Below is the flow for using the callback capability as part of Decentro

The platform consumes this callback to get the latest status of an initiated transaction from Generate payment link API, Generate Dynamic QR, Issue Collect Request or virtual accounts
In this callback, Decentro relays the transaction status via the transaction_status field and the transaction details. The default status will always be 'PENDING' unless the payer authorizes a payment.
The platform can map the transaction type at its end using the collection_type parameter triggered as part of the callback payload.
The platform acknowledges the callback by responding to it with 'CB_S00000' from its end. If any other value is passed, Decentro shall retrigger the callback.
If the platform cannot acknowledge the callback or handle the same at its end, the transaction status can also be fetched using Get Transaction Status in case of a UPI transaction.
If the platform wants to know the updated balance of the ledger account, it can receive it using the Account Balance Callback/Webhook.
The platform can handle the reason a transaction failed using the 'error_key' field in the callback, as mentioned in the Error Key section.

Error Keys

Decentro intimates the platform about the error leg i,e where the error has occurred in the transaction using the 'error_key' in the callback payload if it is a UPI transaction. Please note that error keys are for the platform's use, and standalone is not recommended for end-user messaging.

Below are the values propagated by Decentro, as well as the associated interpretation.

Error Key	Description
error_at_remitter_bank	The transaction failed due to an issue at the payer's bank, such as limits breached, an account frozen, etc.
error_at_beneficiary_bank	The transaction failed due to an issue at the Decentro's bank partner's end.
error_at_payer_psp	The transaction failed due to an issue at payer PSP, i.e., the UPI app used by the payer to authorize the transaction.
error_at_payee_psp	The transaction failed due to payee PSP, i.e., Decentro's partner bank's end.
error_at_npci	The transaction failed due to an issue at the NPCI level

Simulation Data

Overview

Decentro's simulation data helps developers simulate all the real-world scenarios using the Payment Link API.

This requires the platform to use standard request payloads to handle scenarios for each API and scenario, as mentioned below.

The platform must whitelist its IP and configure callback endpoints with Decentro if it wishes to handle the flow. Please reach out to us at support@decentro.tech for the same.

Flow

Decentro triggers the transaction status callback to the endpoints configured by Decentro as per the platform's requests. The callback for the testbed will mirror the fields in the documentation but will have the data as passed by the platform in any of the below APIs.

Body Params

callback_attempt

int32

required

Number of times the callback has been attempted.

callback_txn_id

string

required

Unique identifier mapped to the callback attempt.

consumer_urn

string

required

Unique urn assigned to client that they pass in request payload

callback_timestamp

string

required

Timestamp of the callback. Not the timestamp of the transaction.

original_callback_txn_id

string

Unique identifier mapped to the first callback attempt.

transaction_status

string

required

The status of the transaction. Values passed: SUCCESS, FAILURE, EXPIRED, REFUNDED, DEEMED.

transaction_status_description

string

Description message of the transaction status received.

amount

int32

required

The transaction amount.

decentro_txn_id

string

required

The unique transaction identifier, passed against the payment request, by Decentro at the time of transaction initiation.

reference_id

string

required

The referenceId passed at the time of transaction initiation. Passed only if the transaction is initiated through Decentro

bank_reference_number

string

required

The unique transaction reference number from the bank partner

npci_txn_id

string

A unique transaction id generated by NPCI for each transaction.

purpose_message

string

required

The purpose message value, shared during transaction initiation.

collection_type

string

The method of collection. Describes whether the funds were received via a payment link, dynamic QR, collect request, or a static QR. Only applicable for collection transactions. Possible values: payment_link, dynamic_qr

payee_name

string

required

Merchant name in case of collection transactions.

payer_name

string

Name of the payer if propagated by the partner bank

payee_account_number

string

Virtual account with Decentro against which the fund were credited

payee_account_ifsc

string

IFSC of the beneficiary virtual account created with Decentro

payer_vpa

string

UPI ID (VPA) of the payer.

payee_vpa

string

required

UPI ID (VPA) of the payee.

error_key

string

Indicates the reason for failure, if applicable.

transaction_attempt_status

string

Status of the transaction attempt. Possible values: HOLD, CAPTURED, RELEASED, DEEMED.

attempt_decentro_txn_id

string

The unique transaction identifier, created by Decentro, for the payment attempt.

transaction_authentication_timestamp

string

The timestamp at which user entered the MPIN and authenticated the payment.

payer_account_number

string

Account number of the payer/remitter. Passed only for virtual account based collections if provided by the bank partner.

payer_account_ifsc

string

Account ifsc of the payer/remitter. Passed only for virtual account based collections if provided by the bank partner.

type

string

'Duplicate Payment' will be the value when a transaction is duplicate

parent_decentro_txn_id

string

decentro_txn_id of the parent transaction that is already in terminal state. This value will populate when "type" parameter is "Duplicate Payment"

Headers

your_custom_key_1

string

required

The header token shared by you should not contain any unsanitized values like @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) (

your_custom_key_2

string

required

The header token shared by you should not contain any unsanitized values like @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) (

Responses

Language


xxxxxxxxxx
1
curl --request POST \
2
     --url https://your.custom.endpoint.com/transaction_status/clientcustomendpoint \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'


xxxxxxxxxx
 
1
{
2
  "response_code": "CB_S00000"
3
}

Overview

Points to Note

Flow

Error Keys

Simulation Data

Overview

Flow

200200

400400