# PayPal Initiate billing agreement

The PayPal Reference Transactions API enables a customer and a merchant to enter a contract, or a *billing agreement*, based on *reference transactions*. A reference transaction is a financial transaction that you initiate through a billing agreement and from which you can derive subsequent payments.

The combination of billing agreements and reference transactions benefits customers and merchants.

Customers can make seamless on-demand or recurring payments for services or goods without needing to log in to the merchant site after agreement approval.

For example, customers can enter into agreements to:

* Make future payments for actual usage of utilities, such as gas or electricity
* Make future purchases on the merchant site without being on the merchant site
* Make recurring payments for a subscription service
* Pay a merchant in a marketplace on a regular basis

A customer can have multiple billing agreements. For example, the customer might establish separate agreements for different kinds of service.

Merchants can initiate recurring payments for varying amounts on varying schedules.

* Get consent to take funds from a customer's account at varying amounts and schedules
* Create a billing agreement that charges the customer's PayPal account for subsequent purchases
* Initiate a payment based on the billing agreement
* Leverage PayPal to protect the risks inherent in processing payments

For example, merchants can enter into agreements to:

{% hint style="info" %}
Token is for single use only, you can create only one billing agreement from one token.
{% endhint %}

## Required fields

* ppcUid - PayPal Payment Provider Contract UUID

## Optional fields

* description - Agreement description
* shippingAddress - Shipping Address details
  * country - The two-character ISO 3166-1 code that identifies the country or region
  * postalCode - The postal code, which is the zip code or equivalent
  * countrySubdivision - The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision
  * city - A city, town, or village
  * addressLine1 - The first line of the address
  * addressLine2 - The second line of the address
* enableAddressChange - Indicates whether to show the shipping address but prevent the customer from editing it
* collectShippingAddress - Indicates whether to skip the collection of the shipping address from the customer during the  agreement sign-up phase
* allowedCountries - An array of legally accepted customer country codes
* experienceId - The ID of the experience profile to apply during the agreement approval UI flow
* externalSelectedFundingInstrumentType - The type of financial instrument (FI) that the merchant wants to promote. CREDIT or PAY\_UPON\_INVOICE
* returnUrl - The URL where the customer is redirected after the customer approves the payment
* cancelUrl - The URL where the customer is redirected after the customer cancels the payment

**Request**\
\
Here is an example of request that can be used for creating a billing agreement token.

```bash
curl -v -X POST '<SERVER URL>/billingAgreement/initiate' \
-H 'Authorization: Bearer <Access-Token>' \
-H 'Content-Type: application/json' \
-d '{
    "paymentProviderContract": "<PPC ID>",
    "description": "Stored PayPal account with The Partner merchant",
    "returnUrl": "https://www.example.com/success",
    "cancelUrl": "https://www.example.com/failure"
}'
```

**Response**

The response for create billing agreement token will look like this:

```json
{
    "approvalUrl": "https://www.sandbox.paypal.com/agreements/approve?ba_token=BA-29L89918T33852108",
    "billingToken": "BA-29L89998T33851208"
}
```

## Response fields

* approvalUrl - The URL to which the customer needs to be redirected for approving the billing agreement token
* billingToken - The billing agreement token that would be used to create the billing agreement

## Customer Approval

You redirect the customer to the approval URL, where the customer can consent to the billing agreement and select a funding instrument. Then, the customer is redirected to the return URL that the merchant specified during billing agreement token creation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verifone.com/online-payments/advanced-payment-methods-apms/paypal/your-first-transaction-with-paypal/paypal-initiate-billing-agreement.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.