# Creditor Payment Preference
source: https://developer.mastercard.com/payment-acceptance-api/documentation/use-cases/creditor-payment-controls/index.md

The Creditor Agent uses the Payment Preference APIs to create, update, delete, or retrieve one or more payment preferences (payment controls). Creditor Agents can create preferences within Commercial Direct Payments (CDP) that are applied to payment instructions.   

Payment preferences specify how and when a Creditor accepts payment instructions. When a Debtor Agent submits a payment instruction, CDP validates the request against the Creditor's payment preferences before the payment proceeds through the payment lifecycle. If the payment instruction conflicts with the Creditor's configured payment preferences, it is either accepted or rejected.

## How payment preferences work {#how-payment-preferences-work}

* **Time preferences:** Allows Creditor Agents to control how long a Debtor can make a payment to a Creditor.
* **Relationship preferences:** Allows Creditor Agents to set restrictions for a Creditor based on which Debtor is making the payment.
* **Amount preferences:** Allows Creditor Agents to restrict payments based on the total payment amount.
* **Fee preferences:** Allows Creditor Agents to require an additional fee for payments made to a Creditor.

Tip: When creating a preference, you can specify the type of preference by modifying the contents of the `conditions` object.

Each payment preference must include a decision outcome. The decision can either warn or reject the Debtor.
If a payment instruction conflicts with the payment preference criteria, the instruction is rejected and the payment fails. In such cases, CDP rejects the payment on behalf of the Creditor at the CDP level.

If the payment instruction results in a warning, the payment instruction continues through the payment lifecycle; however, both the Creditor Agent and the Debtor Agent are notified of the warning.

#### Overview {#overview}

A time preference defines the allowable window for submitting a payment instruction relative to the invoice date.

#### Configuration {#configuration}

To create a time preference, set the `maxDaysAfterRelatedDate` field. This field specifies the maximum number of calendar days after the invoice date during which a payment instruction is accepted.

If a payment instruction is submitted **after** this window:

* The instruction is **flagged or rejected**
* The outcome is determined by the `decision` value configured in the preference body

#### Example Scenario {#example-scenario}

|                                                                                                                Scenario                                                                                                                 |                            Payload Fields to Configure                             |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| Create a time preference to **`<decision>`** payment instructions submitted **X** calendar days after the invoice date. **Example:** Supply Co rejects all card payment instructions received more than 10 days after the invoice date. | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"maxDaysAfterRelatedDate": "10"` |

#### Overview {#overview}

A relationship preference controls how payment instructions are handled based on the Debtor--Creditor relationship.

#### Configuration {#configuration}

To create a relationship preference, specify whether Debtors are **included** or **excluded** using one of the following fields:

* `includeDebtors`
* `excludeDebtors`

A Debtor can be identified using one or more of the following:

* Customer number
* Tax ID
* Debtor ID

#### Behavior {#behavior}

* **Include Debtors**   

  When `includeDebtors` is specified, the preference applies **only** to the listed Debtors. Debtors not included are not impacted.

* **Exclude Debtors**   

  When `excludeDebtors` is specified, the preference applies to **all Debtors except** those listed.

#### Example Scenarios {#example-scenarios}

|                                                                                                                   Scenario                                                                                                                    |                                                Payload Fields to Configure                                                 |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| Create a relationship preference to **`<decision>`** all **`<paymentMethod>`** from specific Debtors. **Example:** Supply Co flags all card payment instructions received from Debtor Co.                                                     | `"decision": "WARNING"` `"paymentMethod": "CARD"` `"includeDebtors": ["Debtor Co tax ID or Debtor ID or customer number"]` |
| Create a relationship preference to **`<decision>`** all **`<paymentMethod>`** from all Debtors except a specific Debtor. **Example:** Supply Co rejects all card payment instructions except those received from Debtor Co.                  | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"excludeDebtors": ["Debtor Co tax ID or Debtor ID or customer number"]`  |
| Create a relationship preference to **`<decision>`** all **`<paymentMethod>`** from all Debtors except multiple Debtors. **Example:** Supply Co rejects all card payment instructions except those received from Debtor Co 1 and Debtor Co 2. | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"excludeDebtors": ["Debtor Co 1 identifier", "Debtor Co 2 identifier"]`  |

#### Overview {#overview}

An amount preference defines acceptable payment instruction thresholds based on the instructed payment amount.

#### Configuration {#configuration}

To create an amount preference, configure the `instructedAmount` object and specify one or both of the following fields:

* `max` --- sets the maximum amount the Creditor accepts
* `min` --- sets the minimum amount the Creditor accepts

If a payment instruction violates the configured amount threshold, it is processed according to the `decision` value defined in the preference.

#### Example Scenarios {#example-scenarios}

|                                                                                Scenario                                                                                |                     Payload Fields to Configure                     |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| Create an amount preference to **`<decision>`** all **`<paymentMethod>`** over **`<max>`** . **Example:** Supply Co rejects all card payment instructions over 10,000. | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"max": "10000.0"` |
| Create an amount preference to **`<decision>`** all **`<paymentMethod>`** under **`<min>`** . **Example:** Supply Co rejects all ACH payment instructions under 100.   | `"decision": "REJECT"` `"paymentMethod": "ACH"` `"min": "100.0"`    |

