Reference Transactions Integration Guide

DocsLast updated: June 21st 2023, @ 2:28:18 pm

Use the PayPal Reference Transactions API to create and manage billing agreement tokens and billing agreements. You can use a reference transaction to make a payment.

Important: The PayPal Reference Transactions API is available on a limited use basis to select merchants for approved use cases. For more information, reach out to your PayPal account manager.

Note: When you initiate a reference transaction, PayPal recommends that you use a billing agreement ID to avoid confusion. You pass the ID of the billing agreement in the JSON request body of a v2/orders call.

Warning: To continue providing a Pay Later option at checkout, it is essential that you integrate Billing With Purchase. This solution offers the same functionalities as Billing Agreement and is compatible with your existing payment options.

Overview

The PayPal Reference Transactions API enables a customer and merchant to enter into 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, merchants, and partners:

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.
For example, merchants can enter into agreements to:
- 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.
Partners can enter into an agreement with merchants on the platform to charge merchant fees on demand in varying amounts.

A billing agreement can be merchant-initiated or channel-initiated:

Billing agreement type	Description
Merchant-initiated agreement (MIB)	A basic agreement between a merchant and a customer. The merchant initiates the agreement, the customer signs the agreement with the merchant, and the same merchant processes and receives the payment.
Channel-initiated agreement (CIB)	An agreement between a customer and a channel. The customer grants a channel permission to process third-party payments, or reference transactions. This eliminates the need for the customer to sign a separate billing agreement with each third-party merchant. The channel decides when and by which third-party merchant payments are processed.

Billing agreement type

Description

Merchant-initiated agreement (MIB)

A basic agreement between a merchant and a customer.

The merchant initiates the agreement, the customer signs the agreement with the merchant, and the same merchant processes and receives the payment.

Channel-initiated agreement (CIB)

An agreement between a customer and a channel.

The customer grants a channel permission to process third-party payments, or reference transactions. This eliminates the need for the customer to sign a separate billing agreement with each third-party merchant.

The channel decides when and by which third-party merchant payments are processed.

Note: To enable different types of billing agreements based on your needs, contact your PayPal account manager.

1. Set up your development environment

Before you can integrate Reference Transactions, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Reference Transactions.

2. Create billing agreement token

To create a billing agreement token, pass the agreement details including the description, payer, and billing plan in the JSON request body.

Set the payment_method parameter in the payer object to PAYPAL.

This call returns an approval URL, where the payer is redirected. The payer logs in to PayPal one time to approve the agreement and select a funding instrument. After that, the payer doesn't need to log in again. If the payer approves the agreement, they are redirected to the return URL specified during billing agreement token creation.

For example:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing-agreements/agreement-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -d '{
  "description": "Billing Agreement",
  "shipping_address":
  {
    "line1": "123 Main St.",
    "line2": "Suite #4",
    "city": "New York",
    "state": "NY",
    "postal_code": "12345",
    "country_code": "US",
    "recipient_name": "John Doe"
  },
  "payer":
  {
    "payment_method": "PAYPAL"
  },
  "plan":
  {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences":
    {
      "return_url": "https://example.com/return",
      "cancel_url": "https://example.com/cancel",
      "notify_url": "https://example.com/notify",
      "accepted_pymt_type": "INSTANT",
      "skip_shipping_address": false,
      "immutable_shipping_address": true
    }
  }
}'

If your request for a billing agreement with PayPal payment method succeeds, the API returns the HTTP 201 Created status code and a JSON response that includes an approval URL:

{
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/agreements/approve?ba_token=BA-8A802366G0648845Y",
    "rel": "approval_url",
    "method": "POST"
  },
  {
    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/BA-8A802366G0648845Y/agreements",
    "rel": "self",
    "method": "POST"
  }],
  "token_id": "BA-8A802366G0648845Y"
}

Redirect the payer to the approval URL, where the payer can consent to the billing agreement and select a funding instrument. Then, redirect the payer to the return URL specified during billing agreement token creation.

3. Create billing agreement

After payer approval, use a billing agreement token to create the agreement.

Include the token in the URI:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -d '{
  "token_id": "BA-8A802366G0648845Y"
}'

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the billing agreement ID, the state of the agreement, which is ACTIVE, and information about the payer:

{
  "id": "B-50V812176H0783741",
  "state": "ACTIVE",
  "description": "Billing Agreement",
  "payer":
  {
    "payer_info":
    {
      "email": "doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "ZU7HZ76P4VL5U"
    }
  },
  "plan":
  {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences":
    {
      "notify_url": "https://example.com/notify",
      "accepted_pymt_type": "INSTANT"
    }
  },
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741/cancel",
    "rel": "cancel",
    "method": "POST"
  },
  {
    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741",
    "rel": "self",
    "method": "GET"
  }],
  "merchant":
  {
    "payee_info":
    {
      "email": "merchant@example.com"
    }
  },
  "create_time": "2023-08-08T07:19:28.000Z",
  "update_time": "2023-08-08T07:19:28.000Z"
}

Save the id value, which is the billing agreement ID.

Next, use the reference transaction to make a payment.

4. Use a reference transaction to make a payment

To use a reference transaction to make a payment, pass the ID of the billing agreement in the JSON request body of a /v2/checkout/orders call:

curl - v - X POST https: //api-m.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json"\ - H "Authorization: Bearer ACCESS-TOKEN"\ - d '{
"intent": "CAPTURE", "purchase_units": [{
  "amount": {
    "currency_code": "EUR",
    "value": "0.01"
  }
}], "payment_source": {
  "token": {
    "id": "B-50V812176H0783741",
    "type": "BILLING_AGREEMENT"
  }
}
}

