# Linking source: https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/linking-tutorial/index.md ## Overview {#overview} Linking is the functionality Buyer Payment Agents use to retrieve the correct Supplier ID and Supplier payment preferences to use when submitting a payment instruction through Business Payment Service. An approved link between trading partners reduces the probability that a payment instruction fails due to incorrect vendor data. Supplier Payment Agents can approve or reject link requests received from Buyer Payment Agents. An approved link request establishes the Buyer as a customer of the Supplier and enables them to pay the Supplier with Business Payment Service. Supplier Payment Agents can nudge a Buyer Payment Agent to create a link request between trading partners. Agents will typically complete linking activities after they have used the Mastercard Track Search endpoints to lookup Buyer data. Tip: Supplier Payment Agents can indicate if an approved link is required before a Buyer can pay a Supplier through Business Payment Service. The link required activities are completed using the [POST](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/registration-tutorial/index.md) and [PUT](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/registration-tutorial/index.md) Supplier registration endpoints. For more information on how to indicate that a link is required, refer to the [Managing Supplier registration](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/registration-tutorial/index.md) tutorial. > > #### What you will learn {#what-you-will-learn} > > * How to respond to a linking nudge from a Supplier Payment Agent > * How to initiate a linking request > * How to delete an existing link > * How to find and filter existing Supplier links ## Before you start {#before-you-start} Before starting this tutorial, ensure that you have already completed the following: * Registered with Mastercard Track Business Payment Service ## What you will achieve {#what-you-will-achieve} By completing this tutorial you will successfully link a trading partner to ensure you are making payments to the correct entity. ## Next steps {#next-steps} Click **Next** to get started. ## Nudge a link request {#nudge-a-link-request} As a Supplier Payment Agent you can suggest that a Buyer Payment Agent initiate a link request between their Buyer and your Supplier. Though Supplier Payment Agents cannot directly initiate a link, you can leverage this endpoint to let the Buyer Payment Agent know that you want to create a link between the trading partners. Complete the steps to suggest that a Buyer Payment Agent initiate a link request. ### 1. Create the link suggestion request using the POST linking endpoint. {#1-create-the-link-suggestion-request-using-the-post-linking-endpoint} You can nudge the Buyer Payment Agent by leveraging: API Reference: `POST /supplier-payment-agents/{ica}/supplier-payment-profiles/{spa_profile}/suggested-buyer-links` Note: With the April 2023 release, the previously required `supplierRegistrationId` field is now optional. ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request} If a link suggestion request is incorrect or invalid, the link suggestion is not created. If the failure is due to invalid information, you may receive one of the following error reason codes. | Error Code | Description | |-------------------------------|-------------------------------------------------------------------------------------------------------------------| | INVALID_LINK_REGISTRATION_ID | Enter a valid registration Id. | | INVALID_BUYER_REGISTRATION_ID | Enter a valid Buyer registration id. `[id]` is either not valid or is not associated to your profile. | | SUGGESTED_LINK_EXISTS | A link suggestion for buyer `[buyerRegistrationId]` has already been sent for supplier `[supplierRegistrationId]` | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | ### 3. Verify the link suggestion was successful. {#3-verify-the-link-suggestion-was-successful} You should receive a 201 OK. Once the Buyer Payment Agent receives the link suggestion, they must initiate the link request. Once the link request is received by Business Payment Service from the Buyer Payment Agent, then you will be prompted to update the authorization status of the link request. ### 4. Click Next to proceed to updating the status of the link request. {#4-click-next-to-proceed-to-updating-the-status-of-the-link-request} ## Update the status of the link request {#update-the-status-of-the-link-request} As a Supplier Payment Agent, you can approve or reject the link request between trading partners. Complete the steps to approve or reject the link request. ### 1. Business Payment Service sends the LINK_REQUESTED event notification to the Supplier Payment Agent after the Buyer Payment Agent requests a link. {#1-business-payment-service-sends-the-link_requested-event-notification-to-the-supplier-payment-agent-after-the-buyer-payment-agent-requests-a-link} Review the sample event notification associated with the link request. Note: With the February 2022 release, Supplier Payment Agents can view the `annualExpectedSpend` object if the Buyer Payment Agent included it in the linking request. * JSON ```JSON { "eventId": "someGUID", "eventType": "LINK_REQUESTED", "eventCreatedDate": "2021-01-14T21:14:49.16Z", "data": { "status": "PENDING", "referenceData": { "referredDocumentInformation": [ { //At least 1 required "type": "CINV", //Required Other possible values: CREN (Credit Notes, PUOR (Purchase Order) "number": "123", //Required "relatedDate": "2020-09-01" //Optional } ], "requestedSupplierProfileId": "someSupplier@track",//Optional "customerNumber": "someCustomerIdProvidedByAgent", //Optional "phoneNumber": "somePhoneNumber",//Optional "emailAddress": "some@email.com" //Optional "annualExpectedSpend": { "volume": 1000000, "currency": "USD" }, "buyer": { "dba": "Buyer Co.", "id": "7b8bfb09-3fdc-4cd1-b768-477757fec6be", "inactiveReason": "PRE_REGISTERED", "isActive": true, "legalBusinessAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "legalBusinessName": "Buyer Company", "organisationIdentifications": [ { "identification": "998765432", "type": "TXID" } ], "profile": { "profileId": "someCo.pay@track", "isActive": true, "localInstruments": [ "BECS", "FPS", "INST", "ONCL", "PERI", "SDCL" ], "payToAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "paymentMethods": [ "CARD", "ACH", "TRF" ] } }, "supplier": { "id": "someRegistrationGUID", "dba": "Supplier Co.", "isActive": true, "legalBusinessAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "legalBusinessName": "Buyer Company", "organisationIdentifications": [ { "identification": "998765432", "type": "TXID" } ], "availableProfiles": [ { "profileId": "someCo@track", "billToAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "isActive": true, "localInstruments": [ "BECS", "FPS", "INST", "ONCL", "PERI", "SDCL" ], "paymentMethods": [ "CARD", "ACH", "TRF" ] }, { "profileId": "someDifferentCo@track", "billToAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "isActive": true, "localInstruments": [ "BECS", "FPS", "INST", "ONCL", "PERI", "SDCL" ], "paymentMethods": [ "CARD" ] } ] } } } ``` ### 2. Approve or reject the link request using PUT linking endpoints. {#2-approve-or-reject-the-link-request-using-put-linking-endpoints} 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. #### Approve the link request {#approve-the-link-request} You can approve the link request by leveraging: API Reference: `PUT /supplier-payment-agents/{ica}/supplier-payment-profiles/{spa_profile}/buyer-links/{bpa_profile}` Tip: Once the Supplier Payment Agent approves the link for a specific supplier Id, the Supplier Payment Agent can approve any additional Supplier profile Ids associated with the same Supplier registration Id for the Buyer Id. You can approve other link requests by changing the Supplier Id in th URI. #### Reject the link request {#reject-the-link-request} You can reject the link request by leveraging: API Reference: `PUT /supplier-payment-agents/{ica}/buyer-links` Tip: The `REJECTED` status is final. Once the link request is rejected, it cannot then be approved or deleted. To initiate a new request, the Supplier Payment Agent can nudge the Buyer Payment Agent to submit a new link request. ### 3. Review the possible error codes associated with this request. {#3-review-the-possible-error-codes-associated-with-this-request} If a link update request is incorrect or invalid, the link status is not updated. If the failure is due to invalid information, you may receive one of the following error reason codes. | Error Code | Description | |----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | | INVALID_LINK_UPDATE | Verify the value entered for the link status update request. Valid values are APPROVED or REJECTED. | | INVALID_REASON_CODE | Verify the value entered for reason code. Valid values are NO_BUYER_RECORD, NO_SUPPLIER_RECORD, WRONG_TRADING_PARTNER and NO_ELECTRONIC_PAYMENTS_ALLOWED. | | LINK_ALREADY_APPROVED | Link from `[Buyer profile Id]` to `[Supplier profile Id]` already approved. | | LINK_ALREADY_REJECTED | The link you are trying to approve is already rejected." | | SUPPLIER_INACTIVE | This Supplier has been deactivated. BPS transactions associated with this Supplier are not permitted. Please contact Customer Technical Support at 312-479-9100 (US) or email [Track.Support@mastercard.com](mailto:Track.Support@mastercard.com) for further details. | | INVALID_LINK_SUPPLIER_PROFILE_ID | Supplier Profile ID `[Supplier profile Id]` is not associated with Supplier `[Supplier registration Id]` | | SUPPLIER_PROFILE_INACTIVE | Supplier Profile ID `[Supplier profile Id]` has been deactivated. Please use different Supplier Profile ID. | | BUYER_PROFILE_NOT_FOUND | Buyer Profile `[Buyer profile Id]` not found. | | NO_LINK_TO_REJECT | No 'PENDING' links available to reject. | | CANNOT_REJECT_APPROVED_LINK | Existing approved link between `[Buyer profile Id]` and `[Supplier profile Id]` cannot be rejected, but can be deleted." | If you reject the link request, you must include a reason code for the rejection. | Reason Code | Description | |--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | NO_BUYER_RECORD | Your link for `[Buyer Name]` and `[Supplier Name]` was rejected by the Supplier Agent and/or Supplier because they do not currently have a record of \[Buyer Name\] in their system. | | NO_SUPPLIER_RECORD | Your link for `[Buyer Name]` and `[Supplier Name]` was rejected by the Supplier Agent and/or Supplier because the Supplier no longer does business with their SPA. | | WRONG_TRADING_PARTNER | Your link for `[Buyer Name]` and `[Supplier Name]` was rejected by the Supplier Agent and/or Supplier because the `[Supplier Name]` does not do business with this `[Buyer Name]`. | | NO_ELECTRONIC_PAYMENTS_ALLOWED | No Electronic Payments are allowed from this Supplier. | ### 4. Verify the link status was successfully updated. {#4-verify-the-link-status-was-successfully-updated} You should receive a 204 OK. Once the link status is updated with the `APPROVED` or `REJECTED` status, the Buyer Payment Agent is notified. ### 5. Click Next to proceed to deleting the status of the link request. {#5-click-next-to-proceed-to-deleting-the-status-of-the-link-request} An `APPROVED` link can be deleted if necessary. ## Delete an existing link {#delete-an-existing-link} As a Supplier Payment Agent, you can delete an existing link between trading partners. You can leverage this endpoint to remove a link between trading partners. Complete the steps to delete the link request. ### 1. Create the link delete request using the DELETE linking endpoint. {#1-create-the-link-delete-request-using-the-delete-linking-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. You can delete the link request by leveraging: API Reference: `DELETE /supplier-payment-agents/{ica}/supplier-payment-profiles/{spa_profile}/buyer-links/{bpa_profile}` Tip: You can only delete `APPROVED` links. If a link is rejected, it cannot be deleted. If a link is `PENDING` or has been `REJECTED`, it cannot be deleted. The Buyer Payment Agent is notified if the link is deleted. ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request-1} If a link update request is incorrect or invalid, the link is not deleted. If the failure is due to invalid information, you may receive one of the following error reason codes. | Error Code | Description | |----------------------------------|--------------------------------------------------------------------------------------------| | INVALID_LINK_BUYER_PROFILE_ID | Buyer Profile ID `[Buyer Profile]` is not associated with . | | INVALID_LINK_SUPPLIER_PROFILE_ID | Supplier Profile ID `[Supplier Profile]` is not associated with Supplier `[Buyer Profile]` | | LINK_REMOVAL_ERROR | Error in removing link for `[Buyer ID]` and `[Supplier ID]`. | | INVALID_LINK_REGISTRATION_ID | Enter a valid registration ID. | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | ### 3. Verify the link was successfully deleted. {#3-verify-the-link-was-successfully-deleted} You should receive a 204 OK. ### 4. Business Payment Service notifies both the Buyer Payment Agent and the Supplier Payment Agent with the LINK_REMOVED event notification. {#4-business-payment-service-notifies-both-the-buyer-payment-agent-and-the-supplier-payment-agent-with-the-link_removed-event-notification} An example event notification for this step looks like: * JSON ```JSON { "eventId": "someGUID", "eventType": "LINK_REMOVED", "eventCreatedDate": "datetime", "data": { "supplierProfileId": "matest.supplier1@track", "buyerProfileId": "matest.buyer1.pay@track" } } ``` ### 5. Click Next to proceed to retrieving existing links. {#5-click-next-to-proceed-to-retrieving-existing-links} Supplier Payment Agents can retrieve existing links between trading partners. ## Send locally stored payment preferences to a linked Buyer {#send-locally-stored-payment-preferences-to-a-linked-buyer} As a Supplier Payment Agent, you can send locally stored payment preferences directly to a Buyer Payment Agent if you have opted to store the payment preferences outside of Business Payment Service for Suppliers who have very custom payment preferences. This ensures that these strategic Suppliers' payment preferences can be managed and enforced by the Supplier Payment Agent with their own system and sent directly to the Buyer Payment Agent on behalf of their Suppliers at any time. Once a link is confirmed, a Supplier Payment Agent can send locally stored payment preferences at any time to the Buyer Payment Agent. This helps ensure that the Buyer Payment Agent always has the most current preferences. Complete the steps to send payment preferences directly to a linked Buyer Payment Agent. ### 1. Create the request. {#1-create-the-request} You can send locally stored payment preferences to a linked Buyer Payment Agent by leveraging: API Reference: `PUT /supplier-payment-agents/{ica}/supplier-payment-profiles/{spa_profile}/buyer-links/{bpa_profile}/payment-preferences` ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request-2} If the request is invalid or incorrect, you may receive one of the following error codes. If a Supplier payment preference exists in Business Payment Service between the Buyer profile and Supplier profile, then the locally stored payment preferences are not sent. | Error Code | Description | |------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MISSING_DECISION | Enter a valid decision. | | MISSING_PAYMENT_METHOD | Enter a payment Method. | | INVALID_CONTROLS_DECISION | Enter a valid control decision such as REJECT or WARNING. | | INVALID_PAYMENT_METHOD | Enter a valid payment method. Please use one of the following payment methods CARD, ACH, RTP, TRF. | | INVALID_MAX_INSTRUCTED_AMT | Enter a valid maximum instructed amount value. | | INVALID_MIN_INSTRUCTED_AMT | Enter a valid minimum instructed amount value. | | INSTRUCTED_MIN_GREATER_MAX | The minimum instructed amount value cannot be greater than or equal to the maximum instructed amount value | | 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. | | INVALID_CHARGES_PERCENTAGE_AMT | Enter a valid charges percentage amount. | | INVALID_CHARGES_FLAT_AMT | Enter a valid charges flat amount. | | MISSING_MAX_DAYS_AFTER_RELATED_DATE | Max days after related date is required with referred document type. | | MAX_DAYS_AFTER_RELATED_DATE | Enter a value less than 365 for Max Days After Related Date. | | INVALID_REFERRED_DOCUMENT_TYPE | Enter a valid referred document type. | | DUPLICATE_REFERRED_DOCUMENT_TYPE | Only one condition allowed for each referred document type. | | INVALID_CHARGES_CONDITION | Both charges percentage and charges flat amount cannot be used in the same control at the same time. | | INVALID_INCL_EXCL_CONTROL | Invalid control relationship. There cannot be both an include and exclude relationship setting on the same control. | | INVALID_ORGANISATION_IDENTIFICATION_TYPE | Enter a valid organisation identification type. | | MISSING_ORGANISATION_IDENTIFICATION | Organisation identification is required with organisation identification type. | | INVALID_ORGANISATION_BUYER_ID | Enter a valid organisation Track BPS Buyer ID. | | INVALID_LINK_SUPPLIER_ID | Enter a valid Supplier ID. | | INVALID_LINK_SUPPLIER_REGISTRATION_ID | Enter a valid Supplier registration Id. | | EXISTING_PAYMENT_PREFERENCES | Only one condition can be applied at a time. Mastercard Track Business Payment Service does not support additional payment preferences between the same the Supplier ID and Buyer ID in the system | | LINK_MISSING | There is no existing approved link between the Buyer ID and the Supplier ID. | ### 3. Verify the payment preferences were sent successfully. {#3-verify-the-payment-preferences-were-sent-successfully} You should receive a 204 OK. ### 4. Click Next to proceed to sending external payment preferences to linked Buyer Payment Agents. {#4-click-next-to-proceed-to-sending-external-payment-preferences-to-linked-buyer-payment-agents} Supplier Payment Agents can send payment preferences between trading partners. ## Retrieve an existing link {#retrieve-an-existing-link} As a Supplier Payment Agent, you can retrieve an existing link and statuses between trading partners. Complete the steps to retrieve the link request. ### 1. Retrieve link request using the GET linking endpoint. {#1-retrieve-link-request-using-the-get-linking-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. You can view existing links by leveraging: API Reference: `GET /supplier-payment-agents/{ica}/buyer-supplier-links` Tip: You can filter the search results using the available query parameters. Multiple query parameters can be added to the same request and will result in an "AND" style filter. ### 2. Review the possible error codes associated with this request. {#2-review-the-possible-error-codes-associated-with-this-request-3} If a link retrieve request is incorrect or invalid, the link is not retrieved. If the failure is due to invalid information, you may receive one of the following error reason codes. | Error Code | Description | |-----------------|---------------------------------------------------------------------------------------------| | INVALID_STATUS | Provider a valid status. Valid statuses for search are 'PENDING', 'APPROVED' and 'REJECTED' | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | | INVALID_LIMIT | Invalid limit. Enter a numeric value for limit that is 100 or less. | | INVALID_SORT_BY | Invalid sort field. | | INVALID_OFFSET | Invalid offset field. | ### 3. Verify the link was successfully retrieved. {#3-verify-the-link-was-successfully-retrieved} You should receive a 200 OK. ### 4. Continue to the Supplier payment preferences tutorial. {#4-continue-to-the-supplier-payment-preferences-tutorial} Once your Suppliers are registered with Business Payment Service, you should create the Supplier payment preferences. Review the tutorial [here](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials-and-guides/preferences-tutorial/index.md).