#### Overview {#overview}

A fee preference defines whether a payment instruction must include specific fee information in order to be accepted.

#### Configuration {#configuration}

To create a fee preference, configure the `chargesInformation` object and specify one of the following fields:

* `percentageAmount` --- requires a percentage‑based fee to be included
* `flatAmount` --- requires a fixed fee amount to be included

If a payment instruction does not include the required fee information, it is processed according to the `decision` value defined in the preference.

#### Example Scenarios {#example-scenarios}

|                                                                                                         Scenario                                                                                                         |                        Payload Fields to Configure                         |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Create a fee preference to **`<decision>`** all **`<paymentMethod>`** that do not include a **`<percentageAmount>`** . **Example:** Supply Co rejects all card payment instructions that do not include a 2 percent fee. | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"percentageAmount": "2"` |
| Create a fee preference to **`<decision>`** all **`<paymentMethod>`** that do not include a **`<flatAmount>`** . **Example:** Supply Co flags all card payment instructions that do not include a flat fee of 10.        | `"decision": "WARNING"` `"paymentMethod": "CARD"` `"flatAmount": "10"`     |

#### Overview {#overview}

Preferences can be combined to define more granular payment handling rules. A single preference configuration may include multiple preference types, such as Time, Relationship, Amount, and Fee.

When multiple preference types are configured, all specified conditions must be met for the preference to apply. Payment instructions that violate any configured condition are processed according to the defined `decision`.

#### Example Combinations {#example-combinations}

|          Preference Types          |                                                                                                                                                                   Scenario                                                                                                                                                                   |                                                              Payload Fields to Configure                                                              |
|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Time and Relationship**          | Create a preference to **`<decision>`** all **`<paymentMethod>`** from **`<includeDebtors>`** submitted after **`<maxDaysAfterRelatedDate>`** . **Example:** Supply Co rejects all card payment instructions from Debtor Co received 30 days after the invoice date.                                                                         | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"includeDebtors": ["Debtor Co identifier"]` `"maxDaysAfterRelatedDate": "30"`                       |
| **Relationship and Amount**        | Create a preference to **`<decision>`** all **`<paymentMethod>`** over **`<max>`** from **`<includeDebtors>`** . **Example:** Supply Co rejects all card payment instructions over 500 received from Debtor Co.                                                                                                                              | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"max": "500"` `"includeDebtors": ["Debtor Co identifier"]`                                          |
| **Time and Amount**                | Create a preference to **`<decision>`** all **`<paymentMethod>`** over **`<max>`** submitted after **`<maxDaysAfterRelatedDate>`** . **Example:** Supply Co flags all card payment instructions over 20,000 received 90 days after the invoice date.                                                                                         | `"decision": "WARNING"` `"paymentMethod": "CARD"` `"max": "20000"` `"maxDaysAfterRelatedDate": "90"`                                                  |
| **Fee and Amount**                 | Create a preference to **`<decision>`** all **`<paymentMethod>`** over **`<max>`** that do not include **`<flatAmount>`** . **Example:** Supply Co rejects all card payment instructions over 1,000 that do not include a flat fee of 10.                                                                                                    | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"max": "1000"` `"flatAmount": "10"`                                                                 |
| **Time and Fee**                   | Create a preference to **`<decision>`** all **`<paymentMethod>`** that do not include **`<percentageAmount>`** submitted after **`<maxDaysAfterRelatedDate>`** . **Example:** Supply Co rejects all card payment instructions that do not include a 1.5 percent fee received 7 days after the invoice date.                                  | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"percentageAmount": "1.5"` `"maxDaysAfterRelatedDate": "7"`                                         |
| **Fee and Relationship**           | Create a preference to **`<decision>`** all **`<paymentMethod>`** from **`<includeDebtors>`** that do not include **`<percentageAmount>`** . **Example:** Supply Co flags all card payment instructions from Debtor Co that do not include a 2 percent fee.                                                                                  | `"decision": "WARNING"` `"paymentMethod": "CARD"` `"includeDebtors": ["Debtor Co identifier"]` `"percentageAmount": "2"`                              |
| **Time, Relationship, and Fee**    | Create a preference to **`<decision>`** all **`<paymentMethod>`** from **`<includeDebtors>`** received after **`<maxDaysAfterRelatedDate>`** that do not include **`<flatAmount>`** . **Example:** Supply Co rejects card payment instructions from Debtor Co received 29 days after the invoice date that do not include a flat fee of 100. | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"includeDebtors": ["Debtor Co identifier"]` `"flatAmount": "100"` `"maxDaysAfterRelatedDate": "29"` |
| **Time, Relationship, and Amount** | Create a preference to **`<decision>`** all **`<paymentMethod>`** from **`<includeDebtors>`** over **`<max>`** submitted after **`<maxDaysAfterRelatedDate>`** . **Example:** Supply Co rejects all card payment instructions from Debtor Co over 100,000 received 45 days after the invoice date.                                           | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"includeDebtors": ["Debtor Co identifier"]` `"max": "100000"` `"maxDaysAfterRelatedDate": "45"`     |
| **Time, Amount, and Fee**          | Create a preference to **`<decision>`** all **`<paymentMethod>`** over **`<max>`** that do not include **`<flatAmount>`** received after **`<maxDaysAfterRelatedDate>`** . **Example:** Supply Co rejects all card payment instructions over 10,000 received 30 days after the invoice date that do not include a flat fee of 25.            | `"decision": "REJECT"` `"paymentMethod": "CARD"` `"max": "10000"` `"maxDaysAfterRelatedDate": "30"` `"flatAmount": "25"`                              |

CDP validates each request and returns a response to the Creditor Agent indicating the outcome.
Diagram controloverview

1. The Creditor Agent uses the payment preference APIs to create, update, delete, or retrieve one or all preferences.
2. CDP validates the payment preference.
3. CDP notifies the Creditor Agent of the completed payment preference with response.

Note: The Mastercard assigned ICA number is used for agent identification in all service requests for core operations. A customer service provider can use their API credentials to transact on behalf of a customer by providing their customer's ICA number in the request. Direct payment agents can still transact by entering their own ICA number when sending a transaction to Mastercard CDP.

## Create a Creditor payment preference {#create-a-creditor-payment-preference}

This endpoint allows a Creditor Agent to make create a Creditor payment preference.
Diagram createnewcontrol

1. The Creditor Agent submits the create a Creditor payment preference request to CDP.
   API Reference: `POST /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls`

2. CDP validates the payment preference.
3. CDP creates the payment preference with the `paymentControlId`.
4. CDP returns a 201 Created response to the Creditor Agent.

Tip: The payment control ID is required for subsequent payment preference activities.

## Update a Creditor payment preference {#update-a-creditor-payment-preference}

This endpoint allows updates to a creditor's payment preferences after successful creation in CDP, such as when accepted payment methods change.
Diagram updatepaymentcontrol

1. The Creditor Agent sends the update a Creditor payment preference request to CDP.
   API Reference: `PUT /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls/{payment_control_id}`

2. CDP validates the request against the `paymentControlId`.
3. CDP updates the payment preference.
4. CDP returns a 201 Created response to the Creditor Agent.

## Delete a Creditor payment preference {#delete-a-creditor-payment-preference}

These endpoints can be used to delete either a single payment preference or all payment preferences associated with a creditor in CDP.

### Delete a single Creditor payment preference {#delete-a-single-creditor-payment-preference}

This endpoint allows a Creditor Agent to delete a single existing payment preference.
Diagram deletecontrol

1. The Creditor Agent submits a request to delete a single Creditor payment preference to CDP.
   API Reference: `DELETE /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls/{payment_control_id}`

2. CDP validates the request against the `paymentControlId`.
3. CDP deletes the payment preference.
4. CDP returns a 204 No Content response to the Creditor Agent.

### Delete all Creditor payment preferences {#delete-all-creditor-payment-preferences}

This endpoint allows a Creditor Agent to delete all existing payment preference for a Creditor profile.
Diagram deleteallcontrols

1. The Creditor Agent submits a request to delete all Creditor payment preferences to CDP.
   API Reference: `DELETE /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls`

2. CDP validates the request against the `Creditor_profile_id`.
3. CDP deletes all payment preference.
4. CDP returns a 204 No Content response to the Creditor Agent.

## Retrieve a Creditor payment preference {#retrieve-a-creditor-payment-preference}

These optional endpoints allow Creditor Agents to retrieve existing Creditor payment preferences. They can be used to retrieve a single payment preference or all payment preferences associated with a Creditor in CDP.

### Retrieve a single Creditor payment preference {#retrieve-a-single-creditor-payment-preference}

This endpoint allows a Creditor Agent to retrieve details about a single existing Creditor payment preference for a given Creditor.
Diagram getsinglecontrol

1. The Creditor Agent submits a request to retrieve a single Creditor payment preference to CDP.
   API Reference: `GET /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls/{payment_control_id}`

2. CDP validates the request against the `paymentControlId`.
3. CDP retrieves the payment preference.
4. CDP sends 200 OK response to the Creditor Agent.

### Retrieve all Creditor payment preferences {#retrieve-all-creditor-payment-preferences}

This endpoint allows a Creditor Agent to retrieve details about all existing payment preferences for a given Creditor.
Diagram getallcontrol

1. The Creditor Agent sends the retrieve all Creditor payment preference request to CDP.
   API Reference: `GET /creditor-agents/{ica}/payment-profiles/{creditor_profile_id}/payment-controls`

2. CDP validates the request against the `Creditor_profile_id`.
3. CDP retrieves all payment preference.
4. CDP sends 200 OK response to the Creditor Agent.