A successful request returns a JSON response body that shows payment details:

{
  "id": "5AT627990P285181E",
  "status": "COMPLETED",
  "purchase_units": [{
    "reference_id": "default",
    "payments": {
      "authorizations": [{
        "status": "CREATED",
        "id": "6MS02512BP527144J",
        "amount": {
          "currency_code": "EUR",
          "value": "0.01"
        },
        "seller_protection": {
          "status": "ELIGIBLE",
          "dispute_categories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]
        },
        "expiration_time": "2023-09-27T20:13:54Z",
        "links": [{
          "href": "https://api-m.paypal.com/v2/payments/authorizations/6MS02512BP527144J",
          "rel": "self",
          "method": "GET"
        }, {
          "href": "https://api-m.paypal.com/v2/payments/authorizations/6MS02512BP527144J/capture",
          "rel": "capture",
          "method": "POST"
        }, {
          "href": "https://api-m.paypal.com/v2/payments/authorizations/6MS02512BP527144J/void",
          "rel": "void",
          "method": "POST"
        }, {
          "href": "https://api-m.paypal.com/v2/checkout/orders/5AT627990P285181E",
          "rel": "up",
          "method": "GET"
        }],
        "create_time": "2023-08-29T20:13:54Z",
        "update_time": "2023-08-29T20:13:54Z"
      }]
    }
  }],
  "payer_info": {
    "email": "doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "payer_id": "ZU7HZ76P4VL5U",
    "phone": "123-456-7890",
    "billing_address": {
      "address_status": "CONFIRMED",
      "line1": "123 Main St.",
      "line2": "Suite #4",
      "city": "New York",
      "state": "NY",
      "postal_code": "12345",
      "country_code": "US"
  },
  "links": [{
    "href": "https://api-m.paypal.com/v2/checkout/orders/5AT627990P285181E",
    "rel": "self",
    "method": "GET"
  }]
}

For more information about using a reference transaction to make a payment, see the Payments API Reference.

Optional configuration

You can add the following options to your configuration:

Show token details
Show billing agreement details
Show payer billing address and email
Update the billing agreement
Cancel the billing agreement
Allow payers to change the payment method

Show billing agreement details

To show details about the billing agreement that the payer approved, include the billing agreement ID in the URI:

curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN"

A successful request returns a JSON response body that shows agreement details:

{
  "id": "B-50V812176H0783741",
  "state": "ACTIVE",
  "description": "Billing Agreement",
  "payer":
  {
    "payer_info":
    {
      "email": "doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "ZU7HZ76P4VL5U"
    }
  },
  "plan":
  {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences":
    {
      "notify_url": "https://example.com/notify",
      "accepted_pymt_type": "INSTANT"
    }
  },
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741/cancel",
    "rel": "cancel",
    "method": "POST"
  },
  {
    "href": "https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741",
    "rel": "self",
    "method": "GET"
  }],
  "merchant":
  {
    "payee_info":
    {
      "email": "merchant@example.com"
    }
  },
  "create_time": "2017-08-08T07:19:28.000Z",
  "update_time": "2017-08-08T07:19:28.000Z"
}

Show token details

To show details for a billing agreement token, include the token in the URI:

curl -v -X GET https://api-m.sandbox.paypal.com/v1/billing-agreements/agreement-tokens/BA-8A802366G0648845Y \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN"

A successful request returns the HTTP 200 OK status code and a JSON response body that shows token details:

{
  "description": "Billing Agreement",
  "token_id": "BA-8A802366G0648845Y",
  "token_status": "PENDING",
  "skip_shipping_address": false,
  "immutable_shipping_address": true,
  "redirect_urls":
  {
    "cancel_url": "https://example.com/cancel",
    "return_url": "https://example.com/return",
    "notify_url": "https://example.com/notify"
  },
  "plan_unit_list": [
  {
    "id": "BA-8A802366G0648845Y",
    "billing_type": "MERCHANT_INITIATED_BILLING"
  }],
  "owner":
  {
    "merchant_id": "J6LF2WT3H97J6",
    "email": "merchant@example.com"
  }
}

Show payer billing address and email

In some cases, you need the payer's billing address and email.

To return this information in the create billing agreement or show agreement details calls, select the Billing Address option in the admin dashboard. Then, the response shows the payer's billing address and email:

Note: Contact your PayPal account manager to enable the Billing Address option.

{
  "payer_info": {
    "email": "doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "payer_id": "ZU7HZ76P4VL5U",
    "phone": "123-456-7890",
    "billing_address": {
      "address_status": "CONFIRMED",
      "line1": "123 Main St.",
      "line2": "Suite #4",
      "city": "New York",
      "state": "NY",
      "postal_code": "12345",
      "country_code": "US"
  }
}

Update billing agreement

To update a billing agreement, specify the agreement ID in the https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741 URI:

curl -v -X PATCH https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -d '[{
  "op": "replace",
  "path": "/",
  "value":
  {
    "description": "Example Billing Agreement",
    "merchant_custom_data": "INV-001"
  }
},
{
  "op": "replace",
  "path": "/plan/merchant_preferences/",
  "value":
  {
    "notify_url": "https://example.com/notification"
  }
}]'

A successful request returns the HTTP 204 No Content status code with no JSON response body.

When you don't need to complete any more reference transactions with the billing agreement ID, you can cancel the agreement.

Cancel billing agreement

To cancel a billing agreement, specify the ID in the https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/{agreement_id}/cancel URI:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741/cancel \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS-TOKEN"

A successful request returns the HTTP 200 OK status code with no JSON response body.

Change the payment method

Set up your website to give your payers the option to change the payment method for a specific transaction.

Additional information

Reference Transactions API reference