Common APIs References

  • This document details various data structures used for user information, financial transactions, and communication between systems, including objects for addresses, challenges, dates, money, and persons.

  • The RequestHeader and ResponseHeader objects define the structure for metadata exchanged between systems, ensuring proper context and versioning for each API call with unique request IDs and timestamps.

  • Several objects specify temporal data, such as DateSpec, TimestampSpec, TenureSpec, and TenureRangeSpec, for representing specific dates, time ranges, and contractual terms, with the usage of specific units like the period type and epoch millis.

  • UserIdentifier and UserPhoneNumber objects are defined for the unique identification of a user, using a structure that includes a country code and a national number.

  • Enumerations like Gender, CalendarPeriod, and TermsAndConditionType provide standardized values for user gender, time period categorization, and types of terms and conditions.

Common Objects and Enums

Address

Address of the user.

Field Type Cardinality Description
addressTags string One to many
companyName string Zero or one
addressLine1 string Only one
addressLine2 string Only one
addressLine3 string Only one
landmark string Only one
postalCode string Only one
city string Only one
state string Only one
country string Only one
residenceType string Zero or one Residence type of the customer's current address. For eg, RENTED, OWNED etc.

Challenge

Challenge object encapsulating authentication information to be send back to financial institution.

Field Type Cardinality Description
tokens ChallengeToken One to many List of challenge tokens.
tokenReferenceId string Only one Reference id that uniquely identifies a challenge request.

ChallengeToken

Field Type Cardinality Description
type string Only one SMS_OTP
value string Only one Challenge Token associated with given context, which needs to be validated.

DateSpec

Field Type Cardinality Description
year int64 Only one
month int64 Only one
day int64 Only one

MoneySpec

Field Type Cardinality Description
currencyCode string Only one Currency of money. Use the value "INR".
amountMicros int64 Only one An amount in micros.

Person

Field Type Cardinality Description
firstName string Only one
lastName string Only one
salutation string Only one Acceptable values: “MR”, “MRS”, “MS”, “DR”
middleName string Zero or one
fullName string Zero or one

RequestHeader

Request metadata passed to bank in post param at each API invocation.

Standard request header

{
  "requestHeader" : {
    "requestId": "ANB6732",
    "requestTimestamp": {
      "epochMillis": 1233453453000
    },
    "protocolVersion": {
      "major": 1
    },
    "paymentIntegratorAccountId": "SAMPLEID123"
  },
  "data": {...}
}
Field Type Cardinality Description
requestId string Only one Request Id sent to bank to maintain idempotency and uniquely identify request.
paymentIntegratorAccountId string Only one Unique identifier specifying Vendor
protocolVersion RequestHeader.ProtocolVersion Only one Protocol Version used while communicating with bank
requestTimestamp TimestampSpec Only one Timestamp when the request was created at google server side.

RequestHeader.ProtocolVersion

Field Type Cardinality Description
major int32 Only one Major version. This is marked for compatibility. Requests with different versions are not guaranteed to be compatible.

ResponseHeader

Response meta generated by bank and passed as response to vendor gateway.

Standard response header

{
  "responseHeader" : {
    "responseTimestamp": {
      "epochMillis": 1233453453000
    }
  },
  "data": {...}
}
Field Type Cardinality Description
responseTimestamp TimestampSpec Only one Timestamp set by bank for the response.

TenureRangeSpec

Field Type Cardinality Description
minimum TenureSpec Only one
maximum TenureSpec Only one
variationStep TenureSpec Only one

TenureSpec

Field Type Cardinality Description
periodType string Only one Which periods correspond to length.
length int64 Only one How many periods in this tenure.

TimestampSpec

Timestamp in epoch millis.

All timestamps are represented as milliseconds since the Unix epoch (Jan 1, 1970) in UTC.

For example:

  • April 23, 2019 8:23:25 PM GMT = 1556051005000 milliseconds
  • August 16, 2018 12:28:35 PM GMT = 1534422515000 milliseconds
Field Type Cardinality Description
epochMillis int64 Only one Milliseconds since the unix epoch.

UserIdentifier

UserIdentifier that uniquely identifies the user.

Field Type Cardinality Description
phoneNumber UserPhoneNumber Only one Phone number to identify the user.

UserPhoneNumber

Phone number of the user.

Field Type Cardinality Description
countryCode string Only one Country code. Example: 91 for India.
nationalNumber string Only one National number. Example: 10 digit mobile number for India.

Gender

Enum to represent genders in credit platform.

Name Description
MALE
FEMALE
OTHERS

CalendarPeriod

A CalendarPeriod represents the abstract concept of a time period that has a canonical start. Grammatically, "the start of the current CalendarPeriod." All calendar times begin at midnight UTC.

Name Description
CALENDAR_PERIOD_UNSPECIFIED Undefined period, raises an error.
DAY A day.
WEEK A week. Weeks begin on Monday, following [ISO 8601](https://en.wikipedia.org/wiki/ISO_week_date).
FORTNIGHT A fortnight. The first calendar fortnight of the year begins at the start of week 1 according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_week_date).
MONTH A month.
QUARTER A quarter. Quarters start on dates 1-Jan, 1-Apr, 1-Jul, and 1-Oct of each year.
HALF A half-year. Half-years start on dates 1-Jan and 1-Jul.
YEAR A year.

TermsAndConditionType

Type associated with Terms and condition supplied during application submission or product registration. Next ID: 9

Name Description
MITC
AUTO_CREDIT_LIMIT_INCREASE
AUTHORIZATION_STATEMENT
CREDIT_MEMBER_AGREEMENT
USER_DATA_SHARING_CONSENT
CKYC_DATA_FETCH
CREDIT_REPORT_FETCH
PERSONALISATION_BASED_ON_CREDIT_REPORT