Loan Issuance APIs
Stay organized with collections
Save and categorize content based on your preferences.
Page Summary
This document outlines the API functions for a financial services platform, including initiating challenges, managing credit applications, handling KYC processes, and setting up repayments.
The platform utilizes asynchronous operations for KYC, repayment setup, and application submission, with GetApplicationStatus used to check the status of these processes.
User data, including UserIdentifier, and application progress is managed through unique IDs like googleApplicationId, tokenReferenceId, and partnerApplicationReferenceId.
The platform supports various KYC methods (eKYC, videoKYC, cKYC, offlineKYC), document verification, and offer retrieval, with defined states and error reasons for each process.
Customer authentication and security are handled through challenge mechanisms like SMS_OTP, and authorization tokens are provided via the GetAuthToken API.
InitiateChallenge
This api initiates customer challenge from FI for specified context
using the specified challenge mechanism.
Currently we are defining only OTP as the challenge mechanism,
but can be extended to any new medium.
Context sent by Google to bank. Authentication token is validated against
this context reason and UserIdentifier. This will provide additional
information for initiating the challenge that can be used by
the partner to take action specific to the user journey step.
Response from bank for generated challenge token call.
{
"responseHeader": { ... },
"data": {
"tokenReferenceId": "unique_reference_id",
"tokenMetadata": {
// oneof depending on the challenge mechanism.
"smsOtpMetadata": {
"format": {
"length": 6,
"messageRegex": "(\\d{6}) is OTP for your Credit application
through Google Pay app. OTPs are SECRET.
DO NOT disclose it to anyone.
Bank NEVER asks for OTP.",
}
}
}
}
}
A unique reference ID for this challenge initiation.
This will be passed back while verifying the token,
which can be used by the partner for correlation.
Send over all necessary information to trigger the risk assessment
process for an applicant.
The operation is asynchronous. The status of the approval process
can be periodically requested by Google using the
GetApprovalStatus() call.
Endpoint
POST v1/financialservices/credit/offer/approveUser
ApproveUserForCreditRequest
Request to bank to start approval process.
{"requestHeader":{...},"data":{"googleApplicationId":"AB2134","cKycId":"aabd123214214",// this field is present if// a CkycSearch call was made"productId":"AB2134","challenge":{"tokenReferenceId":"unique_reference_id","tokens":[{"type":"SMS_OTP","value":"12345"}// more repetitions if provided]},"userIdentifier":{"phoneNumber":{"countryCode":"91","nationalNumber":"9876543210"}},"loanDetails":{// mandatory"amount":{"currencyCode":"INR","amountMicros":10000},"loanPurpose":"ONE_OF_LOAN_PURPOSE_STRINGS"// mandatory},"user":{"fullName":"Bruce Wayne",// mandatory"emailAddress":"bruce@gmail.com",// mandatory"type":"NEW_TO_BANK","deviceLocation":{// optional"latitude":123.213,"longitude":-75.436,"accuracy":10}"addresses":[{// mandatory"addressLine1":"101, building name","addressLine2":"west of main road","addressLine3":"west of main road","landmark":"near famous watertower","postalCode":"123456","city":"somecity","state":"somestate","country":"somecountry","addressTags":["RESIDENTIAL_ADDRESS","COMMUNICATION_ADDRESS"],"geoLocation":{// the geoLocation object is optional"latitude":123.213,"longitude":-75.436}},{// mandatory"companyName":"ABC","addressLine1":"101, building name","addressLine2":"west of main road","addressLine3":"west of main road","landmark":"near famous watertower","postalCode":"123456","city":"somecity","state":"somestate","country":"somecountry","addressTags":["OFFICE_ADDRESS"],"geoLocation":{// the geoLocation object is optional"latitude":13.213,"longitude":47.436}},{// optional, only if “residenceOwnership” is “RENTED”"companyName":"ABC","addressLine1":"101, building name","addressLine2":"west of main road","addressLine3":"west of main road","landmark":"near famous watertower","postalCode":"123456","city":"somecity","state":"somestate","country":"somecountry","addressTags":["PERMANENT_ADDRESS"],"geoLocation":{// the geoLocation object is optional"latitude":12.213,"longitude":77.436}}],"pan":"PAQ123453",// mandatory“dateOfBirth”:“1970-07-22”,// mandatory“employmentInfo”:{"employerName":"Toyota",// mandatory"employerAddress":{// mandatory"addressTags":["OFFICE_ADDRESS","COMMUNICATION_ADDRESS"],"companyName":"Aaa","addressLine1":"101, building name","addressLine2":"west of main road","addressLine3":"west of main road","landmark":"near famous watertower","postalCode":"123456","city":"somecity","state":"somestate","country":"somecountry","geoLocation":{// the geoLocation object is optional"latitude":123,"longitude":-47.436}},"workExperience":{"totalWorkExperienceYears":"4",// mandatory},"income":{// mandatory"periodType":"MONTH",“value”:{"currencyCode":"INR","amountMicros":35000000000,}},"employmentType”: { “salaried”: {} } }, "residenceInfo": { // mandatory "timeAtCurrentResidence": "20", "residenceOwnership": "RENTED" // or "OWNED" }, "father": { "firstName": "Thomas", "lastName": "Wayne", "salutation": "MR", // one of MR, DR }, // mandatory } "extension": { "enabledFlags": [ "eligibleForIncomeVerification", ] } }}
#ifUserisapproved,VendorgeneratesanapprovedOfferfortheapplicantandenablestheeKYCflow.#IfUserdoesn'tneedeKYC,kycTokenisnotpresent.{"responseHeader":{...},"data":{"applicationState":"APPROVED","partnerApplicationReferenceId":"123456","approvedStateContext":{"offerId":"123242323",}}}#ifuserisnoteligible{"responseHeader":{...},"data":{"applicationState":"REJECTED","partnerApplicationReferenceId":"123456","rejectedStateContext":{"reason":"offer expired","description":"The offer has expired"}}}#ifadecisionispending{"responseHeader":{...},"data":{"applicationState":"IN_PROCESS","partnerApplicationReferenceId":"123456","inProcessStateContext":{}}}#Theapprovalapplicationisinincomeverificationstate.{"responseHeader":{...},"data":{"applicationState":"INCOME_VERIFICATION","partnerApplicationReferenceId":"123456","incomeVerificationContext":{}}}
User objects to uniquely identify users in a bank's system.
If the offerID is used by Partner to query the details,
then the UserIdentifier can be ignored.
FetchOfferResponse
Response from bank for given offerId.
{"responseHeader":{...},"data":{"offer":{"productId":"product-id","offerId":"OFFER01750","creditLimit":{"variationStep":{"amountMicros":5000000000,"currencyCode":"INR"},"maximumAmount":{"amountMicros":30000000000,"currencyCode":"INR"},"minimumAmount":{"amountMicros":10000000000,"currencyCode":"INR"}},"startTime":{"epochMillis":1625810549692},"endTime":{"epochMillis":1625810879692},"termCreditOfferDetails":{"tenureStructure":[{"maximumAmount":{"amountMicros":30000000000,"currencyCode":"INR"},"minimumAmount":{"amountMicros":10000000000,"currencyCode":"INR"},"tenureRange":{"minimum":{"periodType":"MONTH","length":6},"maximum":{"periodType":"MONTH","length":12},// Variation step should be same across all// tenure structures and the// overall maximum tenure length across// tenure structures should be// reachable from the overall minimum using// the given variation step."variationStep":{"periodType":"MONTH","length":6}}}],"interestStructure":{"fixed":{"interestCharge":{"percentageValueE5":2800000}}}}}}}
Google will send Partner an identifier of the user application session.
Partner will return a token that Google will use to build
a personalized URL.
The KYC operation is asynchronous. Google will support
a callback URL called by Partner when the operation completes.
In addition to that, the status of the KYC process can be periodically
requested by Google using the GetApplicationStatus() call.
Endpoint
POST v1/financialservices/credit/user/kyc/initiate
The user will send Partner the required details to pre-fill on the
Partner’s website.
Partner will return a token that Google will use to build
a personalized URL.
The repayment setup operation is asynchronous.
Google will support a callback URL called by Partner when
the operation completes.
In addition to that, the status of the eMandate process can be
periodically requested by Google using the GetApplicationStatus() call.
Endpoint
POST v1/financialservices/credit/application/initiateRepaymentSetup
{"responseHeader":{...},"data":{"partnerApplicationReferenceId":"123456","urlToken":"abc754uifsd","authCode":"60e7e69fe57bf","expirationTime":{"epochMillis":1603298333942// should be 60 seconds}}}
This is a generic API which will be used to fetch auth token and
other details (like redirection for a process) for multiple processes
(KYC, Repayment, Income Verification) and entities
(Credit approval application, application, account, etc).
The auth token will be used for authenticating the user with the FI.
Google will send the partner an identifier of the entity for the user.
Google will support a callback URL in case the user needs
to be redirected to GPay after a relevant flow completes
on the partner’s end.
Endpoint
POST v1/financialservices/credit/user/getAuthToken
GetAuthTokenRequest
Request to bank to generate and provide a secure auth token for the user.
Indicates the type of context for which the auth token is being
requested. For example, token for income verification, KYC or other
required types in the future.
Timestamp post which the auth token will not be valid.
redirectionUrl
string
Zero or one
SubmitApplication
This call will trigger the actual disbursement of credit.
Google will use this call after the user accepts the final e-agreement.
The operation is asynchronous. The status of the disbursement
can be periodically requested by Google using
the GetApplicationStatus() call.
Endpoint
POST v1/financialservices/credit/application/submit
SubmitApplicationRequest
Request to bank to submit application.
{"requestHeader":{...},"data":{"googleApplicationId":"AB2134","offerId":"loans-test-123","productId":"PERSONAL_LOAN_AUTOPUSH_1","userIdentifier":{"phoneNumber":{"countryCode":"91","nationalNumber":"7358346320"}},"challenge":{"tokenReferenceId":"unique_reference_id","tokens":[{"type":"SMS_OTP","value":"12345"}// more repetitions if provided]},"tncAcceptanceMetadata":[{"version":"version reference id","type":"MITC","acceptance":true},{"version":"version reference id","type":"USER_DATA_SHARING_CONSENT","acceptance":true}],"user":{"type":"EXISTING_TO_BANK","emailAddress":"user@email.com"}"loanApplicationDetails":{"calculatedEmiAmount":{"amountMicros":1200000,"currencyCode":"INR"},"calculatedInterestAmount":{"amountMicros":12000000,"currencyCode":"INR"},"calculatedApplicationFees":[{"feeType":"PROCESSING_FEE","value":{"amountMicros":1200000,"currencyCode":"INR"},"tax":[{"taxType":"GST","amount":{"amountMicros":100000,"currencyCode":"INR"}},{"taxType":"SERVICE_TAX","amount":{"amountMicros":100000,"currencyCode":"INR"}},]},...]}}}
Fetches application status of a given application.
If the application is approved and processed,
response would contain the accountId of the activated product.
For any rejections, partners will provide a reason for the same.
Endpoint
POST v1/financialservices/credit/application/getStatus
Unique ID generated on the partner side for the specific application
to be passed back for correlation.
FetchAccount
Get loan account details after disbursal is approved,
associated with an AccountToken.
The account details are used to refresh the EMI schedule and
how much of the loan has been repaid or is still outstanding.
Endpoint
POST v1/financialservices/credit/account/get
FetchAccountRequest
Request to bank to fetch account for a given user.
CkycSearch API will search for the CKYC record of the user and
return true if ckyc exists for the user.
If the Ckyc record exists, cKycId will be used to fetch the cKYC data
for the user in the CkycDownload API.
Endpoint
POST v1/financialservices/credit/customer/searchCKycRecord
SearchCKycRecordRequest
Request to credit partner to search ckyc record by calling CERSAI's
CKycSearch API.
To indicate whether the user has consented to fetch cKYC data.
For this request, the type field value should have the value
"CKYC_DATA_FETCH", and the acceptance field value should be "true".
See the sample payload.
SearchCKycRecordResponse
Response from credit partner for the SearchCKycRecord API
Unique Id to fetch user KYC data in the download API.
DownloadCKycRecordResponse
Response from the credit partner for the DownloadCKycRecord API.
Success response:
HTTP/1.1200OKContent-Type:application/json{"responseHeader":{...},"data":{"user":{"gender":"FEMALE",//acceptable values: [FEMALE|MALE|OTHERS]"dateOfBirth":"1992-03-24",//DOB format should be: YYYY-MM-DD"email":"kapooraditya@google.com","name":{"salutation":"MRS",//acceptable values: ["MR", "MRS", "DR", "MS"]"firstName":"NAMRTA","middleName":"NIMESH","lastName":"SHAH","fullName":"MRS NAMRTA NIMESH SHAH"},"father":{"salutation":"",//acceptable values: ["MR", "MRS", "DR", "MS"]"firstName":"HARISH","middleName":"KUMAR","lastName":"SHAH","fullName":"MR HARISH KUMAR SHAH"},"mother":{"salutation":"MRS",//acceptable values: ["MR", "MRS", "DR", "MS"]"firstName":"MOTHER","middleName":"","lastName":"MOM","fullName":"MRS MOTHER MOM"},"addresses":[{"addressLine1":"101, building name","addressLine2":"west of main road","addressLine3":"west of main road","landmark":"near famous watertower","postalCode":"123456","city":"somecity","state":"somestate","country":"somecountry","addressTags":["RESIDENTIAL_ADDRESS","COMMUNICATION_ADDRESS"]// incasebotharethesame,otherwisetwodifferentaddressesinthisarray.}]}}}
Error response - in case CKYC record is not found for the user
HTTP/1.1200OKContent-Type:application/json{"responseHeader":{...},"errorResponse":{"errorDescription":"Ckyc record not found for given user.","paymentIntegratorErrorCode":"IL234","errorResponseResult":{"ckycDataNotFound":{}}}}
ApplicationState specific context information given by during account
creation.
Field
Type
Cardinality
Description
accountToken
string
Only one
Account token sent by bank after successful creation of account.
AccountSpec
Field
Type
Cardinality
Description
accountToken
string
Only one
Unique identifier shared between FI and Google to refer to this account.
This should not be a public identifier that anybody can use
to identify a user's credit account with FI.
Optional. Estimated horizontal accuracy radius in meters of device
location (ref).
ApprovedStateContext
Document submission step is approved by partner.
AwaitingApprovalStateContext
Document has been submitted and pending approval from partner. No further
user action action is required.
DocumentVerification
Document verification process, where user submits documents with the
financial institution. For e.g., In order to check creditworthiness of the
customer before applying for any credit product, financial institution may
ask for income related documents.
An example case would be if user starts a doc upload but failure occurs due
to some temporary technical failure, partner is expected to specify the
reason associated with the temporary failure so that it can retried by user.
Timestamp until user is allowed to upload documents on google pay
surface. The user might have to physically submit the documents for
processing post this time.
Timestamp until approval is valid for the kyc step.
AwaitingApprovalStateContext
Kyc step pending approval from partner. No further user action action is
required.
Ckyc
CKYC refers to Central KYC (Know Your Customer), an initiative of the
Government of India. The aim of this initiative is to have a structure in
place which allows customers to complete their KYC only once before
interacting with various entities across the financial sector. CKYC is
managed by CERSAI (Central Registry of Securitization Asset Reconstruction
and Security Interest of India), which is authorized by the Government of
India to function as the Central KYC Registry (CKYCR)
Ekyc (electronic - know your customer) is a paperless Know Your Customer
(KYC) process, wherein the identity and address of the user are verified
electronically through government id verification. In India, Aadhaar, which
is a government id, is used for digital authentication.
An example case would be if user has already started the Ekyc flow and Aadhar
system is down (which is a dependent system at partners end), partner is
expected to specify the reason associated with the temporary failure so that
it can be retried by user.
Specify the reason associated with inprogress state for a given kyc step.
Kyc
For e.g. In case of AXIS card onboarding flow in order to complete the KYC
journey user could be eligible for any of the following combinations.
1) ekyc + videoKyc.
2) offline
3) ekyc + videoKyc + offline.
Option for user to complete KYC via Central KYC Registry where users KYC
details are verified from the centralised depository of KYC documents
managed by CERSAI which is authorized by the Government of
India.
Physical copy of identity verification documents shared by user has
been rejected by partner. Partner will provide reason code associated
with given rejection type.
RejectedStateContext
Kyc step is in a rejected state. The step cannot be retried in case if a kyc
step gets rejected by the partner.
Possible kyc and document verification options for the user in the kyc
flow. This will contain empty messages with optional expiry timestamp
corresponding to the steps that a user is eligible for.
Optional. Qualification criteria pertaining to this offer. Offer will be
enabled only if this qualification criteria is met.
Provenance.Prequalified.QualificationCriteria
Qualification checks that need to be run before enabling the offer. This
will be triggered only for unavailable offers with reason as
PENDING_PREQUALIFIED_CRITERIA_CHECKS.
Field
Type
Cardinality
Description
eligibleTierIds
string
Zero to many
List of tiers that should be used for running the qualification checks.
This list will contain the names referred to by the
FinancialInstitution for the segments.
RejectedStateContext
ApplicationState specific context information given by bank when application
got rejected.
Variable terms are only applicable to this offer.
These terms are either defined by the lender or tentatively defined
by the pre-qualification process.
The amount of loan disbursed by the financial institution. This is equal to
the loan amount approved minus the various fees (like processing fee)
charged to the customer.
interestRateE5
int64
Only one
Interest rate * 10^5. For example, 12.75% would be 1275000.
Unique identifier shared between financial institution and google to
refer this account.
UserDetailsContext
AccountSpec.AccountType
Name
Description
CREDIT_CARD_ACCOUNT
LOAN_ACCOUNT
AccountStateSpec.State
Name
Description
ACTIVE
Active account state.
INACTIVE
Inactive account state.
CLOSED
Account is closed.
DELINQUENT
Account is in delinquency.
ApplicationRejectionReason.Reason
Name
Description
BUREAU_RECORD
Application was rejected based on the Bureau Track Record.
CREDIT_RISK_ASSESSMENT
Customer's credit data did not meet the criteria.
CO_LENDER_REJECT
Application was rejected by the co-lender.
KYC_REJECT
LANGUAGE_BARRIER
Application was rejected due to the language barrier between the partner
and the customer.
BANKING_RELATIONSHIP
Application was rejected based on the past relationship between the
partner and the customer, e.g. previous loans not paid on time, past loan
rejections etc.
UNSERVICEABLE_LOCATION
Lender doesn't provide service at the customer's location.
BORROWER_REJECTED
The application was abandoned by the borrower.
DUPLICATE_APPLICATION
Another application for the same user was submitted, approved or rejected
recently.
USER_UNREACHABLE
Lender was unable to contact the customer to continue application
process. Eg, unable to reach customer for offline KYC.
OTHERS
PENDING_CUSTOMER_ACTION
The application is in rejected state because it needs some input from the
customer. Exact fields which need input can be determined using the field
mask in RejectedStateContext.
INVALID_DATA_WITH_VENDOR
User data is in invalid state on partner's end to proceed with the
application.
Enum specifying the overall state of document verification process. User
could be eligible for both online and offline provisioning of the document
and each of them has its own state context. If one of the methods goes into
terminal state, there are other methods available for users to complete the
document verification process. The value of enum will be derived depending
upon state context of all options that the user is eligible for.
Name
Description
NOT_STARTED
When user is eligible to upload the documents but has not yet
started the document upload journey via any of the options provided by
partner.
IN_PROGRESS
User has started the document uploading process with the partner.
AWAITING_APPROVAL
User has completed the document uploading process and partner is
processing the documents before moving it to a terminal state.
APPROVED
User's documents have been successfully uploaded and verified by
partner.
REJECTED
User is no longer eligible to submit documents from any options provided
due to rejection at partner's end or expiry of the timeframe to complete
those steps.
InProgressStateContext.Reason
Name
Description
USER_ERROR
Error state due to some user initiated action and requires user action to
course correct the document verification step. For eg, user dropping off
during the process, invalid document upload etc.
INTERNAL_DEPENDENCY_FAILURE
Error state due to some system failure at partners end.
RejectedStateContext.Reason
Name
Description
POLICY_ERROR
Rejected due to policy error such as transaction criteria for a given
bank statement doesn't comply with policy at partner's end.
SKIPPED
Rejected on user action of skipping the document verification step at
partner surface.
EXPIRED
Rejected when the current timestamp is greater than expiry timestamp for
a given document verification step.
Error state user has not provided access to camera or location access at
partner surface.
AADHAAR_SERVICE_ERROR
Error state due to Aadhaar service down and partner is unable to validate
the aadhaar details of the user.
VKYC_SERVICE_ERROR
Error due to failure in vkyc service used by the partner.
USER_ERROR
Error state due to some user initiated action that requires user action
to course correct the step. For eg, user dropping off during the process,
invalid otp attempt etc.
INTERNAL_DEPENDENCY_FAILURE
Error state due to some system failure or technical issues at partners
end during video kyc step.
VALIDITY_EXPIRED
Error state where user completed the step in past, but approval got
expired because other steps weren't completed in the required timeframe.
Kyc.KycState
Enum specifying the overall state of user's kyc journey. User could be
eligible for multiple kyc steps as currently we support three different
types of kyc and each individual step has its own state context. If one of
the steps goes into the rejected state, there are other steps available for
users to complete the kyc journey. The value of enum will be derived
depending upon state context of all options that the user is eligible for.
Name
Description
NOT_STARTED
When user is eligible for kyc journey but has not yet started the kyc
process via any of the options provided by partner.
IN_PROGRESS
When user has started the kyc process and it is pending action from user
to complete the process.
AWAITING_APPROVAL
User has completed the kyc process and partner is processing the
documents before moving it to a terminal state.
APPROVED
User's kyc have been verified and approved by partner.
REJECTED
When user is no longer eligible to complete the KYC journey.
EXPIRED
RejectedStateContext.Reason
Name
Description
POLICY_ERROR
Kyc rejected due to some policy error. This rejection is sent in case
partner cannot send a granular error enum such as NAME_MATCH_FAILURE.
LOCATION_CHECK_FAILED
Rejected due to location of user did not meet the criteria at partners
end while performing online kyc.
VKYC_REJECTED
Video kyc step is marked rejected by video call agent or got rejected
during concurrent audit stage at partners end.
EXPIRED
Rejected when the current timestamp is greater than expiry timestamp for
a given kyc step.
SKIPPED
Rejected when user skipped the given kyc step.
USER_ERROR
Rejection due to some user initiated action which cannot be corrected.
For eg, user exhausting the maximum wrong otp attempts.
EKYC_REJECTED
In case ekyc step gets rejected, video kyc step is automatically rejected
for some partners. This reason is to be used to mark the rejection in
video kyc.
NAME_MATCH_FAILURE
Digital KYC would be rejected if there is a mismatch in the applicant's
name in the submitted application and the one on the Aadhar card. The
following error would be sent in the vKYC rejection state context reason.
OfferStateInfo.UnavailableStateContext.Reason
Name
Description
UNKNOWN_REASON
PREMATURE
The offer is complete but will be made available after some time.
PENDING_PREQUALIFIED_CRITERIA_CHECKS
The offer is unavailable as prequalified criteria checks (PQCs) have
not been performed yet.
CreditApprovalApplicationStateInfo.State
Name
Description
APPROVED
User is approved for a credit offer, offer has been provided.
Terminal state.
REJECTED
User was rejected by the lender. Terminal state.
IN_PROCESS
Initial state when for credit approval application.
INCOME_VERIFICATION
User needs to supply more details to verify their income before their
application can be approved.
CustomerChallengeContext.Reason
Name
Description
OFFER_ACTIVATION
Customer is challenged during offer activation
USER_DETAILS
Customer is challenged during getting user details
CARD_DETAILS
Customer is challenged during getting card details
USER_APPROVAL
Customer is challenged during credit approval application
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-16 UTC."],[],[]]
