# Feedback Loop API
source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/api/index.md
The **Pay Feedback API** enables you to submit payment outcome data to
Mastercard for Feedback Loop.
Mastercard uses this feedback to improve the accuracy of [Payment Success Indicator
(PSI)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/psi-tools/index.md).
Currently, the API only supports feedback for PSI.
Warning: The Pay Feedback API will not be live until 12 October 2026.
## How It Works {#how-it-works}
The API has two endpoints for submitting data:
* [Plaintext](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/api/index.md#plaintext-feedback-endpoint): Send feedback as JSON in the request body.
* [Encrypted](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/api/index.md#encrypted-feedback-endpoint): Send feedback as an encrypted payload (using [Mastercard payload encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#overview)).
Both endpoints accept the same business data and validation rules.
1. Prepare payment outcome data using the Feedback API schema.
2. Choose a submission method: plaintext or encrypted.
3. Send the feedback to the appropriate endpoint.
4. Mastercard validates and processes the submitted data.
5. Review the response for successfully processed and rejected records.
Diagram feedback-loop-api-flow Tip: We recommend sharing data at consistent intervals (monthly or bi-weekly) to ensure models stay current and product performance improves consistently.
## Before You Begin {#before-you-begin}
You need:
* Access to the Mastercard Open Finance US APIs.
* Authentication credentials - refer to [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md) and the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md) for details of how to set up authentication.
* Payment outcome data that follows the Feedback API schema.
## Submission Format {#submission-format}
* Submit **up to 25,000 records per request**.
* For datasets larger than 25,000 records, split the data across multiple requests.
* For encrypted submissions, ensure your encryption/decryption configuration is correctly set up before sending Production data.
### Submission Fields {#submission-fields}
| Field | Data Type | Description | Required | Example/Notes |
|--------------------|-----------|----------------------------------------------------|-------------|-------------------------------------------------------------------------------------|
| `product` | string | Pay product associated with the feedback | Yes | Must be `PSI` |
| `partnerId` | integer | Production partner ID provided by Mastercard | Yes | Positive int64; the same partner ID must be used for every item in the request |
| `customerId` | integer | Customer ID provided by Mastercard | Yes | Positive int64; customer must exist |
| `payReqId` | string | Payment request ID associated with the transaction | Yes | Must contain 1-30 digits |
| `paymentId` | string | Identifier that you provide for the payment | Yes | Must contain 1-30 digits |
| `settled` | string | Indicates whether the payment settled | Yes | Must be `Y` or `N` |
| `initiationAmount` | decimal | Value of the transaction | Yes | Must be greater than zero |
| `initiationDate` | string | Date the payment was initiated | Yes | Format: `YYYY-MM-DD` |
| `settledDate` | string | Date the transaction settled | Conditional | Format: `YYYY-MM-DD` Required when `settled = Y`; must be absent when `settled = N` |
| `returnDate` | string | Date the transaction was returned | Conditional | Format: `YYYY-MM-DD` Required when `settled = N`; must be absent when `settled = Y` |
| `returnReason` | string | Reason the transaction was returned | Conditional | Example: `R10` Required when `settled = N`; must be absent when `settled = Y` |
### Settled Payment Example {#settled-payment-example}
When `settled = Y`:
* `settledDate` is required.
```json
{
"payFeedbacks": [
{
"product": "PSI",
"partnerId": 1234567890,
"customerId": 9876543210,
"paymentId": "9988776655",
"settled": "Y",
"initiationDate": "2025-09-10",
"settledDate": "2025-09-11",
"initiationAmount": 250.75,
"payReqId": "123456789"
}
]
}
```
### Returned Payment Example {#returned-payment-example}
When `settled = N`:
* `returnDate` is required.
* `returnReason` is required.
* `settledDate` should not be provided.
```json
{
"payFeedbacks": [
{
"product": "PSI",
"partnerId": 1234567890,
"customerId": 9876543210,
"paymentId": "9988776655",
"settled": "N",
"initiationDate": "2025-09-10",
"returnDate": "2025-09-15",
"returnReason": "R01",
"initiationAmount": 250.75,
"payReqId": "123456789"
}
]
}
```
## Plaintext Feedback Endpoint {#plaintext-feedback-endpoint}
Use this endpoint to submit payment feedback as standard JSON.
API Reference: `POST /payments/feedbacks`
### Request Body {#request-body}
```json
{
"payFeedbacks": [
{
"product": "PSI",
"partnerId": 1234567890,
"customerId": 9876543210,
"paymentId": "9988776655",
"settled": "Y",
"initiationDate": "2025-09-10",
"settledDate": "2025-09-11",
"initiationAmount": 250.75,
"payReqId": "123456789"
}
]
}
```
### Response {#response}
A successful request returns **HTTP 200 OK**.
The response indicates how many records were successfully processed and
identifies any records that could not be processed.
#### Full Success {#full-success}
```json
{
"totalFeedbackCount": 150,
"successFeedbackCount": 150,
"errorFeedbackCount": 0,
"errorItems": []
}
```
#### Partial Success {#partial-success}
A request can contain both valid and invalid records. The API processes the
valid records and returns the invalid records in `errorItems`.
The HTTP response remains **200 OK**.
Warning: You should check `errorItems` even when the API returns `200`.
```json
{
"totalFeedbackCount": 150,
"successFeedbackCount": 149,
"errorFeedbackCount": 1,
"errorItems": [
{
"product": "PSI",
"paymentId": "9988776655",
"errorCode": "450004",
"errorMessage": "Invalid Combination of PartnerId,CustomerId and Account"
}
]
}
```
## Encrypted Feedback Endpoint {#encrypted-feedback-endpoint}
Use this endpoint when submitting encrypted data.
Refer to [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#overview) for
details of how to encrypt your data.
Before encryption, your payload content should follow the same business data and validation rules as for the [plaintext endpoint request](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/api/index.md#request-body).
API Reference: `POST /payments/encrypted-feedbacks`
### Encrypted Request {#encrypted-request}
```json
{
"encryptedFeedbackRequestProperties": ""
}
```
After receiving the request, the API:
1. Validates that the encrypted payload is present.
2. Decrypts the payload.
3. Validates the underlying feedback data.
4. Processes the feedback.
5. Returns an encrypted response.
### Encrypted Response {#encrypted-response}
```json
{
"encryptedFeedbackResponseProperties": ""
}
```
Refer to [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#overview) for details of how to decrypt the response. The response content follows the
same format as the [plaintext endpoint response](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/api/index.md#response).