Async API

The following guide describes an async implementation of our bank account verification APIs. This lets you initiate a verification request and let it complete asynchronously—without having to wait for an immediate response. Essentially, you will need the following 2 APIs—

• Verify bank account—This lets you initiate a verification request.
• Get verification request details—This lets you check the status associated with the verification request.

Here are the URLs you would need for this integration—

• Sandbox—https://dg-sandbox.setu.co
• Production—https://dg.setu.co
• Headers—Contact Setu for providing the credentials required to successfully call Setu APIs. This contains:
  • x-client-id
  • x-client-secret
  • x-product-instance-id

Verify bank account

Call this API to initiate bank account verification of your customer. A quick explanation of the request params—

• ifsc is the IFSC (Indian Financial System Code) of the bank branch, where the bank account is held.
• accountNumber is the bank account number that has to be verified.
• narration is the reason for carrying out bank account verification

Set the accountNumber value as 1234567890 always. Use the ifsc values as mentioned below, to mimic respective scenarios—

• ABCD0123456—successful verification response.
• ABCD0123457—invalid transaction response. This may happen if the provided account does not support IMPS transactions.
• ABCD0123458—transaction limit may have been reached. This may happen if, at the time of the penny drop, the transaction breaches the the daily IMPS limit for the account. While this is rare, it is still a possibility.
• ABCD0123459—downstream service error.
• ABCD0123450—pending verification.
• ABCD0123467—invalid account details.

200

SUCCESS Your request contains a valid bank account number and the verification request has been successfully initiated.

Request

POST  /api/verify/ban/async 
 
{ 
  "ifsc": "ABCD0123456",  
  "accountNumber": "1234567890", 
  "narration": "test transaction for verification" 
} 

Response

You get an id associated with the verification request, which you can use to check verification status asynchronously.

{ 
  "id": "02c2dc4c-1015-4ea0-8ec4-987829fc70cc" 
} 

Get verification request details

Call this API to know verification status of request that was previously initiated, against the id associated with it.

200

SUCCESS Verification was successful and the account is active.

Request

POST  /api/verify/ban/async/:requestId 
 

Response

You get the name of the account holder in the response.

{
  "id": "d9342684-1300-4fa8-8344-cc861a20a488",
  "code": "BAV00",
  "verification": "success", 
  "message": "Account exists and is active.", 
  "data": { 
    "name": "name of the account holder", 
    "transactionReference": "120716373986",
    "verifiedAt": "2017-08-28T09:36:18+00:00"
  } 
  "traceId": "...",
} 

200

INVALID TRANSACTION Setu successfully attempted penny drop, but the provided accountNumber may not support IMPS transactions.

Request

POST  /api/verify/ban/async/:requestId 

Response

{ 
    "id": "d9342684-1300-4fa8-8344-cc861a20a488",
    "code": "BAVM1", 
    "message": "This transaction is not valid for this account.", 
    "verification": "failed",
    "traceId": "...",
} 

200

TRANSACTION LIMIT EXCEEDED Setu successfully attempted penny drop, but the daily IMPS transaction limit for the provided account was breached at the time of penny drop. While this is rare, it is still a possibility.

Request

POST  /api/verify/ban/async/:requestId 

Response

{
    "code": "BAVM1",  
    "message": "The transaction limit for this account may have been reached.", 
    "verification": "failed",
    "traceId": "...",
}  

200

PENDING The request still needs to be processed by our banking partner. Please check again in some time.

Request

POST  /api/verify/ban/async/:requestId 

Response

{ 
  "id": "d9342684-1300-4fa8-8344-cc861a20a488",
  "verification": "pending",
  "traceId": "...",
} 

200

INVALID ACCOUNT Setu has processed your request, but the accountNumber or ifsc is invalid.

Request

POST  /api/verify/ban/async/:requestId 

Response

{
  "id": "d9342684-1300-4fa8-8344-cc861a20a488",
  "code": "BAVM1",  
  "verification": "failed", 
  "message": "This account does not exist or is invalid." 
  "traceId": "...",
} 

500

PARTNER SERVER ERROR Setu attempted penny drop, but received a server error.

Request

POST  /api/verify/ban/async/:requestId 

Response

{
    "id": "....",
    "error": {
      "code": "upstream_service_error", 
      "detail": "Upstream service error. Please reach out to support along with the traceId.", 
      "traceId": "..." 
    }
}