openapi: 3.2.0 info: title: Open Finance Payment Enablement Bundle API description: 'OpenAPI specification for Finicity APIs. Open Finance (formerly Open Banking) solutions in the US are provided by Finicity, a Mastercard company.' contact: name: API Support email: apisupport@mastercard.com url: https://developer.mastercard.com/open-finance-us/documentation/support/ version: 1.43.0 servers: - url: https://api.finicity.com description: Production security: - FinicityAppKey: [] FinicityAppToken: [] tags: - name: Payment Enablement Bundle description: Any or all of the Payments endpoints in one API call paths: /aggregation/v1/paysuite/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts: get: tags: - Payment Enablement Bundle description: 'This bundled API returns any or all of the Payments endpoints in one API call using institution login ID. This includes, Account Simple details, ACH details, Account Owner, and Account Balance. This requires initial setup to determine which endpoints are included in the API response. For Account Balance, You can define an additional query parameter `balance_cache_interval` to specify the time interval of the last cached balance. This parameter is used by the server to determine whether the cached balance is still valid or if it needs to be refreshed. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' summary: Fetch all the requested field details using institution login ID operationId: GetAccountDetailsByInstitutionLoginId parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/InstitutionLoginIdParameterPEB' - $ref: '#/components/parameters/IncludeParameter' - $ref: '#/components/parameters/PebAllowedBalanceCacheIntervalParameter' responses: '200': $ref: '#/components/responses/GetPaymentEnablementBundleResponse' '400': $ref: '#/components/responses/GetPaymentEnablementBundleBadRequestErrorResponse' '401': $ref: '#/components/responses/AuthenticationUnauthorizedErrorResponse' '404': $ref: '#/components/responses/GetPaymentEnablementBundleResourceNotFoundForInstitutionLoginIdErrorResponse' /aggregation/v1/paysuite/customers/{customerId}/accounts/{accountId}: get: tags: - Payment Enablement Bundle description: 'This bundled API will return any or all of the Payments endpoints in one API call using account ID. This includes, Account Simple details, ACH details, Account Owner, and Account Balance. This requires initial setup to determine which endpoints are included in the API response. For Account Balance, You can define an additional query parameter `balance_cache_interval` to specify the time interval of the last cached balance. This parameter will be used by the server to determine whether the cached balance is still valid or if it needs to be refreshed. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' summary: Fetch all the requested details using the account ID operationId: GetAccountDetailsByAccountId parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/AccountIdParameter' - $ref: '#/components/parameters/IncludeParameter' - $ref: '#/components/parameters/PebAllowedBalanceCacheIntervalParameter' responses: '200': $ref: '#/components/responses/GetPaymentEnablementBundleResponse' '400': $ref: '#/components/responses/GetPaymentEnablementBundleBadRequestErrorResponse' '401': $ref: '#/components/responses/AuthenticationUnauthorizedErrorResponse' '404': $ref: '#/components/responses/GetPaymentEnablementBundleResourceNotFoundForAccountIdErrorResponse' components: examples: MissingFinicityAppKeyExample: value: code: '10026' message: Missing parameter (Finicity-App-Key) NoAccountForCustomerIdExample: value: code: 38003 message: Customer does not have any accounts NotAuthorizedExample: value: code: '10021' message: You are not authorized. PaymentEnablementBundleResponseExample: value: customerId: '5000902316' errorCount: 0 accountCount: 1 accountIdentitySuccessCount: 1 balanceDetailsSuccessCount: 1 paymentInstructionSuccessCount: 1 accounts: - id: '5011648377' institutionId: '4222' institutionName: FinBank institutionLoginId: 1007302745 accountDetails: id: '5011648377' accountNumberDisplay: '8888' realAccountNumberLast4: '5678' name: Super Checking type: checking aggregationStatusCode: 0 status: active aggregationSuccessDate: '2023-06-26T11:14:11Z' aggregationAttemptDate: '2023-06-26T11:14:11Z' createdDate: '2023-06-26T11:14:11Z' currency: USD displayPosition: 1 authorizationStartDate: '2023-06-26T11:14:11Z' authorizationEndDate: '2023-07-26T11:14:11Z' authorizationExpires: true parentAccount: '5011648377' balanceDetails: id: 5011648377 realAccountNumberLast4: '5678' availableBalance: 123.45 availableBalanceDate: '2023-06-26T11:14:11Z' clearedBalance: 222.25 clearedBalanceDate: '2023-06-26T11:14:11Z' aggregationStatusCode: 0 currency: USD accountIdentity: holders: - relationship: AUTHORIZED_USER ownerName: John Smith, PhD firstName: John middleName: L lastName: Smith suffix: PhD nameClassification: home nameClassificationConfidenceScore: 100 asOfDate: 1607450357 addresses: - ownerAddress: 434 W Ascension Way type: Home line1: 434 W Ascension Way line2: 'Suite #200' line3: UT 84123 city: Murray country: USA postalCode: '84123' state: UT emails: - isPrimary: true email: john@example.com emailType: Personal phones: - type: HOME country: '61' phone: 1-555-184-4200 documentations: - taxId: 123-45-7890 taxIdCountry: USA governmentId: '123456789' paymentInstruction: type: ach accountNumber: '124344454' tanEnabled: true descriptors: - type: routingNumber value: '2434345' NoAccountForInstitutionLoginIdExamplePEB: value: code: '38007' message: Customer does not have any accounts associated with institutionLoginId. CustomerNotFoundExample: value: code: '14001' message: Customer not found. GenericBadRequestExample: value: code: '14020' message: Bad request. InvalidCredentialsExample: value: code: '10001' message: Invalid credentials InvalidFieldParameterExample: value: code: 12019 message: fields parameter value must be 'balanceDetails','paymentInstruction' and 'accountIdentity' PaymentEnablementBundleWithErrorResponseExample: value: customerId: '5000902316' errorCount: 2 accountCount: 1 accountIdentitySuccessCount: 0 balanceDetailsSuccessCount: 0 paymentInstructionSuccessCount: 1 accounts: - id: '5011648377' institutionId: '4222' institutionName: TestBank institutionLoginId: 1007302745 accountDetails: id: '5011648377' accountNumberDisplay: '8888' realAccountNumberLast4: '5678' name: Super Checking type: checking aggregationStatusCode: 0 status: active aggregationSuccessDate: '2023-06-26T11:14:11Z' aggregationAttemptDate: '2023-06-26T11:14:11Z' createdDate: '2023-06-26T11:14:11' currency: USD displayPosition: 1 authorizationStartDate: 1607450357 authorizationEndDate: 1607459357 authorizationExpires: true parentAccount: '5011648377' paymentInstruction: type: ach accountNumber: '124344454' tanEnabled: true descriptors: - type: routingNumber value: '2434345' errors: - fieldName: balanceDetails code: '102' description: FI Down for maintenance - fieldName: accountIdentity code: '102' description: FI Down for maintenance schemas: PaymentInstructionPEB: required: - accountNumber - type type: object properties: type: type: string description: Payment instruction type example: ach accountNumber: type: string description: The account number from the institution example: '124344454' tanEnabled: type: boolean description: This field indicates whether the FI uses a tokenized account number for origination purposes. example: true descriptors: type: array description: List of descriptors items: $ref: '#/components/schemas/Descriptor' IdentityRiskScore: type: number description: Comprehensive identity risk score with a higher score indicating a riskier account sign-up. example: 275 AuthorizationExpires: type: boolean description: A Boolean flag that indicates whether the customer’s authorization period has a defined authorization end date. example: true default: false PhoneCountryCode: type: string description: The ISO-3166 alpha-2 country code associated with the phone number. example: UK ZipCode: type: string description: A ZIP code example: '84123' AccountOwnerDocumentation: description: Account owner documentation type: object properties: taxId: $ref: '#/components/schemas/TaxId' taxIdCountry: $ref: '#/components/schemas/Country' governmentId: $ref: '#/components/schemas/GovernmentId' PhoneLineType: type: string description: 'The line type of the phone number. * landline - traditional wired phone line. * fixed-voip - VoIP-based fixed line phones. * mobile - wireless phone line. * voicemail - voicemail-only service. * toll-free - callee pays for call. * premium - caller pays a premium for the call-e.g., 976 area code. * non-fixed-voip - Skype, for example * other - anything that does not match the previous categories.' example: mobile AccountOwnerHolders: required: - holders type: object properties: holders: type: array items: $ref: '#/components/schemas/AccountOwnerDetails' description: List of account owners EmailAddress: type: string description: An email address example: myname@mycompany.com AccountOwnerDocumentations: description: List of account owner documentation. Not currently available in the US region. type: array items: $ref: '#/components/schemas/AccountOwnerDocumentation' EmailDomainCreationDate: type: string description: Returns a date that the email domain was created. example: '2011-06-29T00:00:00.000Z' AccountOwnerPhones: description: List of phones type: array items: $ref: '#/components/schemas/AccountOwnerPhone' AddressLine2: type: string description: Address line 2 example: 'Suite #200' AddressLine3: type: string description: Address line 3 example: UT 84123 IpGeolocationCountryCode: type: string description: The ISO-3166 alpha-2 country code associated with the geolocation of the IP address. example: US AddressLine1: type: string description: Address line 1 example: 434 W Ascension Way AccountOwnerDetails: required: - ownerName - nameClassification - nameClassificationConfidenceScore type: object properties: relationship: $ref: '#/components/schemas/AccountOwnerRelationshipType' ownerName: $ref: '#/components/schemas/AccountOwnerName' firstName: $ref: '#/components/schemas/FirstName' middleName: $ref: '#/components/schemas/MiddleName' lastName: $ref: '#/components/schemas/LastName' suffix: $ref: '#/components/schemas/Suffix' nameClassification: $ref: '#/components/schemas/NameClassificationType' nameClassificationconfidencescore: $ref: '#/components/schemas/ClassificationConfidenceScore' asOfDate: $ref: '#/components/schemas/AsOfDate' addresses: $ref: '#/components/schemas/AccountOwnerAddresses' emails: $ref: '#/components/schemas/AccountOwnerEmails' phones: $ref: '#/components/schemas/AccountOwnerPhones' documentations: $ref: '#/components/schemas/AccountOwnerDocumentations' identityInsights: $ref: '#/components/schemas/AccountOwnerIdentityInsights' description: Owner of a customer account EmailIsDisposable: type: boolean description: True if the email address is from a disposable email service. example: true IdentityRiskReasonCode: type: string description: "Reason code for the identity risk score. Must be exactly two\n uppercase letters." pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 example: AA PhoneCountry: type: string description: Country calling code of the phone number as defined by ITU-T E.123 and E.164 international standards (max length 3)". example: '61' Alerts: type: string description: An alert generated when processing the request. example: Unable to generate IP and user insights MiddleName: type: string description: The middle name of the account holder example: L PhoneNumber: type: string description: A phone number (max length 15). example: 1-801-984-4200 ErrorMessage: required: - code type: object properties: code: type: object description: 'An error code (can be returned as a number or a string). Useful links: [Common API Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/#common-api-status-codes), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes).' example: '10001' status: type: string description: A status code example: '401' title: type: string description: A title for the error example: Connecting accounts error level: type: string description: An error level example: error message: type: string description: An error message example: Invalid authorization credentials user_message: type: string description: Some more details about the error example: The session has expired or is invalid assetId: $ref: '#/components/schemas/AssetId' accountId: $ref: '#/components/schemas/AccountId' externalTransactionId: type: string description: A unique identifier for the transaction that assists in linking data back to your systems. example: MAC1005061234 minLength: 1 maxLength: 100 tags: type: string description: Categories that the error belongs to example: AGG DeviceBrowser: type: string description: The name of the browser used to authorize your product or service. example: Safari AccountId: type: string description: An account ID example: '5011648377' AccountOwnerAddress: description: Account owner address type: object properties: ownerAddress: $ref: '#/components/schemas/Address' type: $ref: '#/components/schemas/AddressType' line1: $ref: '#/components/schemas/AddressLine1' line2: $ref: '#/components/schemas/AddressLine2' line3: $ref: '#/components/schemas/AddressLine3' city: $ref: '#/components/schemas/City' state: $ref: '#/components/schemas/State' postalCode: $ref: '#/components/schemas/ZipCode' country: $ref: '#/components/schemas/Country' AccountIdentitySuccessCount: type: integer format: int32 description: Total number of successful sections returned when requesting accountIdentity. If not provided, value will be 0. example: 1 NameClassificationType: type: string description: 'The classification of the account holder: * "person / personal / home" * "business" * "other"' example: person IpLastSeenDays: type: number description: Count of days since the IP address was last observed in Ekata's Identity Network. If the IP address has not been observed before, IpLastSeenDays will be 0. example: 15 IpPhoneDistance: type: number description: The distance (in miles) between the IP address and the closest physical address associated with the phone number. example: 200 AccountOwnerEmails: description: List of emails type: array items: $ref: '#/components/schemas/AccountOwnerEmail' IpAddressDistance: type: number description: The distance (in miles) between the IP address and the physical address. example: 210 PaymentInstructionSuccessCount: type: integer format: int32 description: Total number of successful sections returned when requesting paymentInstruction. If not provided, value will be 0. example: 1 Descriptor: required: - type - value type: object properties: type: type: string description: Payment Instruction Descriptor Type example: routingNumber value: type: string description: Value that the Descriptor Type Holds example: '2434345' EmailValid: type: boolean description: True if the email address is valid. example: true AggregationStatus: type: string description: "\"pending\" during account discovery, always \"active\" following\n successful account activation" example: active PhoneLastSeenDays: type: number description: Count of days since the phone was last observed in Ekata's Identity Network. If the phone has not been observed before, `phoneLastSeenDays` will be 0. example: 42 PaymentEnablementBundle: required: - errorCount - customerId - accounts type: object properties: customerId: $ref: '#/components/schemas/CustomerId' errorCount: $ref: '#/components/schemas/ErrorCount' accountCount: $ref: '#/components/schemas/AccountCount' accountIdentitySuccessCount: $ref: '#/components/schemas/AccountIdentitySuccessCount' balanceDetailsSuccessCount: $ref: '#/components/schemas/BalanceDetailsSuccessCount' paymentInstructionSuccessCount: $ref: '#/components/schemas/PaymentInstructionSuccessCount' accounts: type: array description: List of Account Details items: $ref: '#/components/schemas/PEBAccountDetails' LastName: type: string description: The last name of the account holder example: Smith AccountSimpleDetails: required: - accountNumberDisplay - createdDate - currency - name - status - type type: object properties: id: $ref: '#/components/schemas/AccountId' accountNumberDisplay: $ref: '#/components/schemas/AccountNumberDisplay' name: $ref: '#/components/schemas/Name' type: $ref: '#/components/schemas/AccountType' aggregationStatusCode: $ref: '#/components/schemas/AggregationStatusCode' status: $ref: '#/components/schemas/AggregationStatus' aggregationSuccessDate: $ref: '#/components/schemas/DateTimeWithZone' aggregationAttemptDate: $ref: '#/components/schemas/DateTimeWithZone' createdDate: $ref: '#/components/schemas/DateTimeWithZone' currency: $ref: '#/components/schemas/Currency' displayPosition: $ref: '#/components/schemas/DisplayPosition' authorizationStartDate: $ref: '#/components/schemas/AuthorizationStartDate' authorizationEndDate: $ref: '#/components/schemas/AuthorizationEndDate' authorizationExpires: $ref: '#/components/schemas/AuthorizationExpires' parentAccount: $ref: '#/components/schemas/AccountId' AvailableBalancePEB: required: - realAccountNumberLast4 - availableBalance - availableBalanceDate - clearedBalance - clearedBalanceDate - aggregationStatusCode - currency type: object properties: id: $ref: '#/components/schemas/NumericAccountId' realAccountNumberLast4: $ref: '#/components/schemas/AccountNumberLast4' availableBalance: type: number description: The available balance of the account format: double example: 123.45 minimum: 0 maximum: 10000000000000000 availableBalanceDate: $ref: '#/components/schemas/DateTimeWithZone' clearedBalance: type: number description: The cleared balance of the account. Also referred as posted balance, current balance, ledger balance example: 222.25 format: double minimum: 0 maximum: 9999999999999 clearedBalanceDate: $ref: '#/components/schemas/DateTimeWithZone' aggregationStatusCode: $ref: '#/components/schemas/AggregationStatusCode' currency: $ref: '#/components/schemas/Currency' AccountType: type: string description: 'The list of supported account types. * "checking": Standard checking * "savings": Standard savings * "cd": Certificates of deposit * "moneyMarket": Money Market * "creditCard": Standard credit cards * "lineOfCredit": Home equity, line of credit * "investment": Generic investment (no details) * "investmentTaxDeferred": Generic tax-advantaged investment (no details) * "employeeStockPurchasePlan": ESPP, Employee Stock Ownership Plans (ESOP), Stock Purchase Plans * "ira": Individual Retirement Account (not Rollover or Roth) * "401k": 401K Plan * "roth": Roth IRA, Roth 401K * "403b": 403B Plan * "529plan": 529 Plan (True value is 529) * "rollover": Rollover IRA * "ugma": Uniform Gifts to Minors Act * "utma": Uniform Transfers to Minors Act * "keogh": Keogh Plan * "457plan": 457 Plan (True value is 457) * "401a": 401A Plan * "brokerageAccount": Brokerage Account * "educationSavings": Education Savings Account that is not a 529 * "healthSavingsAccount": HSA (Health Savings Accounts) * "pension": Pension * "profitSharingPlan": Profit Sharing Plan * "roth401k": Roth 401K * "sepIRA": Simplified Employee Pension IRA * "simpleIRA": Simple IRA * "thriftSavingsPlan": Thrift Savings Plan * "variableAnnuity": Variable Annuity * "cryptocurrency": Cryptocurrency Wallet, Cryptocurrency Account * "mortgage": Standard Mortgages * "loan": Auto loans, equity loans, other loans * "studentLoan": Student Loan * "studentLoanGroup": Student Loan Group * "studentLoanAccount": Student Loan Account' example: checking EmailFirstSeenDays: type: number description: Count of days since the email was first observed in Ekata's Identity Network. If the email has not been observed before, first_seen_days will be 0. example: 453 AccountOwnerAddresses: description: List of addresses type: array items: $ref: '#/components/schemas/AccountOwnerAddress' PhoneCarrier: type: string description: The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level. example: Vodafone UK ltd. AccountOwnerIdentityInsights: description: List of account owner Identity Insights type: object properties: requestRefId: $ref: '#/components/schemas/RequestRefId' isEmailValid: $ref: '#/components/schemas/EmailValid' emailFirstSeenDays: $ref: '#/components/schemas/EmailFirstSeenDays' emailDomainCreationDate: $ref: '#/components/schemas/EmailDomainCreationDate' emailToName: $ref: '#/components/schemas/EmailToName' emailMailboxVelocity: $ref: '#/components/schemas/EmailMailboxVelocity' emailIsDisposable: $ref: '#/components/schemas/EmailIsDisposable' ipRisk: $ref: '#/components/schemas/IpRisk' ipRiskScore: $ref: '#/components/schemas/IpRiskScore' identityRiskReasonCode: $ref: '#/components/schemas/IdentityRiskReasonCode' deviceRiskScore: $ref: '#/components/schemas/DeviceRiskScore' deviceType: $ref: '#/components/schemas/DeviceType' deviceBrowser: $ref: '#/components/schemas/DeviceBrowser' devicePlatform: $ref: '#/components/schemas/DevicePlatform' devicePhoneEmailFirstSeen: $ref: '#/components/schemas/DevicePhoneEmailFirstSeen' deviceBrowserIpTzDifference: $ref: '#/components/schemas/DeviceBrowserIpTzDifference' deviceIpEmailFirstSeen: $ref: '#/components/schemas/DeviceIpEmailFirstSeen' ipLastSeenDays: $ref: '#/components/schemas/IpLastSeenDays' ipGeolocationCountryCode: $ref: '#/components/schemas/IpGeolocationCountryCode' ipGeolocationSubdivision: $ref: '#/components/schemas/IpGeolocationSubdivision' ipPhoneDistance: $ref: '#/components/schemas/IpPhoneDistance' ipAddressDistance: $ref: '#/components/schemas/IpAddressDistance' isPhoneValid: $ref: '#/components/schemas/PhoneValid' phoneLineType: $ref: '#/components/schemas/PhoneLineType' phoneCarrier: $ref: '#/components/schemas/PhoneCarrier' phoneCountryCode: $ref: '#/components/schemas/PhoneCountryCode' phoneLastSeenDays: $ref: '#/components/schemas/PhoneLastSeenDays' phoneEmailFirstSeenDays: $ref: '#/components/schemas/PhoneEmailFirstSeenDays' phoneToName: $ref: '#/components/schemas/PhoneToName' phoneToAddress: $ref: '#/components/schemas/PhoneToAddress' addressValidityLevel: $ref: '#/components/schemas/AddressValidityLevel' addressToName: $ref: '#/components/schemas/AddressToName' emailRisk: $ref: '#/components/schemas/EmailRisk' identityRiskScore: $ref: '#/components/schemas/IdentityRiskScore' warnings: type: array items: $ref: '#/components/schemas/Warnings' alerts: type: array items: $ref: '#/components/schemas/Alerts' PhoneToAddress: type: string description: 'The match status between the input phone and the queried entity. * match - Phone location matches input address line 1, address line 2, city, state, and postal code. * postal-match - Phone location postal code matches input address postal code. * zip4-match - Phone location postal code zip+4 matches input address postal code zip+4. * city-state-match - Phone location city and state matches input address city and state. * metro-match - Phone location is in the same metro area as input address. * country-match - Phone location country matches input address country. * no-match - Phone location does not match input address.' example: match DeviceBrowserIpTzDifference: type: integer description: Time zone difference between device browser and IP location example: 1000 AddressType: type: string description: 'The type of address location: * "Business" * "Home" * "Mailing"' example: Home AuthorizationEndDate: type: integer format: int64 description: Authorization end date and time in epoch format (not used if AuthorizationExpires is false). example: 1641030399 AccountOwnerEmailPrimary: type: boolean description: The email is primary. example: true InstitutionName: type: string description: The name of the institution example: FinBank DeviceType: type: string description: The device type used to authorize your product or service. example: iPhone PhoneToName: type: string description: 'The match status between the input name and the queried entity. * not-found * match * no-match' example: match Country: type: string description: Country code is Iso3166-1 Alpha-2 code and Alpha 3 standard (max length 3). example: CAN Fields: type: string description: Mention API fields that needs to be fetched example: balanceDetails,paymentInstruction,accountIdentity PhoneValid: type: boolean description: True if the phone number is valid. example: true FieldErrors: type: array description: Lists of errors while getting the data items: $ref: '#/components/schemas/FieldError' AccountOwnerRelationshipType: type: string description: 'The type of relationship to the account: * "AUTHORIZED_USER" * "BUSINESS" * "FOR_BENEFIT_OF_PRIMARY" * "FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED" * "FOR_BENEFIT_OF_SECONDARY" * "FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED" * "FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED" * "POWER_OF_ATTORNEY" * "PRIMARY_JOINT_TENANTS" * "PRIMARY" * "PRIMARY_BORROWER" * "PRIMARY_JOINT" * "SECONDARY" * "SECONDARY_JOINT_TENANTS" * "SECONDARY_BORROWER" * "SECONDARY_JOINT" * "SOLE_OWNER" * "TRUSTEE" * "UNIFORM_TRANSFER_TO_MINOR"' example: AUTHORIZED_USER AddressToName: type: string description: 'The match status between the input name and the queried entity. * not-found * match * no-match' example: match InstitutionId: description: The ID of a financial institution type: string example: '4222' Address: type: string description: A street address example: '434 W Ascension Way Suite #200 Murray UT 84123' AccountOwnerPhoneType: type: string description: 'The account owner''s phone type: * "HOME" * "BUSINESS" * "CELL" * "FAX"' example: HOME DeviceRiskScore: type: number description: Comprehensive risk score associated with a device, with a higher score indicating a riskier device. A number between 0 and 1. example: 0.45 Name: type: string description: The account name from the institution example: Super Checking DevicePhoneEmailFirstSeen: type: integer format: int64 description: Days since the combination of device, phone, and email was first seen example: 140 IpRisk: type: boolean description: True if the IP address is considered risky, based on multiple IP data points and velocity calculations. example: true AssetId: type: string description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API. example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178 PebAllowedBalanceCacheInterval: type: integer format: int32 default: 30 minimum: 1 maximum: 1440 description: Time interval in minutes to check balance data against live balance from financial institution or from latest cached example: 15 GovernmentId: type: string description: "A federal or state issued identification number in alphanumeric characters.\n* **Canada**:\n\n * Passport: 8 digits\n\n * Driver: 6-9 digits" example: '123456789' AggregationStatusCode: type: integer description: The status of the most recent aggregation attempt (see [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes)). Won't be present until you have run your first aggregation for the account. IpGeolocationSubdivision: type: string description: More granular detail about the IP address location. example: Oregon AuthorizationStartDate: type: integer format: int64 description: Authorization start date and time in epoch format. example: 1541030399 NumericAccountId: type: integer format: int64 description: An account ID represented as a number example: 5011648377 PhoneEmailFirstSeenDays: type: number description: Count of days since the combination of phone and email was first observed in Ekata's Identity Network. If that combination has not been observed before, `phoneEmailFirstSeenDays` will be 0. example: 54 DeviceIpEmailFirstSeen: type: integer description: Days since the combination of device, IP, and email was first seen example: 365 Currency: type: string description: A currency code example: USD PEBAccountDetails: required: - id - institutionId - institutionName - institutionLoginId type: object properties: id: $ref: '#/components/schemas/AccountId' realAccountNumberLast4: $ref: '#/components/schemas/AccountNumberLast4' institutionId: $ref: '#/components/schemas/InstitutionId' institutionName: $ref: '#/components/schemas/InstitutionName' institutionLoginId: $ref: '#/components/schemas/NumericInstitutionLoginId' accountDetails: $ref: '#/components/schemas/AccountSimpleDetails' balanceDetails: $ref: '#/components/schemas/AvailableBalancePEB' accountIdentity: $ref: '#/components/schemas/AccountOwnerHolders' paymentInstruction: $ref: '#/components/schemas/PaymentInstructionPEB' errors: $ref: '#/components/schemas/FieldErrors' DevicePlatform: type: string description: The device platform used to authorize your product or service. example: iOS EmailRisk: type: number description: Email Risk Score assesses the risk level of an email address by leveraging features from our Identity Graph and Identity Network. It provides the strongest indicator of a high-risk email. example: 0.8 ClassificationConfidenceScore: type: number description: The confidence score 0 – 1.0 of the name classification. example: 0.9 minimum: 0 maximum: 1.0 Warnings: type: string description: "An array containing warning messages. Warnings can be one of:\n\n * Address: Input postal code was corrected\n * Address: Input state corrected\n * Email: Address is too long\n * Email: General syntax error\n * Email: Invalid domain syntax\n * Email: Invalid top-level-domain (TLD) in address\n * Email: Invalid username syntax\n * IP: IP address is in private range\n * Phone: Invalid country_hint value. Only Alpha-2 supported" example: Test warnings BalanceDetailsSuccessCount: type: integer format: int32 description: Total number of successful sections returned when requesting balanceDetails. If not provided, value will be 0. example: 1 Suffix: type: string description: A generational or academic suffix example: PhD ErrorCount: type: integer format: int32 description: The number of errors or failures that have occurred while processing the API request. If all the requested parameters are returned successfully then this value will be 0. Any value other than zero indicates failures. example: 0 NumericInstitutionLoginId: type: integer format: int64 description: An institution login ID (from the account record), represented as a number example: 1007302745 AccountOwnerName: type: string description: The full name of the account owner. Multiple account owners are returned in one string per the source data from the institution. example: John Smith, PhD EmailMailboxVelocity: type: number description: The velocity of the mailbox. example: 3 State: type: string description: State example: UT AsOfDate: type: integer description: The last time the payroll data was updated in the payroll provider's system format: int64 example: 1596175200 AccountOwnerPhone: description: Consumer phone type: object properties: type: $ref: '#/components/schemas/AccountOwnerPhoneType' country: $ref: '#/components/schemas/PhoneCountry' phone: $ref: '#/components/schemas/PhoneNumber' FirstName: type: string description: The first name of the account holder example: John FieldError: required: - fieldError - code - description type: object properties: fieldName: type: string description: Field Name example: balanceDetails code: type: string description: Error Code example: '102' description: type: string description: Error Description example: FI Down for maintenance IpRiskScore: type: number description: Comprehensive risk score associated with an IP address, with a higher score indicating a riskier IP address. A number between 0 and 1 rounded to three decimal places. example: 0.123 AddressValidityLevel: type: string description: "The most granular level to which the address could be validated. Ex. If the address was only valid to the city level (but not to the house level), it would return “valid_to_city”.\n * missing_address - An input address was not provided.\n\n * invalid - The input address is not valid.\n\n * valid - The input address is valid.\n\n * valid_to_country - The input address could only be validated to the\ncountry level. This means the country of the input address is valid, but the other elements of the input address were unable to be confirmed as valid or invalid.\n\n * valid_to_city - The input address was validated to the city level.\nThis means the country, state, city, and postal code of the input address are valid, but the street, house number, and subpremise of the input address were unable to be confirmed as valid or invalid.\n\n * valid_to_street - The input address was validated to the street\nlevel. This means the country, state, city, postal code, and street of the input address are valid, but the house number and subpremise of the input address were unable to be confirmed as valid or invalid.\n\n * valid_to_house_number - The input address was validated to the\nstreet and house number level. This means the country, state, city, postal code, street, and house number of the input address are valid, but the subpremise of the input address was unable to be confirmed as valid or invalid.\n\n * valid_to_house_number_missing_apt - The input address was\nvalidated to the street and house number level. This means the country, state, city, postal code, street, and house number of the input address are valid, but the subpremise of the input address was missing and thus unable to be confirmed as valid or invalid." example: valid EmailToName: type: string description: 'The match status between the input name and the queried entity. * not found * match * no-match' example: not found TaxId: type: string description: "Country specific tax ID associated with the customer.\n* **Canada**: Social Insurance Number (SIM) or Numero d'assurance sociale (NAS)\n\n * Format: 123-456-789" example: 123-45-7890 DateTimeWithZone: type: string format: date-time description: A date-time with time zone example: '2022-03-10T06:06:20.042584549Z' CustomerId: type: string description: A customer ID. See Add Customer API for how to create a customer ID. example: '1005061234' AccountNumberLast4: type: string description: The last 4 digits of the account number, derived by Mastercard from the account number provided by the financial institution. This is only returned for ACH-enabled accounts. example: '5678' AccountOwnerEmail: description: Account owner email type: object properties: isPrimary: $ref: '#/components/schemas/AccountOwnerEmailPrimary' email: $ref: '#/components/schemas/EmailAddress' emailType: $ref: '#/components/schemas/AccountOwnerEmailType' City: type: string description: City example: Murray RequestRefId: type: string description: The generated unique web transaction identifier. example: be3ad617-04ad-43e1-a438-79425b6511b6 DisplayPosition: type: integer description: "Display position of the account at the financial institution, \"1\"\n being the top listed account" format: int32 example: 2 AccountOwnerEmailType: type: string description: 'The account owner''s email type. * "Personal" * "Business"' example: Personal AccountNumberDisplay: type: string description: 'Account identifier derived by Mastercard from the account number provided by the financial institution. The format varies depending on the institution. We recommend using this to identify accounts if available. Below is a non-exhaustive list of examples for the `accountNumberDisplay` field. * 5720 * 3539-259 * 1500-1 * 0824-S0050' example: '7528' AccountCount: type: integer format: int32 description: Total number of accounts returned. example: 1 responses: GetPaymentEnablementBundleResponse: description: We successfully fetched the requested details content: application/json: schema: $ref: '#/components/schemas/PaymentEnablementBundle' examples: PaymentEnablementBundleResponse: $ref: '#/components/examples/PaymentEnablementBundleResponseExample' PaymentEnablementBundleResponseWithError: $ref: '#/components/examples/PaymentEnablementBundleWithErrorResponseExample' GetPaymentEnablementBundleResourceNotFoundForInstitutionLoginIdErrorResponse: description: The requested details do not match with the existing details or you requested something we don't have or was deleted. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: NoAccountForInstitutionLoginIdExample: $ref: '#/components/examples/NoAccountForInstitutionLoginIdExamplePEB' CustomerNotFoundExample: $ref: '#/components/examples/CustomerNotFoundExample' AuthenticationUnauthorizedErrorResponse: description: The request lacks valid authentication credentials. Check Partner ID, Partner Secret or Finicity-App-Key. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: MissingFinicityAppKeyExample: $ref: '#/components/examples/MissingFinicityAppKeyExample' InvalidCredentialsExample: $ref: '#/components/examples/InvalidCredentialsExample' NotAuthorizedExample: $ref: '#/components/examples/NotAuthorizedExample' GetPaymentEnablementBundleBadRequestErrorResponse: description: We couldn't handle your request, see response payload for more information. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: InvalidFieldParameterExample: $ref: '#/components/examples/InvalidFieldParameterExample' GenericBadRequestExample: $ref: '#/components/examples/GenericBadRequestExample' GetPaymentEnablementBundleResourceNotFoundForAccountIdErrorResponse: description: Customer ID or Account ID does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: NoAccountForCustomerIdExample: $ref: '#/components/examples/NoAccountForCustomerIdExample' CustomerNotFoundExample: $ref: '#/components/examples/CustomerNotFoundExample' parameters: PebAllowedBalanceCacheIntervalParameter: description: '`balance_cache_interval` (in minutes) is used at server side to decide whether to return existing cached balance or retrieve from financial institution in real-time. Details explained below: 1. If the cached balance data at server is older than provided `balance_cache_interval` then live balance from financial institution will be retrieved. 2. If the cached balance data is within provided `balance_cache_interval` allowed interval then balance from cache will be returned. 3. If `balance_cache_interval` is not provided, then by default pre defined cache interval will be used to decide whether to return existing cached balance or retrieve from financial institution in real-time.' name: balance_cache_interval in: query required: false schema: $ref: '#/components/schemas/PebAllowedBalanceCacheInterval' example: 30 InstitutionLoginIdParameterPEB: description: The institution login ID name: institutionLoginId in: path required: true schema: $ref: '#/components/schemas/NumericInstitutionLoginId' example: 1007302745 IncludeParameter: name: include in: query description: 'If you do not require all API fields ( `balanceDetails`, `accountIdentity` and `paymentInstruction`) then mention specific API fields you are interested in. For example, If you are interested in only `balanceDetails` and `paymentInstruction`, then send query string as include=`balanceDetails`,`paymentInstruction`' required: false schema: $ref: '#/components/schemas/Fields' example: balanceDetails, paymentInstruction, accountIdentity AccountIdParameter: description: The account ID name: accountId in: path required: true schema: $ref: '#/components/schemas/AccountId' example: '5011648377' CustomerIdParameter: description: A customer ID name: customerId in: path required: true schema: $ref: '#/components/schemas/CustomerId' example: '1005061234' securitySchemes: FinicityAppKey: name: Finicity-App-Key type: apiKey in: header description: The "Finicity-App-Key" from the developer dashboard FinicityAppToken: name: Finicity-App-Token type: apiKey in: header description: A token returned by the `/authentication` API