Debit Request

Introduction

In the ever-evolving landscape of financial technology, the Debit Request API emerges as a pivotal tool, seamlessly integrating the critical functionality of presenting mandates for the deduction of funds from a customer's bank account. This innovative API plays a central role in the automated and secure execution of financial transactions, specifically focusing on the post-registration phase of mandates.

At its core, the Debit Request API facilitates the streamlined process of requesting and initiating debit transactions after successfully registering a mandate. The mandate, in this context, serves as the customer's authorization for the withdrawal of a specified amount from their bank account. Once a mandate has been successfully established, the Debit Request API takes center stage, orchestrating the presentation of this authorization to the financial institution for the deduction of funds.

Key features of the Debit Request API include its robust security measures, ensuring the confidentiality and integrity of sensitive financial information. Moreover, the API operates with a keen focus on automation, reducing manual intervention and expediting the overall transaction process. This not only enhances efficiency but also minimizes the potential for errors that may arise from manual handling.

The Debit Request API is designed to empower financial institutions, businesses, and service providers with a reliable and standardized mechanism for handling debit transactions in a compliant and user-friendly manner. By leveraging this API, organizations can navigate the complexities of financial operations with greater ease, providing a seamless experience for both businesses and their customers in the realm of automated fund transfers.

Authentication

This API employs API Keys for request authentication. It's crucial to safeguard your API Keys, as they grant various privileges. To obtain the Access Key, kindly reach out to our Support/CSM team. Once obtained, please utilize this access key in the Authorization header.

Authentication for the API is executed through the Authorization header.

--header 'Authorization: YOUR_ACCESS_KEY_HERE'

Feel free to replace 'YOUR_ACCESS_KEY_HERE' with the actual Access Key provided by our Support/CSM team.

API Details

The details of the API can be found here.

Sample Request

curl --location 'https://api.signzy.app/api/v3/enach/debitrequest' \
--header 'Authorization: YOUR_ACCESS_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerAuthenticationId": "*******************",
    "amount": "8.0",
    "productInfo": "Netflix",
    "firstName": "**********",
    "phone": "***************",
    "email": "*****************",
    "successRedirectUrl": "https://www.google.com/",
    "failureRedirectUrl": "https://www.signzy.com/",
    "callbackUrl": "*****************************",
    "maxAmount": "20.0",
    "subMerchantId": "***************",
    "finalCollectionDate": "2024/12/31"
}'

Input Parameters

Here's a table outlining the key parameters, descriptions, whether they are mandatory or optional, and their data types.

Key	Description	Mandatory/Optional	Type
customerAuthenticationId	Customer authentication ID This is the customer authentication ID that you got from Initiate Payment API	Mandatory	String
amount	Amount of the transaction This is the amount that you want to deduct from the end customer's bank account as part of presenting the mandate. It should be less and equal to maximum amount always (the maximum amount of the mandate that was created using Initiate Payment API)	Mandatory	String
productInfo	Product information You need to pass the same product info which you passed while using the Initiate Payment API	Mandatory	String
firstName	First name of the customer	Mandatory	String
phone	Phone number of the customer	Mandatory	String
email	Email address of the customer	Mandatory	String
successRedirectUrl	URL for redirection, post successful transaction. It will be used in cases where the amount to deduct is more than 15K in case of UPI AutoPay. In such sceanrios, the end customers will again go through a flow, where they need to enter their PIN to authenticate.	Mandatory	String
failureRedirectUrl	URL for redirection, post failure transaction. It will be used in cases where the amount to deduct is more than 15K in case of UPI AutoPay. In such sceanrios, the end customers will again go through a flow, where they need to enter their PIN to authenticate.	Mandatory	String
callbackUrl	URL for callback/notification This callback URL will be used by SIgnzy to post the data for the transaction.	Mandatory	String
maxAmount	Maximum allowed amount for transaction This is the maximum amount of the mandate which was set in the Initiate Payment API. It needs to be the same.	Mandatory	String
subMerchantId	Sub-merchant ID Signzy will share a sub-merchant ID for every client which they need to pass in Production. It will be done post doing an onboarding. For Pre-Production, please use the sub-merchant ID S79159ASPT. You can test out the flow using this.	Mandatory	String
finalCollectionDate	Final collection date for the transaction It should be in YYYY/MM/DD format	Mandatory	String

Sample Response

{
    "result": {
        "txnId": "65eae23e219881001169b35e89",
        "amount": "8.0",
        "productInfo": "Netflix",
        "firstName": "Ramesh",
        "phone": "******************",
        "email": "*******************",
        "customerAuthenticationId": "65eadfa0ee6b35001779550f900",
        "autoDebitAccessKey": "*******************",
        "signzyId": "S2403081V607U9899",
        "merchantDebitId": "***********************",
        "data": {
            "status": 1,
            "data": "Auto debit request accepted successfully"
        }
    }
}

Output Parameters

Key	Type	Description
result.txnId	String	The transaction ID of the payment
result.amount	String	The payment amount
result.productInfo	String	Information about the product for which the payment is made
result.firstName	String	The first name of the payer
result.phone	String	The phone number of the payer
result.email	String	The email address of the payer
result.customerAuthenticationId	String	The unique ID for customer authentication
result.autoDebitAccessKey	String	The unique access key for auto debit
result.signzyId	String	The unique Signzy ID
result.merchantDebitId	String	The unique merchant debit ID
result.data.status	Integer	The status of the debit request It will be 1 in case of successful acceptance of the auto debit request
result.data.data	String	Information about successful acceptance of auto debit. Post that, it will be sent to bank for processing.

Sample Errors

{
    "error": {
        "name": "error",
        "message": "Something went wrong. Please contact [email protected] if issue persists. Transaction ID: 65eae205219881001169b35d",
        "status": "400",
        "reason": "ERROR",
        "type": "Bad Request",
        "statusCode": 200
    }
}

Error Parameters

Key	Description	Type
error	Main error object	Object
error.name	Error name	String
error.message	Error message	String
error.status	Error status code	String
error.reason	Error reason	String
error.type	Type of error	String
error.statusCode	HTTP status code	String

Error Codes

Error Code	Error Message	Explanation
400	Bad Request	Input parameter has a missing required parameter or invalid inputs
401	Authorization Failed	Authorization token is invalid
500	Internal Server Error	Internal error at Signzy, Please reach out to [email protected]