# Billing Agreement and Recurring Payments
source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md

With Checkout with PayPal or Pay with PayPal, you can set up a billing agreement for a payer. This allows you to initiate a reference transaction which is either subscription, recurring, or on-demand payments against this billing agreement without additional consent from the payer. The payer logs into PayPal once to consent to the agreement. After a billing agreement is approved, the payer need not log into PayPal to confirm subsequent payments.

## PayPal billing agreement flow with or without first time payment {#paypal-billing-agreement-flow-with-or-without-first-time-payment}

As a prerequisite, you need to contact PayPal to enable the ability to process billing agreements and reference transactions.
![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/billingAgreementPayPal.png)
The checkout flow is as follows:

1. A payer browses your shop site, selects a product and clicks **PayPal** at the checkout page.
2. When the payer clicks the **PayPal** button, you perform a Tokenize Browser Payment call to the Mastercard Gateway, and redirect the payer to the PayPal URL returned in the response. See [Initiating your Billing Agreement](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md#step-2-initiating-your-billing-agreement).
3. The Mastercard Gateway redirects the payer to the PayPal website to approve the agreement details.
4. The payer logs in to their PayPal account using the PayPal Login page.
5. The payer reviews the billing agreement details and confirms the details by clicking the "**Agree \& Continue** " or the "**Agree \& Pay**" button on the PayPal website.
6. PayPal redirects the payer to the Mastercard Gateway where a call is made to PayPal to execute the billing agreement. PayPal returns an agreement Id, which the Mastercard Gateway stores as a token together with the other agreement details. See [Retrieving Billing Agreement Details](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md#step-3-retrieve-billing-agreement-details).
7. The payer's browser is returned to your website where depending on the agreement confirmation, **Agree \& Pay** or **Agree \& Continue** , you will initiate a payment against the billing agreement at that time or on-demand in the future respectively. See [Initiating a Payment Against the Billing Agreement](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md#step-2-initiating-your-billing-agreement).

## Step 1: Create a Session {#step-1-create-a-session}

As a first step, create a session by submitting a Create Session request to the Mastercard Gateway from your web server. The operation returns a session ID that you can use to reference this session.
**Create Session API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#session)

## Step 2: Initiating your Billing Agreement {#step-2-initiating-your-billing-agreement}

Provide the following fields in the Tokenize Browser Payment request to initiate a billing agreement and to customize the payer experience presented by PayPal.

* **token** : The token that you wish to create or update. The agreement details are stored against this token.  
  You only need to provide this field if you are configured for the "Merchant Supplied" token generation strategy. Otherwise, the Mastercard Gateway creates the token for you.
* `sourceOfFunds.type` = PAYPAL
* `session.id`: The identifier for the payment session (returned in Step 1) that will be updated with the token containing the agreement details.
* `sourceOfFunds.provided.paypal.billingAgreement.description`: Your description for the PayPal billing agreement. This description is displayed to the payer when they are asked to approve the billing agreement.
* `sourceOfFunds.provided.paypal.billingAgreement.name`: Your name for the PayPal billing agreement.
* `sourceOfFunds.provided.paypal.billingAgreement.cardinality`: Indicates the number of billing agreements between you and this payer. You can set this to:
  * **MULTIPLE**: Indicates that you have multiple billing agreements with this payer. This means that a new agreement will be returned in response to each request.
  * **SINGLE**: Indicates that you have a single billing agreement with this payer. This means that the same agreement will be returned in response to each request.
* `browserPayment.returnUrl`: The URL to which you want the payer's browser to be redirected after approving the billing agreement at PayPal.
* `browserPayment.paypal.agreementConfirmation`: Indicates the action that PayPal displays to the payer prior to being redirected back to your website. You can set this to:
  * **AGREE**: This displays as "Agree \& Continue" on the PayPal website. This means that after the payer has approved the billing agreement and their browser has been returned to your website, you will not process a payment against this billing agreement at that time.
  * **AGREE_AND_PAY**: This displays as "Agree \& Pay" on the PayPal website. This means that after the payer has approved the billing agreement and their browser has been returned to your website, you will process a payment against this billing agreement.
* `browserPayment.paypal.displayShippingAddress`: Indicates whether you want PayPal to display the shipping address to the payer on the PayPal website. You can set this to "true" or "false".  
  By default, the shipping address is displayed to the payer. For more information, see [Display/Override Shipping Address](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#optional-displayoverride-shipping-address).
* `browserPayment.paypal.overrideShippingAddress`: Indicates whether you want to allow the payer to change the shipping address for the payment on the PayPal website. You can set this to "true" or "false".  
  By default, the payer is allowed to change the shipping address. For more information, see [Display/Override Shipping Address](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/paypal/index.md#optional-displayoverride-shipping-address).

After submitting this request, you must redirect the payer's browser to the URL returned in the browserPayment.redirectUrl field.
**Tokenize Browser Payment API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#tokenization) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#tokenization)

### Example Request and Response {#example-request-and-response}

Here is an example of a Tokenize Browser Payment request where the token has been generated using the "Merchant Supplied" token generation strategy.

| HTTP Method |                         URL                         |
|-------------|-----------------------------------------------------|
| POST        | {{host}}/api/rest/version/100/merchant/{merchantId} |

```json
{
   "apiOperation": "TOKENIZE_BROWSER_PAYMENT",
   "browserPayment": {
      "paypal": {
         "agreementConfirmation": "AGREE_AND_PAY",
         "displayShippingAddress": true,
         "overrideShippingAddress": false
      },
      "returnUrl": "https://<return_url>"
   },
   "correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
   "session": {
      "id": "SESSION0002567768179L82204264I7"
   },
   "shipping": {
      "address": {
         "city": "<city>",
         "country": "<country>",
         "postcodeZip": "<post_code>",
         "stateProvince": "<state>",
         "street": "test1",
         "street2": "test2"
      },
      "contact": {
         "firstName": "<merchant_first_name>",
         "lastName": "<merchant_last_name>"
      }
   },
   "sourceOfFunds": {
      "provided": {
         "paypal": {
            "billingAgreement": {
               "description": "Test Billing Agreement",
               "name": "Test Name",
               "cardinality": "MULTIPLE"
            }
         }
      },
      "type": "PAYPAL"
   },
   "token": "975890899756"
} 
```

```json
{
   "browserPayment": {
      "redirectUrl": "https://<redirect_url>"
   },
   "correlationId": "f4d8b752-4f68-47c6-81e7-2ee488f821a0",
   "merchant": "<test_merchant_Id>",
   "response": {
      "gatewayCode": "NO_VERIFICATION_PERFORMED"
   },
   "result": "SUCCESS",
   "session": {
      "id": "SESSION0002567768179L82204264I7"
   }
} 
```

### Retrieve session details {#retrieve-session-details}

The token, either Mastercard Gateway-generated or the one supplied by you in the Tokenize Browser Payment request, is stored in a payment session and returned in the Tokenize Browser Payment response.

If you are configured for Mastercard Gateway-generated tokens, submit a Retrieve Session request immediately using the session.id and obtain the value returned in the sourceOfFunds.token field. If the payer was unable to set up the billing agreement successfully, the token is not returned.

If you are configured for merchant-supplied tokens, go to [Step 3: Retrieve Billing Agreement Details](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/bill-agree-recc-pay/index.md#step-3-retrieve-billing-agreement-details).

### Example Retrieve Session Request {#example-retrieve-session-request}

Here is an example of a Retrieve Session request for a session Id obtained from the Tokenize Browser Payment response where the token has been generated by the Mastercard Gateway.

| HTTP Method |                                   URL                                   |
|-------------|-------------------------------------------------------------------------|
| GET         | {{host}}/api/rest/version/100/merchant/{merchantId}/session/{sessionId} |

### Example Retrieve Session Response {#example-retrieve-session-response}

```json
{
   "merchant": "<test_merchant>",
   "session": {
      "id": "SESSION0002567768179L82204264I7",
      "updateStatus": "SUCCESS",
      "version": "82cbc9f602"
   },
   "sourceOfFunds": {
      "token": "975890899756"
   },
   "version": "72"
}
```

### Customizing your billing agreement at PayPal {#customizing-your-billing-agreement-at-paypal}

To further customize the payer experience at PayPal, you can provide additional parameters when setting up the agreement at PayPal.

* Agreement Name
* Agreement Description
* Merchant Custom Data: Merchant-specific agreement data.
* Skip Shipping Address: If set to true, the shipping address is not collected from the payer during the agreement approval.
* Immutable Shipping Address: If set to true, the shipping address will be displayed but not editable.
* Include Shipping Address: Allow the payer to provide a shipping address if it is different from the default address. Warning: Ensure that the shipping address fields in the Tokenize Browser Payment request and the PayPal Billing Agreement configuration are set to create the desired payer experience during the billing agreement approval.

## Step 3: Retrieve Billing Agreement Details {#step-3-retrieve-billing-agreement-details}

Before proceeding with a payment against the billing agreement, you must check if the token containing the agreement details is valid. This is because the payer may choose to cancel the billing agreement on the PayPal website, in which case the token status will become invalid. Proceeding with a payment using an invalid token will cause the transaction to fail.

When the payer has returned to the page specified by the browserPayment.returnUrl, you can submit a Retrieve Token request. Provide the token Id to retrieve the billing agreement details. The following details are returned if the payer successfully signed up for the billing agreement. Otherwise, the "token not found" error is returned.

* `sourceOfFunds.provided.paypal.billingAgreement.cardinality`
* `sourceOfFunds.provided.paypal.billingAgreement.description`
* `sourceOfFunds.provided.paypal.billingAgreement.id`
* `sourceOfFunds.provided.paypal.billingAgreement.name`
* `sourceOfFunds.provided.paypal.payerId`
* `sourceOfFunds.provided.paypal.accountEmail`
* `sourceOfFunds.provided.paypal.accountHolder`

### Example Retrieve Token Request {#example-retrieve-token-request}

Here is an example of a Retrieve Token request for a token Id obtained from the Retrieve Session response or as supplied by you in the Tokenize Browser Payment request.

| HTTP Method |                                 URL                                 |
|-------------|---------------------------------------------------------------------|
| GET         | {{host}}/api/rest/version/100/merchant/{merchantId}/token/{tokenId} |

### Example Retrieve Token Response {#example-retrieve-token-response}

```json
{
   "repositoryId": "TEST8108F6CF-6899-42",
   "result": "SUCCESS",
   "shipping": {
      "address": {
         "city": "<city>",
         "country": "<country>",
         "postcodeZip": "<pos_code>",
         "stateProvince": "<state>",
         "street": "test1",
         "street2": "test2"
      },
      "contact": {
         "firstName": "<merchant_first_name>",
         "lastName": "<merchant_last_name>"
      }
   },
   "sourceOfFunds": {
      "provided": {
         "paypal": {
            "accountEmail": "test@test.com",
            "accountHolder": "FirtName LastName",
            "billingAgreement": {
               "cardinality": "MULTIPLE",
               "description": "Test Billing Agreement",
               "id": "B-NGxIf31554266975867",
               "name": "Test Name"
            },
            "payerId": "K4ZK9KRAXRVNA"
         }
      },
      "type": "PAYPAL"
   },
   "status": "VALID",
   "token": "975890899756",
   "usage": {
      "lastUpdated": "2019-04-03T04:49:48.029Z",
      "lastUpdatedBy": "<test_merchant>",
      "lastUsed": "2019-04-03T04:49:48.029Z"
   },
   "verificationStrategy": "NONE"
}
```

## Step 4: Initiating a Payment Against the Billing Agreement {#step-4-initiating-a-payment-against-the-billing-agreement}

If the billing agreement is approved and valid, you must initiate a payment immediately against the billing agreement if you set `browserPayment.paypal.agreementConfirmation`=**AGREE_AND_PAY** in the Tokenize Browser Payment request.

Provide the following fields in a Pay request in addition to the standard fields:

* `sourceOfFunds.type` = PAYPAL
* `sourceOfFunds.token`: Provide the token Id that identifies the billing agreement details (as received from PayPal) on the Mastercard Gateway. You can use this token Id for one-time and recurring payments.

You can view the billing agreement details for an Authorize or Pay transaction by performing a Retrieve Transaction operation or through Merchant Administration.

### Example Pay Request {#example-pay-request}

Here is an example Pay transaction request using the token that identifies the billing agreement details with PayPal.

| HTTP Method |                                               URL                                               |
|-------------|-------------------------------------------------------------------------------------------------|
| PUT         | {{host}}/api/rest/version/100/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |

```json
{
   "apiOperation": "PAY",
   "order": {
      "amount": "123.46",
      "currency": "USD",
      "description": "Quantity description",
      "item": [
         {
            "name": "name",
            "quantity": "40",
            "sku": "sku",
            "unitPrice": "2.8"
         }
      ],
      "itemAmount": "112.00",
      "tax": [
         {
            "amount": "0.29",
            "rate": "9.77"
         }
      ],
      "taxAmount": "11.46"
   },
   "shipping": {
      "address": {
         "city": "<city>",
         "country": "<country>",
         "postcodeZip": "<pos_code>",
         "stateProvince": "<state>",
         "street": "test1",
         "street2": "test2"
      },
      "contact": {
         "email": "test@test.com",
         "firstName": "FirstName"
      }
   },
   "sourceOfFunds": {
      "token": "975890899756"
   }
}
```