# Linking source: https://developer.mastercard.com/mastercard-buyer-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. An approved link request establishes the Buyer as a customer of the Supplier and enables them to pay the Supplier with Business Payment Service. Buyer Payment Agents can initiate a link between trading partners. In some cases, the Supplier Payment Agent may nudge the Buyer Payment Agent to initiate a link request. Agents will typically complete linking activities after they have used the Mastercard Track Search endpoints to lookup Supplier data. Buyer Payment Agents can retrieve Supplier payment preferences across all Supplier payment profiles or specific Supplier payment profiles to determine payment acceptance of a given Supplier. Display options of Supplier Payment Preferences are enabled by the Supplier Payment Agent. If a Supplier Payment Agent does not enable display options for Supplier Payment Preferences, then a link request is required. Buyer specific preferences will not be openly returned without a link request. > > #### 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. ### Step 1 - Optional - receiving a link nudge {#step-1---optional---receiving-a-link-nudge} A Supplier Payment Agent can nudge a Buyer Payment Agent to initiate a linking request. If a Supplier Payment Agent nudges a Buyer Payment Agent, the Buyer Payment Agent receives the SUPPLIER_SUGGESTING_LINK_REQUEST event notification, which includes the Supplier's information. An example event notification for this scenario looks like: * JSON ```JSON { "eventId": "someGUID", "eventType": "SUPPLIER_SUGGESTING_LINK_REQUEST", "eventCreatedDate": "datetime", "data": { "buyer": { "dba": "Buyer Co.", "id": "7b8bfb09-3fdc-4cd1-b768-477757fec6be", "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 Name", "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" ] } ] }, "supplier": { "dba": "Supplier Co.", "id": "7b8bfb09-3fdc-4cd1-7777-477757fae6rf", "isActive": true, "legalBusinessAddress": { "addressLine1": "2200 Mastercard Blvd.", "addressLine2": "North Building", "addressLine3": "Suite 1000", "country": "US", "countrySubDivision": "MO", "postCode": "63368", "townName": "O'Fallon" }, "legalBusinessName": "Supplier Company Name", "organisationIdentifications": [ { "identification": "998765432", "type": "TXID" } ] } } } ``` To respond to the nudge, you can initiate a linking request by using the POST linking call. However, the Buyer Payment Agent can initiate a linking request without a nudge from the Supplier Payment Agent. #### Click Next to initiate a linking request. {#click-next-to-initiate-a-linking-request} ## Initiate a link request {#initiate-a-link-request} As a Buyer Payment Agent, you can initiate a link between your Buyer and their Suppliers. You can leverage this endpoint to create a link request between trading partners. Complete the steps to initiate a link. ### 1. Use the GET registration endpoint to retrieve the Buyer registration ID for your Buyer. {#1-use-the-get-registration-endpoint-to-retrieve-the-buyer-registration-id-for-your-buyer} If you do not already have the Buyer registration ID, you can query the following registration endpoint using **filters** and find the Buyer registration ID in the response body. Note: With the April 2023 release, the previously required `supplierRegistrationId` field is now optional. API Reference: `GET /buyer-payment-agents/{ica}/buyers` Tip: Use filters in your query to return only the record for your specific Buyer. Otherwise, you will return a list of all Buyer registrations. The Buyer registration ID is the value of the `id` key for your Buyer in the response body. ### 2. Create the link initiation request using the POST linking endpoint. {#2-create-the-link-initiation-request-using-the-post-linking-endpoint} Note: With the February 2022 release, Buyer Payment Agents can include the `annualExpectedSpend` object in the linking request. You can initiate links by leveraging: API Reference: `POST /buyer-payment-agents/{ica}/buyer-payment-profiles/{bpa_profile}/supplier-links` Tip: You must include an invoice number in the request body. To do so, the request should include values for these fields: "referenceData": { "referredDocumentInformation": \[ { "type": "CINV", "number": "20001", } Additional information that can be added to `type` and `number` are purchase order and credit notes, however, these data types are optional. You **must** include a `number` value for CINV (commercial invoice number) in the request body. An example of the request body with multiple document types looks like: * JSON ```JSON { "supplierRegistrationId": "someSupplierRegistrationGUID", "referenceData": { "customerAccount": [ { "customerNumber": "someCustomerIdProvidedByAgent", //Optional (Remove Customer Number from "Reference Data) "referredDocumentInformation": [ { "type": "CINV", "number": "123", "relatedDate": "2020-09-01" } ], "netTerms": [ //Optional { "netDays": 10, //Required if entry is provided. Non-Negative number "discount": "2%" //Optional. String with number being >=0 & < 100 and a % sign }, { "netDays": 30, "discount": "0%" } ] }, { "customerNumber": "someCustomerIdProvidedByAgent1", "referredDocumentInformation": [ { "type": "PUOR", "number": "123", "relatedDate": "2020-09-01" } ] } ], "annualExpectedSpend": { "volume": 1000000, "currency": "USD" } }, "requestedSupplierProfileId": "someSupplier@track", "phoneNumber": "somePhoneNumber", "emailAddress": "some@email.com" } ``` ### 3. Review the possible error codes associated with this request. {#3-review-the-possible-error-codes-associated-with-this-request} If a link initiation request is incorrect or invalid, the link request 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_BUYER_ID | Enter a valid Buyer ID. | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | | INVALID_ICA | Enter a valid ICA number. | | INVALID_BUYER_REGISTRATION_ID | Enter a valid Buyer registration id. is either not valid or is not associated to your profile. | | INACTIVE_LINK_BUYER_ID | Submit the request with a different Buyer payment profile ID. The Buyer payment profile ID used in the request in inactive. | | NO_REGISTRATION_ID | Enter a valid registration Id. Registration Id is missing. | | INVALID_LINK_REGISTRATION_ID | Enter a valid registration Id. | | NO_SUPPLIER_ID | Enter a valid Supplier Id. Supplier Id is missing. | | INVALID_LINK_SUPPLIER_ID | Enter a valid Supplier Id. | | NO_INVOICE_NUMBER | Enter a valid invoice number. Invoice number is required. | | INVALID_LINK_CUSTOMER_NUMBER | Enter a valid customer number. | | INVALID_LINK_PHONE_NUMBER | Enter valid phone number with 255 characters or less. | | INVALID_LINK_EMAIL_ADDRESS | Enter a valid email address. Ensure the format includes \[username\]@\[domain\].com. | | INVALID_REFERRED_DOCUMENT_TYPE | Enter a value for Type. Valid Values include CINV (Customer Invoice), CREN (Credit Notes) or PUOR (Purchase Order Number). | | NO_REFERRED_DOCUMENT_TYPE | Enter a value for Type. Valid Values include CINV (Customer Invoice), CREN (Credit Notes) or PUOR (Purchase Order Number). | | INVALID_LINK_REFERRED_DOCUMENT_NUMBER | Enter a referred document number with 255 characters or less. | | NO_LINK_REFERRED_DOCUMENT_NUMBER | A referred document number is required to request a link. Resubmit the request with a value for referredDocumentNumber. | ### 4. Verify the link initiation was successful. {#4-verify-the-link-initiation-was-successful} You should receive a 201 OK. ### 5. Supplier Payment Agent approves or rejects the linking request and the Buyer Payment Agent is notified of approval status. {#5-supplier-payment-agent-approves-or-rejects-the-linking-request-and-the-buyer-payment-agent-is-notified-of-approval-status} #### Linking approval event notification {#linking-approval-event-notification} Note: You may receive multiple LINK_APPROVED event notifications for multiple Supplier IDs. If the Supplier Payment Agent approves the linking request, you will receive the LINK_APPROVED and SUPPLIER_CONTROLS event notifications. An example of these notifications are: * JSON ```JSON { "eventId": "someGUID", "eventType": "LINK_APPROVED", "eventCreatedDate": "datetime", "data": { "status": "APPROVED", "linkedBuyer": { "buyerProfileId": "someBuyer.pay@track", "buyerRegistrationId": "someGUID" }, "linkedSupplier": { "supplierProfileId": "someSupplier@track", "supplierRegistrationId": "someGUID" } } } ``` #### Linking approval event notification with Supplier payment preferences {#linking-approval-event-notification-with-supplier-payment-preferences} In addition to receiving the LINK_APPROVED event notification, you will also receive the Supplier's payment preferences, if they have any registered with Business Payment Service. Supplier payment preferences let Buyer Payment Agents know how and when the Supplier prefer to be paid. * JSON ```JSON { "eventId": "someGUID", "eventType": "SUPPLIER_CONTROLS", "eventCreatedDate": "datetime", "data": { "supplierId": "someSupplier@track", "buyerId": "someBuyer.pay@track", "paymentPreferences": [ { "conditions": { "chargesInformation": { "percentageAmount": "2.5" }, "instructedAmount": { "max": "5000.2", }, "referredDocumentInformation": [ { "time": { "maxDaysAfterRelatedDate": "10" }, "type": "CINV" } ] }, "decision": "REJECT", "paymentMethod": "CARD" } ] } } ``` ##### Supplier payment preferences {#supplier-payment-preferences} Buyer Payment Agents must ensure they are compliant with the Supplier's payment preferences. Suppliers can implement the following types of preferences: * **Time preferences:** limits the duration of payment acceptance between a Buyer and their Supplier. * **Relationship preferences:** restricts which Buyers can pay each Supplier. * **Amount preferences:** restricts the payment based on total amount of a payment instruction. * **Fee preferences:** requests an additional fee when making a payment. You must code to the following fields: | Field | Description | Valid values | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|------------------| | `conditions` | The object containing the Supplier's preference criteria. | N/A | | decision | The desired outcome when a payment instruction violates a Supplier's payment control. | WARNING REJECT | | paymentMethod | The payment rail applicable for the control. The control can be set against any payment method supported by the agent and Supplier. | CARD ACH RTP TRF | | `chargesInformation` | The object containing fee conditions. You can use either `percentageAmount` or `flatAmount`, however you cannot use both in the same request body. | N/A | | percentageAmount | A percentage fee amount applied to the payment instruction. | 2.5 | | flatAmount | A flat fee amount applied to the payment instruction. | 10 | | `instructedAmount` | The object containing payment amount conditions. | N/A | | min | Minimum amount allowed for the payment instruction. | 200.5 | | max | Maximum amount allowed for the payment instruction. | 5000.2 | | `referredDocumentInformation` | The object containing time conditions. | N/A | | `time` | The object containing the numeric value for time related preferences. | N/A | | maxDaysAfterRelatedDate | Calendar Days in UTC that a payment instruction is accepted after the related date. | 10 | | type | Specifies the type of referred document (ex. CINV - Commercial Invoice) | CINV PUOR CREN | #### Linking rejection event notification {#linking-rejection-event-notification} If the Supplier Payment Agent rejects the request, you will receive the LINK_REJECTED event notification. An example of this notification looks like: * JSON ```JSON { "eventId": "someGUID", "eventType": "LINK_REJECTED", "eventCreatedDate": "datetime", "data": { "supplierRegistrationId": "someSupplierGUID", "buyerProfileId": "matest.supplier1@track", "rejectReasonCode": "NO_BUYER_RECORD|NO_SUPPLIER_RECORD|WRONG_TRADING_PARTNER|NO_ELECTRONIC_PAYMENTS_ALLOWED", "rejectReasonMessage": "" } } ``` #### Codes and messages {#codes-and-messages} If the link is rejected, you will receive a reason code with the rejection. | Reason Code | Description | |--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | NO_BUYER_RECORD | The link request for `[Buyer Name]` and `[Supplier Name]` was rejected by the Supplier Payment Agent because there is no record of `[Buyer Name]` associated with the Supplier Payment Agent in their system. | | NO_SUPPLIER_RECORD | The link request for `[Buyer Name]` and `[Supplier Name]` was rejected by the Supplier Payment Agent because there is no record of `[Supplier Name]` associated with the Supplier Payment Agent in their system. | | WRONG_TRADING_PARTNER | The link request for `[Buyer Name]` was rejected by `[Supplier Name]` because the Supplier does not do business with `[Buyer Name]`. | | NO_ELECTRONIC_PAYMENTS_ALLOWED | This Supplier does not accept electronic payments from this Buyer. | | BUYER_NOT_ALLOWED | This Supplier does not accept payments from this Buyer. | #### Click Next to proceed to deleting a link request. {#click-next-to-proceed-to-deleting-a-link-request} ## Delete an existing link {#delete-an-existing-link} As a Buyer Payment Agent, you can delete an existing link between trading partners. You can leverage this endpoint to remove link between trading partners. Complete the steps to delete the link request. ### 1. Delete a link using the DELETE linking endpoint. {#1-delete-a-link-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 /buyer-payment-agents/{ica}/buyer-payment-profiles/{bpa_profile}/supplier-links/{spa_profile}` Tip: You can only delete `APPROVED` links. 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} 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" } } ``` #### Click Next to proceed to retrieving existing links. {#click-next-to-proceed-to-retrieving-existing-links} Buyer Payment Agents can retrieve existing links between trading partners. ## Retrieve an existing link {#retrieve-an-existing-link} As a Buyer 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 /buyer-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-1} 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. ## Get all payment preferences for Supplier {#get-all-payment-preferences-for-supplier} This end point will allow the return of payment preferences across all of a Supplier's payment profiles. Complete the steps to retrieve the Supplier payment preferences. ### 1. Retrieve Supplier payment preferences using the GET linking endpoint. {#1-retrieve-supplier-payment-preferences-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 Supplier payment preferences by leveraging: API Reference: `GET /buyer-payment-agents/{ica}/payment-profiles/{bpa_profile}/suppliers/{spa_reg}/payment-preferences` 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-2} 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 | |--------------|-------------------------------------------------------------------------------------------| | ID_NOT_FOUND | The ID included in the request was not found | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | ### 3. Verify the Supplier payment preferences were successfully retrieved. {#3-verify-the-supplier-payment-preferences-were-successfully-retrieved} You should receive a 200 OK. ## Get payment preference for Supplier Profile {#get-payment-preference-for-supplier-profile} This end point will allow the return of payment preferences for only a specified Supplier payment profile. Complete the steps to retrieve the Supplier profile payment preferences. ### 1. Retrieve Supplier profile payment preferences using the GET linking endpoint. {#1-retrieve-supplier-profile-payment-preferences-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 Supplier profile payment preferences by leveraging: API Reference: `GET /buyer-payment-agents/{ica}/payment-profiles/{bpa_profile}/suppliers/{spa_reg}/payment-profiles/{spa_profile}/payment-preferences` 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 | |--------------|-------------------------------------------------------------------------------------------| | ID_NOT_FOUND | The ID included in the request was not found | | INVALID_AUTH | Invalid authorization. Please correct your access credentials to Track BPS and try again. | ### 3. Verify the Supplier profile payment preferences were successfully retrieved. {#3-verify-the-supplier-profile-payment-preferences-were-successfully-retrieved} You should receive a 200 OK.