# Agreement Management
source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/use-cases/agreement-management/index.md

## Overview {#overview}

The agreement management use case enables the debtor service provider to carry out three key operations. The debtor service provider can:  

* Enable the debtor to link their account to the creditor and store the payment information for future purchases; enable the setup of recurring payments based on frequency, duration, and amount for subscription-based payments.  
* Enable the debtor to view and delete linked accounts from their mobile banking app.  
* Enable the debtor to log in to the mobile banking app and view and update their linked accounts.  

In order to link the debtor account to the creditor, the following link agreement types are used:  

* **Account on File (AOF)** - The debtor links their account to the creditor for the purpose of making an immediate linked payment the next time they check out with the same creditor. Subsequent linked payments happen when the debtor is in session. Example: E-commerce online checkout   
* **Merchant Requested Transaction (MRT)** - The debtor links their account to the merchant for the purpose of making a linked transaction after they have left the creditor domain. A debtor is able to link an account to a creditor based on an agreement. The individual transaction is authorized by the debtor each time with the creditor, but the subsequent linked payment happens when the debtor is not in session.  
  Example: Grocery shopping   
* **Merchant Initiated Transaction (MIT)** - This is for traditional recurring subscription payments. A consumer is able to link an account to a merchant based on an agreement. Subsequent linked payments happen when the debtor is not in session.   
  Example: Streaming service payment  

## Link Debtor Account to Creditor {#link-debtor-account-to-creditor}

The link debtor account service allows the debtor to link their account to creditor and store payment information for future purchases.   

The link debtor account to creditor has two journeys:   

**Single Device** : The debtor completes the user journey on a single mobile device, where the debtor is redirected to their bank app using the universal link.   

**Two Devices**: The debtor completes the user journey with two devices. The creditor page displays a 6-digit numeric Link Reference Number, which the debtor enters in the Account to Account Commerce section of their bank app to complete the journey.

### Link Debtor Account- Single Device {#link-debtor-account--single-device}

Diagram link-account-single-device

The following are the execution steps:  

1. The debtor requests the creditor to link their account, and the creditor forwards the request to the creditor service provider.  
2. The creditor service provider initiates a create link request to Mastercard.  
3. Mastercard validates the request for data format, a duplicate link, and other business rules. Upon successful validation, Mastercard generates an agreementLifecycleId, agreementId and responds to the creditor service provider.  
4. The creditor service provider uses the merchant library to fetch the universal link of all the debtor service providers onboarded to account to account commerce platform and presents the list to the debtor. The debtor chooses their debtor service provider, and the creditor redirects the debtor to its debtor service provider's mobile app/website.  
5. The debtor authenticates in the app, and the debtor service provider captures the agreementLifecycleId.  
6. The debtor service provider sends a retrieve link request to Mastercard by calling the `/agreement-retrievals` endpoint.  
7. Mastercard sends all the link details to the debtor service provider.  
8. The debtor service provider validates the link request and presents it to the debtor for approval.  
9. The debtor responds to the link request.  
10. The debtor service provider sends a confirm link request to Mastercard by calling `/agreements/{agreement_id}/updates` endpoint.  
11. Mastercard sends a confirm link response to the debtor service provider.  
12. Mastercard sends a confirm link outbound notification to the creditor service provider.  
13. The creditor service provider responds to the confirm link.  
14. The creditor service provider updates the web/app interface.   
15. The debtor service provider redirects the debtor to the creditor's web/app.   

### Link Debtor Account- Two Device {#link-debtor-account--two-device}

Diagram link-account-two-device

The following are the execution steps:  

1. The debtor requests the creditor to link their account, and the creditor forwards the request to the creditor service provider.  
2. The creditor service provider initiates a create link request to Mastercard.  
3. Mastercard validates the request for data format, a duplicate link, and other business rules. Upon successful validation, Mastercard generates an agreementLifecycleId, agreementReferenceNumber and responds to the creditor service provider.  
4. The creditor service provider displays the reference number for the debtor to authenticate from a different device.  
5. The debtor manually opens the debtor service provider app and authenticates.   
6. The debtor enters the reference number to confirm the link.  
7. The debtor service provider receives the request and sends the retrieve link request by calling the `/agreement-retrievals` endpoint to Mastercard.  
8. Mastercard sends all the link details to the debtor service provider.  
9. The debtor service provider validates the link request and presents the link request consent to the debtor.  
10. The debtor reviews and responds to the link request.  
11. The debtor service provider validates the link request and sends a confirm link request to Mastercard by calling `/agreements/{agreement_id}/updates` endpoint.  
12. Mastercard send a confirm link response to the debtor service provider.  
13. Mastercard sends a confirm link outbound notification to the creditor service provider.  
14. The creditor service provider responds to the confirm link.  
15. The creditor service provider updates the web/app interface.   
16. The Debtor is redirected to Creditor web/app interface.   

## Delete Debtor Linked Accounts {#delete-debtor-linked-accounts}

The delete debtor linked account service allows debtors to delete their linked account with a creditor. This can be done from the mobile banking app of the debtor service provider.

Diagram delete-agreement

The following are the execution steps:  

1. The debtor logs in to the debtor service provider's mobile app.  
2. The debtor navigates to the linked account menu, and the debtor service provider displays the list of linked accounts. If the debtor service provider hasn't stored the list of agreements linked to the debtor, it can initiate the agreement list retrieval API by calling the `/agreement-searches` endpoint. The debtor selects the creditor agreement to delete.  
3. The debtor service provider initiates a delete agreement to Mastercard by calling the `/agreements/{agreement_id}/updates` endpoint.  
4. Mastercard inactivates the agreement and responds to the debtor service provider.  
5. The debtor service provider sends the updated creditor agreement list to the debtor.  
6. Mastercard initiates a delete agreement outbound notification to the creditor service provider.  
7. The creditor service provider and the creditor delete the linked account of the debtor.  
8. The creditor service provider informs the creditor to update the debtor's linked accounts.  

## Update Linked Debtor Accounts {#update-linked-debtor-accounts}

The update linked debtor account service allows the debtor to view their linked debtor account and update any parameters when needed. Mastercard only allows the update of the agreement account nickname in this service.

Diagram update-linked-accounts

The following are the execution steps:  

1. The debtor logs in to the debtor service provider's mobile app.  
2. The debtor navigates to the linked account menu, and the debtor service provider displays the list of linked accounts. If the debtor service provider hasn't stored the list of agreements linked to the debtor, it can initiate the agreement list retrieval API by calling `/agreement-searches` endpoint. The debtor selects the creditor agreement and updates the nickname.  
3. The debtor service provider initiates the update agreement to Mastercard by calling the `/agreements/{agreement_id}/updates` endpoint.  
4. Mastercard acknowledges and responds to the debtor service provider.  
5. The debtor service provider sends the updated creditor agreement list to the debtor.  
6. Mastercard initiates the update agreement outbound notification to the creditor service provider.  
7. The creditor service provider and the creditor update the linked account of the debtor.  
8. The creditor service provider responds with a successful update response.  

## Additional Information {#additional-information}

1. Look at the [API Reference](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-reference/index.md) for information on how to implement this use case.  
2. Look at the [Codes and Formats](https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/code-and-formats/index.md) for acknowledgement responses.