—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 6 minutes

Edit this page ↗

#Penny drop + PennyLess API Integration

The following guide describes an Penny drop + PennyLess 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 and it generates webhook when bank account verification is completed.

You will need the following 2 APIs—

  • Create Penny drop + PennyLess—This lets you initiate a verification request.
  • GET Penny drop + PennyLess 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

#Create Penny drop + PennyLess

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

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

Sample account number and ifsc for Sandbox.

  • accountNumber:1234567890, ifsc:UTIB0002083 - Successful Verification Type 1 (PennyLess Drop)
  • accountNumber:1234567891, ifsc:UTIB0002083 - Successful Verification Type 2 (PennyLess Drop)
  • accountNumber:1234567895, ifsc:UTIB0002083 - Successful Verification Type 3 (Penny Drop)


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

Request
POST  /api/verify/setu-bav/async
 
{ 
  "ifsc": "UTIB0002083",  
  "accountNumber": "1234567890", 
}
Response

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

{
    "id": "3afb7ca0-535a-4d5a-9892-960c03c4e966",
    "status": "CREATED",
    "traceId": "e99b6f9a-41bc-4063-adcf-cd27043785d4"
}

#GET Penny drop + PennyLess details

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

Response Type 1

In processing
Request
GET /api/verify/setu-bav/:requestId
Response
{
    "id": "3afb7ca0-535a-4d5a-9892-960c03c4e966",
    "status": "IN_PROGRESS",
    "traceId": "e99b6f9a-41bc-4063-adcf-cd27043785d4"
}

Response Type 2

Verification done through PennyLess Drop
Request
GET /api/verify/setu-bav/:requestId
Response
{
    "id": "50c4b0a4-7de2-4eb3-9d78-153fb4d9991d",
    "status": "SUCCESS",
    "fulfillmentType": "PENNYLESS",
    "data": {
        "bankAccountNumber": "1234567890",
        "bankAccountIfsc": "UTIB0002083",
        "bankAccountName": "PAVANKUMAR KAMAT BIZ",
        "ifscCrossCheck": true,
        "ifscDetails": { // if ifscCrossCheck is true
            "name": "Axis Bank",
            "branch": "KAPODRA, SURAT",
            "center": "SURAT",
            "district": "SURAT",
            "state": "GUJARAT",
            "address": "J R SQUARE, MAMTA PARK - 1 KAPODRA, VARACHHA MAIN ROAD,  SURAT - 395 006",
            "contact": "+919824188896",
            "imps": "true",
            "rtgs": "true",
            "city": "SURAT",
            "iso3166": "IN-GJ",
            "neft": "true",
            "micr": "395211016",
            "upi": "true",
            "swift": ""
        },
        "entityType": "MERCHANT", // or 'INDIVIDUAL'
        "merchantDetails": { // if entityType is MERCHANT
            "mccCode": "1520",
            "identifier": {
                "merchantType": "SMALL",
                "merchantGenre": "OFFLINE",
                "onBoardingType": "BANK"
            },
            "name": {
                "brand": "praimports",
                "legal": "Indian",
                "franchise": "rajababuimpor"
            },
            "ownership": {
                "type": "PRIVATE"
            }
        }
    },
    "traceId": "1ab2fbc8-5b10-4358-8a87-a46592b89a6b"
}

Response Type 3

Verification done through PennyDrop
Request
GET /api/verify/setu-bav/:requestId
Response
{
    "id": "3afb7ca0-535a-4d5a-9892-960c03c4e966",
    "status": "SUCCESS",
    "fulfillmentType": "PENNYDROP",
    "data": {
        // No "entityType" and "merchantDetails" in case of PennyDrop
        "bankAccountNumber": "1234567890",
        "bankAccountIfsc": "ABCD0123456",
        "bankAccountName": "Test User Name",
        "ifscCrossCheck": true,
        "ifscDetails": {
            "name": "State Bank of India",
            "branch": "CANTONMENT, BARODA",
            "center": "BARODA",
            "district": "BARODA",
            "state": "GUJARAT",
            "address": "BARODA MUNICIPAL CORPN. SHOPPING COMPLEX,NEAR FATEHGUNJ PETROL PUMP ,FATEHGUNJ BARODA ,PIN - 390002",
            "contact": "+912652795129",
            "imps": "true",
            "rtgs": "true",
            "city": "VADODARA",
            "iso3166": "IN-GJ",
            "neft": "true",
            "micr": "390002022",
            "upi": "true",
            "swift": ""
        }
    },
    "traceId": "cf7d0e36-1eb8-46b1-ac66-e0576d4d18f1"
}

#Get notified via webhook

As soon as Penny drop + PennyLess compelete (success or failed). Setu triggers a near realtime notification via webhook mechanism. See Notifications page for more information

Was this page helpful?