# PSI FCRA source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/psi-fcra/index.md Note: This documentation has been updated to describe the latest PSI endpoints which add support for an unauthorized return score. For details of the legacy endpoints, see [Legacy PSI Endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/legacy/index.md). ## PSI FCRA Flow {#psi-fcra-flow} Diagram psi-fcra ## Execution Steps {#execution-steps} 1. Customer Consent: The merchant/fintech/PSP obtains customer consent to share bank data when setting up recurring payments. 2. PSI Request: A PSI FCRA request is sent prior to payment initiation via a **POST** call. 3. Risk Assessment: Mastercard analyzes the account and returns NSF and unauthorized return risk scores via a **GET** call. 4. Payment Decision: The merchant makes a decision. * If using PSI FCRA, the customer must receive a link to the [Finicity Consumer Portal](https://consumer.finicityreports.com/) to dispute decisions. Note: For PSI FCRA: * the [customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) must include an email address. * the API request must include an FCRA [permissible purpose code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md). ## Technical Documentation {#technical-documentation} Refer to the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) for creating a [customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) record using your `partnerId` and generating a [Connect](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) URL to use this service. Note that the endpoints require [authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication). API Reference: `POST /payments/customers/{customerId}/accounts/{accountId}/fcra-payment-success-indicators` **Generate FCRA Payment Success Indicators** returns a `payRequestId` - use it to call the endpoint below and retrieve the PSI scores. API Reference: `GET /payments/customers/{customerId}/accounts/{accountId}/fcra-payment-success-indicators/{payRequestId}` Tip: If you want the optional NSF reason codes, set `include_reasons` to `true` when calling the above endpoint. If the PSI data is not yet ready, **Get FCRA Payment Success Indicators by Pay Request ID** returns a `status` value of `IN PROGRESS`. You can poll the endpoint until the data is available. If you are making multiple GET requests immediately after calling **Generate Non-FCRA Payment Success Indicators**, wait 0.5 to 1 second between each GET request. We recommend integrating with the [Get Available Balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md#get-available-balance) endpoint as a fallback. Your solution should first call **Get FCRA Payment Success Indicators by Pay Request ID** , then use **Get Available Balance** if the PSI request fails, so you can still retrieve the customer's available balance. ## Understanding the PSI Response Data {#understanding-the-psi-response-data} * The `nsfReturnRisk` and `unauthorizedReturnRisk` tiers correspond to the `score` value. There are 3 possible tiers: * `score` 0-10 corresponds to "High Risk" * `score` 11-30 corresponds to "Medium Risk" * `score` 31-100 corresponds to "Low Risk" * The `reasons` array for each day with the `nsfReturnRisk` can be used to see why the score for a given day was generated. Reasons can be interpreted as both negative and positive drivers, influencing the `score` value. For example: * `score` 100 and `nsfHistory` 100 may be interpreted as that this account has had few, if any, NSF occurrences in the past, and it is **unlikely** to result in NSF. * `score` 10 and `nsfHistory` 100 may be interpreted as that this account has multiple NSF occurrences in the past, and it is **likely** to result in NSF.
See [Interpreting the Scores](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/how-psi-works/index.md#interpreting-the-scores) for full details. ## Error Codes {#error-codes} The following table lists the errors that are specific to this API. See also the [Error Handling](https://developer.mastercard.com/open-finance-us/documentation/errors/index.md) section for a list of general errors and status codes which can occur. Warning: In some cases, a server-side failure can result in an HTTP 200 response being returned with an internal error (such as 18002) in the response body. This is a known issue which we are working to resolve. Retry the request and contact your Customer Success Manager if the problem persists. | **HTTP Code** | **Status Code** | **Description** | **Remediation for Partner** | |---------------|-----------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | 10005 | "invalid purpose code" | [Permissible purpose code](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) must be "1P" for a payments use case. | | 400 | 10006 | "settleByDate must not be in the past" | Call the PSI endpoint with a `settleByDate` value equal to today or for a future date. | | 400 | 10007 | "\[FIELD\] is the incorrect type" | Call the PSI endpoint with correct type for the identified field. | | 400 | 10008 | "account has no transactions" | This indicates that the consumer's account does not have sufficient transaction history to produce a risk score with confidence. You may decline or accept the transaction. | | 400 | 10009 | "\[FIELD\] is a required parameter" | Call the PSI endpoint with the identified field provided. | | 400 | 10013 | "Only active accounts can be used, please use a different account" | The customer must select an active account when linking their accounts. | | 400 | 12022 | "An email is required when registering a customer for PSI-FCRA" | Add customer email during the [create customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#customers) process. | | 401 | 24302 | "Bad credentials" | Call the PSI endpoint with a valid app key and token. If this doesn't work, it is possible that your account is locked due to security reasons (normally as a result of multiple failed attempts). Contact customer support to unlock your account. | | 404 | 14001 | "customerId not found" | Ensure you are using the correct customer ID. If the customer ID is correct, it might be that the account has had no activity for a long period leading to an inactive status.​ | | 404 | 38003 | "accountId not found" | Ensure you are using the correct account ID and that the customer has connected their account. | ## Testing {#testing} See the [Payment Success Indicator Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-success-indicator-profiles) section of [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md) for details of banking profiles which are provided for testing purposes. These profiles are designed to return different PSI scores for different payment amounts and settlement dates. ## FCRA Considerations {#fcra-considerations} This section is intended for product, compliance, and operational teams to understand and implement The Fair Credit Reporting Act (FCRA) requirements and responsibilities. ### FCRA Background {#fcra-background} The Fair Credit Reporting Act (FCRA) regulates access to and accuracy of consumer reports and enables consumers to see and dispute the content of the consumer reports prepared on them. Companies and persons seeking to obtain a consumer report must have a legally permissible purpose enumerated under the FCRA, such as decisioning an application for credit, insurance, employment, or other defined purposes. Additionally, the FCRA requires that report users notify the consumer when an adverse action is taken based on such reports. ### FCRA Applicability {#fcra-applicability} The FCRA applies when a consumer's credit or other financial account and personal information is provided by a consumer reporting agency to a third party to inform that third-party's decisions about a consumer's eligibility, such as their eligibility for credit, housing, employment, or other business purposes. With respect to PSI, the FCRA is applicable to use cases where a merchant intends on leveraging PSI to determine whether to accept or reject consumer payment transactions and/or provide instant access to funds or services. ### FCRA Requirements {#fcra-requirements} For products and use cases that are subject to FCRA, consumers are granted several rights, including the right to be notified that an adverse action has been taken against them; the right to access their file, which must include the data compiled on them to generate a consumer report; and the right to dispute and have corrected any incomplete, inaccurate, or unverifiable information in that file. ### FCRA Requirements by Participant {#fcra-requirements-by-participant} | **Requirement and Description** | **Responsible Party and Guidelines** | |------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Notification:** Consumers must be notified that an adverse action, such as a rejected transaction, has been taken against them. | **Partner:** Partners using PSI FCRA must update their experience to notify the consumer. The notification must include the Pay Request ID and link to the Finicity Consumer Portal. An example notification is captured below. We recommend that you store the Pay Request ID for 60 days, as consumers are allotted 60 days to initiate a dispute. | | **Consumer Report Disclosure:** Consumers must be provided access to review information in consumer reports on them. | **Finicity:** Finicity provides, as part of the Consumer Portal, the Consumer Report Disclosure, which was designed in compliance with regulatory requirements and with the end consumer in mind. | | **Consumer Disputes via Portal:** Consumers must have the ability to review and dispute the information in their consumer reports. | **Finicity:** Finicity provides a Consumer Portal, where the consumer can view his/her report and is assisted by our dedicated Disputes Team. The Consumer Portal is located at [`https://consumer.finicityreports.com/`](https://consumer.finicityreports.com/). For more information on how consumers can use the portal, see the [consumer-facing guidance](https://www.mastercard.com/us/en/business/open-finance/consumer.html). | ### Example FCRA Notification {#example-fcra-notification} The following example user flow shows how a merchant app might use PSI to assess the risk of accepting a payment, and display an alert to the consumer with a link to the Finicity consumer dispute portal if the payment is not accepted as a result. The consumer must also be provided with the Pay Request ID relating to the payment in question. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-notification-cx_1.png) ### FCRA Consumer Journey in the Finicity Consumer Portal {#fcra-consumer-journey-in-the-finicity-consumer-portal} The following screens show a typical user journey in the consumer portal. The consumer will need to create an account (if they don't already have one), authenticate themselves, and then provide the Pay Request ID they were given by the merchant. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-dispute-portal-cx-1_1.png) The consumer portal will then provide information about the PSI report so they can file a dispute if they think something is wrong. ![](https://static.developer.mastercard.com/content/open-finance-us/uploads/psi-fcra-dispute-portal-cx-2_1.png)