Billing Agreement and Recurring Payments

Using Checkout with PayPal or Pay with PayPal, you can set up a billing agreement for a payer, which allows you to initiate a reference transaction (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/Without First Time Payment

As a prerequisite, you need to contact PayPal to enable the ability to process billing agreements and reference transactions.

Billing Agreement with PayPal Workflow

The checkout flow is as follows:

A payer browses your shop site, selects a product and clicks PayPal at the checkout page.
When the payer clicks the PayPal button, you perform a Tokenize Browser Payment call to the gateway, and redirect the payer to the PayPal URL returned in the response. See Initiating your Billing Agreement.
The gateway redirects the payer to the PayPal website to approve the agreement details.
The payer logs in to their PayPal account using the PayPal Login page.
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.
PayPal redirects the payer to the gateway where a call is made to PayPal to execute the billing agreement. PayPal returns an agreement Id, which the gateway stores as a token together with the other agreement details. See Retrieving Billing Agreement Details.
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.

Step 1: Create a Session

As a first step, create a session by submitting a Create Session request to the gateway from your web server. The operation returns a session ID that you can use to reference this session.

Create Session API Reference[REST][NVP]

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 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 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 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.
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.

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][NVP]

Example Request

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

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}
HTTP Method	POST

{
   "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"
}

Example Response

{
   "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

The token, either 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 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.

Example Retrieve Session Request

Here's 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 gateway.

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/{sessionId}
HTTP Method	GET

Example Retrieve Session Response

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

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: You must allow the payer to provide a shipping address if it's different from the default address.

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

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. You must 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

Here's 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.

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/token/{tokenId}
HTTP Method	GET

Example Retrieve Token Response

{
   "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

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 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 via Merchant Administration.

Example Pay Request

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

URL	https://na.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method	PUT

{
   "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"
   }
}