Online payments

Overview

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:

Note: Token is for single use only, you can create only one billing agreement from one token.

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.

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:

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