# Supplier payment preferences source: https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/preferences-tutorial/index.md ## Overview {#overview} Supplier Payment Agents can create preferences within Business Payment Service that are applied to payment instructions. Payment preferences specify how and when a Supplier accepts payment instructions. When a Buyer Payment Agent submits a payment instruction, Business Payment Service validates the payment instruction request against the Supplier's payment preferences before the payment proceeds through the payment lifecycle. If the payment instruction conflicts with the Supplier's payment preferences in place, it is either accepted or rejected. > > #### What you will learn {#what-you-will-learn} > > * How to create a Supplier payment preference > * How to update a Supplier's payment preferences > * How to delete a Supplier's payment preferences > * Optional - how to retrieve a supplier's payment preferences ## Before you start {#before-you-start} Review the payment preference types. * **Time Preference:** allows Supplier Payment Agents to enforce the duration of payment acceptance between a Buyer and their Supplier. * **Relationship Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier based on the Buyer making the payment. * **Amount Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier based on the total amount of a payment. * **Fee Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier in order to require an additional fee when making a payment. ## What you will achieve {#what-you-will-achieve} By completing this tutorial you will successfully manage your Supplier's payment preferences in Business Payment Service. ## Next steps {#next-steps} Click **Next** to get started. ## Create a Supplier payment preference {#create-a-supplier-payment-preference} Complete these steps to create a Supplier payment preference in Business Payment Service. Note: With the April 2023 release, an approved linking request is required when the Supplier payment preference flag is set to `NO`. If the display options for Supplier payment preferences are set to `YES`, then the available Supplier payment preferences are displayed. Contact your Mastercard representative to set the Supplier payment preferences flag. ### 1. Familiarize yourself with the various payment preference scenarios. {#1-familiarize-yourself-with-the-various-payment-preference-scenarios} * **Time Preference:** allows Supplier Payment Agents to enforce the duration of payment acceptance between a Buyer and their Supplier. * **Relationship Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier based on the Buyer making the payment. * **Amount Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier based on the total amount of a payment. * **Fee Preference:** allows Supplier Payment Agents to set a restriction for a given Supplier in order to require an additional fee when making a payment. Tip: When creating a preference, you can specify the type of preference by modifying the contents of the `conditions` object. You must also specify what the decision is for the payment preference. You can specify whether a payment preference rejects or warns the Buyer of the payment preference. If a payment preference conflicts with the payment preference criteria, then the payment instruction is rejected, and the payment fails. Business Payment Service rejects the payment on behalf of the Supplier and the payment instruction is rejected at the Business Payment Service level. If the payment instruction receives a warning message, then the payment instruction proceeds through the payment lifecycle, however, both the Supplier Payment Agent and Buyer Payment Agent are notified of the warning. To create a time preference, you must specify the `maxDaysAfterRelatedDate` field, which specifies the number of calendar days after the invoice date that the payment instruction will be accepted. If the payment instruction is submitted beyond the window of days specified by the `maxDaysAfterRelatedDate` field, then the payment instruction is either flagged or rejected based on the `decision` field set in the preference body. | Scenario | Example\* Objects within the payload that you need to update to achieve the desired preference | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | Create a time preference to `` for **X** number of calendar ``. Supply Co rejects all card payment instructions received 10 days after the invoice date. | "decision": "REJECT" "paymentMethod": "CARD" "maxDaysAfterRelatedDate": "10" | To create a relationship preference, you must indicate if a Buyer will be included or excluded in the preference by using the `includeBuyers`, or `excludeBuyers` fields. To specify a Buyer for this preference, you can use either the Buyer's tax ID or Buyer ID. Supplier Payment Agents can include a Buyer in the preference by adding the customer number, tax ID, buyer ID, or any combination of the three identification numbers in the request. The `includeBuyers` field apply the preference only to the Buyer(s) specified in the preference. Buyers not included in the preference are not impacted by the preference. Supplier Payment Agents can exclude a Buyer from the preference by adding the customer number, tax ID, buyer ID, or any combination of the three identification numbers in the request. The `excludeBuyers` field apply the preference to everyone except the Buyer(s) specified in the preference. | Scenario | Example\* Objects within the payload that you need to update to achieve the desired preference | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Create a relationship preference to `` all `` from ``. Supply Co flags all ACH payment instructions received from Buyer Co. | "decision": "WARNING" "paymentMethod": "ACH" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" | | Create a relationship preference to `` all `` from all Buyers except ``. Supply Co rejects all card payment instructions except those received from Buyer Co. | "decision": "REJECT" "paymentMethod": "CARD" "excludeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" | | Create a relationship preference to `` all `` from all Buyers except ``. Supply Co rejects all card payment instructions except those received from Buyer Co 1 and Buyer Co 2. | "decision": "REJECT" "paymentMethod": "CARD" "excludeBuyers": "\[Buyer Co 1's tax ID, Buyer ID, or customer number and Buyer Co 2's tax ID, Buyer ID, or customer number\]" | To create an amount preference, you must indicate whether a payment instruction will accept a maximum or minimum amount using the `max` and `min` fields within the `instructedAmount` object. The `max` field sets the limit for the highest amount the Supplier accepts. The `min` field sets the minimum amount a Supplier accepts. | Scenario | Example\* Objects within the payload that you need to update to achieve the desired preference | |----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | Create an amount preference to `` all `` over ``. Supply Co rejects all card payment instructions over 10,000. | "decision": "REJECT" "paymentMethod": "CARD" "max": "10000.0" | | Create an amount preference to `` all `` under `.` Supply Co rejects all ACH payment instructions under 100. | "decision": "REJECT" "paymentMethod": "ACH" "min": "100.0" | To create a fee preference, you must specify whether a `percentageAmount` or `flatAmount` fields within the `chargesInformation` object must be applied to the payment instruction. | Scenario | Example\* Objects within the payload that you need to update to achieve the desired preference | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | Create a preference to `` all `` that do not include a ``. Supply Co rejects all card payment instructions that do not include a 2 percent fee. | "decision": "REJECT" "paymentMethod": "CARD" "percentageAmount": "2" | | Create a preference to `` all `` that do not include a ``. Supply Co flags all ACH payment instructions that do not include a flat fee of 10. | "decision": "WARNING" "paymentMethod": "ACH" "flatAmount": "10" | When creating a preference, you can include more than one type of preference. This allows you to be more specific when indicating your Supplier's payment preference. | Preference Types | Desired Outcome | Example\* Objects within the payload that you need to update to achieve the desired preference | |--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Time and Relationship | Create a preference to `` all `` from `` made by ``. Supply Co rejects all card payment instructions from Buyer Co that are made 30 days after the invoice date. | "decision": "REJECT" "paymentMethod": "CARD" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" "maxDaysAfterRelatedDate": "30" | | Relationship and Amount | Create a preference that `` all `` over `` submitted by ``. Supply Co rejects all card payment instructions over 500 received from Buyer Co. | "decision": "REJECT" "paymentMethod": "CARD" "max": "500" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" | | Time and Amount | Create a preference to `` all `` over `` made by ``. Supply Co flags all ACH payment instructions over 20,000 received 90 days after the invoice date. | "decision": "WARNING" "paymentMethod": "ACH" "max": "20000" "maxDaysAfterRelatedDate": "90" | | Fee and Amount | Create a preference that `` all `` over `` that do not include a ``. Supply Co rejects all ACH payment instructions over 1,000 that do not include a flat fee of 10. | "decision": "REJECT" "paymentMethod": "ACH" "max": "1000" "flatAmount": "10", | | Time and Fee | Create a preference that `` all `` which do not have a `` included submitted by ``. Supply Co rejects all card payment instructions that do not include a 1.5 percent fee made 7 days after the invoice date. | "decision": "REJECT" "paymentMethod": "CARD" "percentageAmount": "1.5", "maxDaysAfterRelatedDate": "7" | | Fee and Relationship | Create a preference that `` all `` from `` that do not include ``. Supply Co flags all card payment instructions from Buyer Co that do not include a 2 percent fee. | "decision": "WARNING" "paymentMethod": "CARD" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" "percentageAmount": "2" | | Time, Relationship, and Fee | Create a preference that `` all `` from `` received by `` that do not include ``. Supply Co rejects ACH payment instructions from Buyer Co received 29 days after the invoice date that do not include a flat fee of 100. | "decision": "WARNING" "paymentMethod": "ACH" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" "flatAmount": "100" "maxDaysAfterRelatedDate": "29" | | Time, Relationship, and Amount | Create a preference that `` all `` from `` over `` amount after ``. Supply Co rejects all card payments received from Buyer Co over 100,000 received 45 days after the invoice date. | "decision": "REJECT" "paymentMethod": "CARD" "includeBuyers": "\[Buyer Co's tax ID, Buyer ID, or customer number\]" "max": "100000" "maxDaysAfterRelatedDate": "45" | | Time, Amount, and Fee | Create a preference that `` all `` over `` that does not include a `` received by ``. Supply Co rejects all card payment instructions over 10,000 received 30 days after the invoice date that does not include a flat fee of 25. | "decision": "REJECT" "paymentMethod": "CARD" "max": "10000" "maxDaysAfterRelatedDate": "30" "flatAmount": "25" | ### 2. Create the Supplier payment preference request using the POST Supplier payment preferences endpoint. {#2-create-the-supplier-payment-preference-request-using-the-post-supplier-payment-preferences-endpoint} API Reference: `POST /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls` ### 3. Review the possible error codes associated with this request. {#3-review-the-possible-error-codes-associated-with-this-request} If a Supplier payment preference request is incorrect or invalid, the payment preference is not created. If the failure is due to invalid information, you may receive one of the following error reason codes. | Reason Code | Description | |------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | SUPPLIER_ID_NOT_EXIST | Supplier ID `Supplier ID` does not exist. | | MISSING_DECISION | Enter a valid decision. | | MISSING_SUPPLIER_ID | Enter a supplierId. | | MISSING_PAYMENT_METHOD | Enter a paymentType. | | INVALID_CONTROLS_DECISION | Enter a valid control decision such as REJECT or WARNING. | | INVALID_PAYMENT_METHOD | Enter a valid payment method. Use one of the following; `list of supported Payment Methods`. | | INVALID_MAX_INSTRUCTED_AMT | Enter a valid maximum instructed amount value. | | INVALID_MIN_INSTRUCTED_AMT | Enter a valid minimum instructed amount value. | | INVALID_CURRENCY_CODE | Enter a valid ISO 4217 Alpha-3 currency code. | | INVALID_CHARGES_PERCENTAGE_AMT | Enter a valid charges percentage amount. | | INVALID_CHARGES_FLAT_AMT | Enter a valid charges flat amount. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | EXISTING_CONTROL | There is an existing `Control Condition` for `Payment Method` on this Supplier ID. | | INSTRUCTED_MIN_GREATER_MAX | The minimum instructed amount value cannot be greater than the maximum instructed amount value. | | INVALID_INCL_EXCL_CONTROL | Invalid control relationship. There cannot be both an include and exclude relationship setting on the same control. | | API_DOWN | This BPS API is down. Try again later. | | INVALID_CHARGES_CONDITION | Both charges percentage and charges flat amount cannot be used in the same control at the same time. | | INVALID_MIN_MAX_INSTRUCTED_AMT | Enter a valid maximum and minimum instructed amount value. There cannot be both the same value for maximum and minimum instructed amounts. | | MAX_DAYS_AFTER_RELATED_DATE | Enter a value less than 365 for Max Days After Related Date. | | INVALID_MAX_DAYS_AFTER_RELATED_DATE | Enter a valid number value. | | INVALID_REFERRED_DOCUMENT_TYPE | Enter a valid referred document type. | | INVALID_ORGANISATION_IDENTIFICATION_TYPE | Enter a valid organisation identification type. | | MISSING_ORGANISATION_IDENTIFICATION | Organisation identification is required with organisation identification type. | | MISSING_MAX_DAYS_AFTER_RELATED_DATE | Max days after related date is required with referred document type. | | DUPLICATE_REFERRED_DOCUMENT_TYPE | Only one condition allowed for each referred document type. | | INVALID_ORGANISATION_BUYER_ID | Enter a valid organisation Track BPS Buyer ID. | ### 4. Verify the Supplier payment profile was created successfully. {#4-verify-the-supplier-payment-profile-was-created-successfully} You should receive a 201 OK and the registration Id for the Supplier. Tip: You will need the payment control Id to complete other payment preference activities. ### 5. Click Next to proceed to updating the Supplier's payment preferences. {#5-click-next-to-proceed-to-updating-the-suppliers-payment-preferences} ## Update a Supplier payment preference {#update-a-supplier-payment-preference} You can make updates to the Supplier's payment preferences after the payment preference has been successfully created in Business Payment Service. For example, if a Supplier changes the payment methods they accept, you can update the information by leveraging this endpoint. To update the Supplier's payment preferences, complete these steps: ### 1. Create the Supplier payment preference request using the PUT Supplier payment preferences endpoint. {#1-create-the-supplier-payment-preference-request-using-the-put-supplier-payment-preferences-endpoint} The Mastercard assigned ICA 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 when sending a transaction to Mastercard Track Business Payment Service. API Reference: `PUT /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls/{payment_control_id}` ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request} If an update Supplier payment preferences request is incorrect or invalid, the payment preference is not updated. If the failure is due to invalid or missing information, you may receive one of the following error reason codes. | Reason Code | Description | |------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | MISSING_SUPPLIER_ID | Enter a supplierId. | | CONTROL_ID_NOT_EXIST | Control ID `Control ID Provided` does not exist. | | MISSING_CONTROL_ID | Enter a valid controlId. | | MISSING_DECISION | Enter a valid decision. | | MISSING_PAYMENT_METHOD | Enter a paymentType. | | INVALID_CONTROLS_DECISION | Enter a valid control decision such as REJECT or WARNING. | | INVALID_PAYMENT_METHOD | Enter a valid payment method. Use one of the following; `list of supported Payment Methods`. | | INVALID_MAX_INSTRUCTED_AMT | Enter a valid maximum instructed amount value. | | INVALID_MIN_INSTRUCTED_AMT | Enter a valid minimum instructed amount value. | | INVALID_CURRENCY_CODE | Enter a valid ISO 4217 Alpha-3 currency code. | | INVALID_CHARGES_PERCENTAGE_AMT | Enter a valid charges percentage amount. | | INVALID_CHARGES_FLAT_AMT | Enter a valid charges flat amount. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | INSTRUCTED_MIN_GREATER_MAX | The minimum instructed amount value cannot be greater than the maximum instructed amount value. | | INVALID_INCL_EXCL_CONTROL | Invalid control relationship. There cannot be both an include and exclude relationship setting on the same control. | | NO_EXISTING_CONTROLS | Supplier Payment Controls could not be found. | | INVALID_CHARGES_CONDITION | Both charges percentage and charges flat amount cannot be used in the same control at the same time. | | INVALID_MIN_MAX_INSTRUCTED_AMT | Enter a valid maximum and minimum instructed amount value. There cannot be both the same value for maximum and minimum instructed amounts. | | MAX_DAYS_AFTER_RELATED_DATE | Enter a value less than 365 for Max Days After Related Date. | | INVALID_MAX_DAYS_AFTER_RELATED_DATE | Enter a valid number value. | | INVALID_REFERRED_DOCUMENT_TYPE | Enter a valid referred document type. | | INVALID_ORGANISATION_IDENTIFICATION_TYPE | Enter a valid organisation identification type. | | MISSING_ORGANISATION_IDENTIFICATION | Organisation identification is required with organisation identification type. | | MISSING_MAX_DAYS_AFTER_RELATED_DATE | Max days after related date is required with referred document type. | | DUPLICATE_REFERRED_DOCUMENT_TYPE | Only one condition allowed for each referred document type. | | INVALID_ORGANISATION_BUYER_ID | Enter a valid organisation Track BPS Buyer ID. | ### 3. Verify the Supplier's payment preferences were successfully updated. {#3-verify-the-suppliers-payment-preferences-were-successfully-updated} You should receive a 200 OK response. ### 4. Click Next to proceed to deleting the Supplier's payment preferences. {#4-click-next-to-proceed-to-deleting-the-suppliers-payment-preferences} ## Delete Supplier payment preferences {#delete-supplier-payment-preferences} These optional endpoints allow Supplier Payment Agents to delete Supplier payment preferences. You can leverage these endpoints to either delete a single payment preference or all payment preferences associated with the Supplier in Business Payment Service. To delete Supplier payment preferences, complete these steps: ### 1. Create the single Supplier payment preference deletion request using the DELETE single Supplier payment preferences OR the DELETE all Supplier payment preferences endpoint to delete all Supplier payment preferences. {#1-create-the-single-supplier-payment-preference-deletion-request-using-the-delete-single-supplier-payment-preferences-or-the-delete-all-supplier-payment-preferences-endpoint-to-delete-all-supplier-payment-preferences} The Mastercard assigned ICA 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 when sending a transaction to Mastercard Track Business Payment Service. #### Delete a single Supplier payment preference {#delete-a-single-supplier-payment-preference} API Reference: `DELETE /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls/{payment_control_id}` #### Delete all Supplier payment preferences {#delete-all-supplier-payment-preferences} API Reference: `DELETE /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls` ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request-1} If you would like to delete an existing Supplier Payment Preference and request is incorrect, the preference is not deleted. If the failure is due to invalid information, you may receive one of the following error reason codes. | Reason Code | Description | |----------------------|--------------------------------------------------------------| | MISSING_SUPPLIER_ID | Enter a supplierId. | | CONTROL_ID_NOT_EXIST | Control ID `Control ID Provided` does not exist. | | MISSING_CONTROL_ID | Enter a valid controlId. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | NO_EXISTING_CONTROLS | Supplier Payment Controls could not be found. | If you would like to delete all existing Supplier Payment Preference and the request is incorrect, the preference are not deleted. If the failure is due to invalid information, you may receive one of the following error reason codes. | Reason Code | Description | |----------------------|--------------------------------------------------------------| | MISSING_SUPPLIER_ID | Enter a supplierId. | | CONTROL_ID_NOT_EXIST | Control ID `Control ID Provided` does not exist. | | MISSING_CONTROL_ID | Enter a valid controlId. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | NO_EXISTING_CONTROLS | Supplier Payment Controls could not be found. | ### 3. Verify the Supplier's payment preferences were successfully deleted. {#3-verify-the-suppliers-payment-preferences-were-successfully-deleted} You should receive a 204 OK response. ### 4. Click Next to proceed to retrieving the Supplier's payment preferences in Business Payment Service. {#4-click-next-to-proceed-to-retrieving-the-suppliers-payment-preferences-in-business-payment-service} ## Retrieve Supplier payment preferences {#retrieve-supplier-payment-preferences} These optional endpoints allow Supplier Payment Agents to retrieve existing Supplier payment preferences. You can leverage these endpoints to either lookup a single payment preference or all payment preferences associated with a Supplier in Business Payment Service. To retrieve Supplier payment preference(s) in Business Payment Service, complete these steps: ### 1. Create a single Supplier payment preference retrieval request using the GET a single Supplier payment preferences endpoint OR the GET all Supplier payment preferences endpoint to retrieve all existing Supplier payment preferences. {#1-create-a-single-supplier-payment-preference-retrieval-request-using-the-get-a-single-supplier-payment-preferences-endpoint-or-the-get-all-supplier-payment-preferences-endpoint-to-retrieve-all-existing-supplier-payment-preferences} The Mastercard assigned ICA 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 when sending a transaction to Mastercard Track Business Payment Service. #### Retrieve a single Supplier payment preference {#retrieve-a-single-supplier-payment-preference} API Reference: `GET /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls/{payment_control_id}` #### Retrieve all Supplier payment preferences {#retrieve-all-supplier-payment-preferences} API Reference: `GET /supplier-payment-agents/{ica}/suppliers/{supplier_id}/payment-preferences/payment-controls` ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request-2} If you would like to retrieve an existing Supplier payment preference and request is incorrect, the preference is not retrieved. If the failure is due to invalid information, you may receive one of the following error reason codes. | Reason Code | Description | |----------------------|--------------------------------------------------------------| | MISSING_SUPPLIER_ID | Enter a supplierId. | | CONTROL_ID_NOT_EXIST | Control ID `Control ID Provided` does not exist. | | MISSING_CONTROL_ID | Enter a valid controlId. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | NO_EXISTING_CONTROLS | Supplier Payment Controls could not be found. | | MISSING_SUPPLIER_ID | Enter a supplierId. | If you would like to retrieve all existing Supplier Payment Preference for a given Supplier Id and request is incorrect, the preference are not retrieved. If the failure is due to invalid information, you may receive one of the following error reason codes. | Reason Code | Description | |----------------------|--------------------------------------------------------------| | MISSING_SUPPLIER_ID | Enter a supplierId. | | CONTROL_ID_NOT_EXIST | Control ID `Control ID Provided` does not exist. | | MISSING_CONTROL_ID | Enter a valid controlId. | | INVALID_SUPPLIER_ID | This Supplier ID is not associated with your company in BPS. | | NO_EXISTING_CONTROLS | Supplier Payment Controls could not be found. | | MISSING_SUPPLIER_ID | Enter a supplierId. | ### 3. Verify the Supplier payment preference details were successfully retrieved. {#3-verify-the-supplier-payment-preference-details-were-successfully-retrieved} You should receive a 200 response.