Enable PayPal in a Google Pay integration

PayPal merchants can enable Google Pay with PayPal on their website or Android application.

Note: If you're not a PayPal merchant and you want to accept PayPal within Google Pay, implement a PayPal server integration, then return to this document and continue to the Google Pay API integration.

Integrate the Google Pay API to enable PayPal in Google Pay

This guide is for PayPal merchants who want to integrate with Google Pay and support PayPal as a payment option within Google Pay.

Prerequisites

Payments API is the preferred way to enable PayPal within Google Pay.
A PayPal merchant ID is required for this integration. You can look up your merchant ID by logging into https://www.paypal.com.
- Select the settings icon at the top of your PayPal account page and then click Profile and settings.
- Click My business info on the left, and the alphanumeric Merchant account ID displays in the list of profile items on the right.

Integrate

Follow the steps on Google's website to integrate with the Google Pay API.

Construct a base request to determine your buyer's ability to pay with PayPal or any other payment methods you support. Define your support for the PayPal in IsReadyToPayRequest.

PayPalPaymentMethod = {
  "type": "PAYPAL",
  "parameters": {
    "purchase_context": {
      "purchase_units": [{
        "payee": {
          "merchant_id": "<paypal_merchant_id>"
        }
      }]
    }
  }
};

Call the isReadyToPay method from the Google Pay API to determine the buyer's ability to pay with one or more specified payment methods, including PayPal.

IsReadyToPayRequest = {
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        ...
      },
      "tokenizationSpecification": {
        ...
      }
    },
    PayPalPaymentMethod
  ]
};

PaymentsClient.isReadyToPay(IsReadyToPayRequest);

Add a tokenizationSpecification parameter to the request to have the PayPal payment token returned directly to your site or app.

PayPalPaymentMethod.tokenizationSpecification = {
"type": "DIRECT"
}

Set PAYPAL as the payment method type and pass the PayPal-specific parameters in purchase_context to receive a PayPal payment token for Android and Web in the Google integration.

The purchase_context object needs to be a formatted JSON string.

PaymentDataRequest = {
   "apiVersion": 2,
   "apiVersionMinor": 0,
   "allowedPaymentMethods": [
   {
      "type": "PAYPAL",
      "parameters": {
        // Use the merchant account ID from https://www.paypal.com
        "purchase_context": [{
          payee: {
            merchant_id: "<merchant_id>"
          }
        }]
      }
   }]
};

PaymentDataResponse = {
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    // Common fields
    "type": "PAYPAL",
    "description": "PayPal: john@gmail.com",
    "tokenizationData": {
      "type": "DIRECT",
      // This is the payment token you pass to the /payment call
      "token": "xxxxxxxxxxxxxxx"
    },
    }
  };

The following samples show minimum parameters required for the purchase_context object.

Note: Your PayPal merchant_id is required. Also, the default payment_intent is CAPTURE.

// Request with minimum fields

 {
   "purchase_context": {
     "purchase_units": [{
       "payee": {
         "merchant_id":"xxxxxxxxxxxxxxx"
       }
     }]
   }
 }

The following sample shows optional parameters. See optional parameters for purchase_context for additional parameters. If you receive the shipping address from the Google API, you can continue to pass the POST /payments call for a complete record of the transaction.

// Request with optional fields

{
  "purchase_context": {
    "payment_intent": "CAPTURE",
    "purchase_units": [
      {
        "reference_id": "PUHF",
        "description": "Sporting Goods",
        "custom_id": "CUST-HighFashions",
        "soft_descriptor": "HighFashions",
        "payee": {
          "merchant_id": "xxxxxxxxxxxxxxx"
        },
        "shipping": {
          "method": "United States Postal Service",
          "address": {
            "name": {
              "full_name": "John Doe"
            },
            "address_line_1": "123 Townsend St",
            "address_line_2": "Floor 6",
            "admin_area_2": "San Francisco",
            "admin_area_1": "CA",
            "postal_code": "94107",
            "country_code": "US"
          }
        }
      }
    ]
  }
}

After this step, customers now have the Google Pay button with the option to select PayPal if they've linked their PayPal account to their Google account. You'll use this token in the next step.

When a customer selects PayPal as a payment method, the Google Pay API response includes a PayPal payment token to complete the PayPal transaction.

Pass the token from Google Pay to the v1/payments/payment call using payer.funding_instruments.pay_token. Not all fields are required. Refer to the v1/payments/payment POST method for details about other required and optional fields.

It is important that the Bearer token within the Authorization header be generated using the client_id and secret for the merchant (as identified by merchant_id) that was passed as part of the purchase_context parameters for the Google Pay call. If not, you receive a PERMISSION_DENIED error.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-H "PayPal-Request-Id: <API caller-generated idempotency ID>" \
-d '{
  "intent": "sale",
  "payer": {
    "payment_method": "paypal",
    "funding_instruments": [
      {
        "pay_token": {
          "type": "PAYMENT_METHOD_TOKEN",
          "id": "<token>",
          "issuer": "PAYPAL"
        }
      }
    ]
  },
  "transactions": [
    {
      "amount": {
        "total": "30.11",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.07",
          "shipping": "0.03",
          "handling_fee": "1.00",
          "shipping_discount": "-1.00",
          "insurance": "0.01"
        }
      },
      "description": "The payment transaction description.",
      "invoice_number": "48787589673",
      "payment_options": {
        "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
      },
      "soft_descriptor": "ECHI5786786",
      "item_list": {
        "items": [
          {
            "name": "hat",
            "description": "Brown hat.",
            "quantity": "5",
            "price": "3",
            "tax": "0.01",
            "sku": "1",
            "currency": "USD"
          },
          {
            "name": "handbag",
            "description": "Black handbag.",
            "quantity": "1",
            "price": "15",
            "tax": "0.02",
            "sku": "product34",
            "currency": "USD"
          }
        ],
        "shipping_address": {
          "recipient_name": "Brian Robinson",
          "line1": "4th Floor",
          "line2": "Unit #34",
          "city": "San Jose",
          "country_code": "US",
          "postal_code": "95131",
          "phone": "011862212345678",
          "state": "CA"
        }
      }
    }
  ],
  "note_to_payer": "Contact us for any questions on your order.",
  "redirect_urls": {
    "return_url": "https://yourwebsite.com/return",
    "cancel_url": "https://yourwebsite.com/cancel"
  }
}'

Best practices

PayPal recommends that you pass the PayPal-Request-ID header to ensure that you can expect an idempotent response in situations when failures arise (such as time outs). When you pass this header, an initial success response is returned with an HTTP status of 201 CREATED. An idempotent response has a status of HTTP 200 OK.
Refund a sale or captured payment transaction using the Payments API. This integration does not change how you process Refunds, Voids, Disputes or any other post-payment transaction calls.
PayPal recommends that you continue to pass the shipping_address (including shipping addresses from the Google API) in the POST /payments call for a complete record of the transaction.
Refer to Google Pay FAQs on the PayPal Help Center for more information about adding PayPal to Google Pay.

Required parameter for this integration

Parameter, Type, Description
Parameter	Type	Description
`payee.merchant_id`	String. Required.	The encrypted PayPal account ID of the merchant. A PayPal merchant ID is required for this integration.

Optional parameters for `purchase_context`

Parameter, Type, Description
Parameter	Type	Description
`payment_intent`	Enum.	Specifies intent to either authorize or capture the payment. Valid values are: `CAPTURE` (default)– if the intention is to capture payment immediately. This is equivalent to specifying SALE if you currently use our NVP/SOAP or `v1/payments/payment`REST APIs. `AUTHORIZE` – if the intention is to authorize the payment. This is equivalent to specifying Authorization if you currently use our NVP/SOAP or "authorize" if you currently use `v1/payments/payment` REST APIs.

Parameter, Type, Description
Parameter	Type	Description
`reference_id`	String.	The ID for the purchase unit. Maximum length is 256.
`description`	String.	The purchase description. Maximum length is 127.
`custom_id`	String.	The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer. Maximum length is 127.
`invoice_id`	String.	The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. Maximum length is 127.
`soft_descriptor`	String.	The payment descriptor on the payer's credit card statement. Maximum length is 22.
`shipping.address.name.full_name`	String.	The name of the person to whom to ship the items. Maximum length is 300.
`shipping.address.name.address_line1`	String.	The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address. Maximum length is 300.
`shipping.address.name.address_line2`	String.	The second line of the address. For example, suite or apartment number. Maximum length is 300.
`shipping.address.name.address.admin_area_1`	String.	The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is: UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton. Maximum length: 300.
`shipping.address.name.admin_area_2`	String.	A city, town, or village. Smaller than `admin_area_level_1`. Maximum length is 300.
`shipping.postal_code`	String.	The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. Maximum length is 60.
`shipping.address.country_code`	String.	The two-character ISO 3166-1 code that identifies the country or region. If `shipping.address` is specified `country_code` is required.

Integrate the Google Pay API to enable PayPal in Google Pay

This guide is for PayPal merchants who want to integrate with Google Pay and support PayPal as a payment option within Google Pay.

Payments API is the preferred way to enable PayPal within Google Pay.
A PayPal merchant ID is required for this integration. You can look up your merchant ID by logging into https://www.paypal.com.
- Select the settings icon at the top of your PayPal account page and then click Profile and settings.
- Click My business info on the left, and the alphanumeric Merchant account ID displays in the list of profile items on the right.

Follow the steps on Google's website to integrate with the Google Pay API.

Construct a base request to determine your buyer's ability to pay with PayPal or any other payment methods you support. Define your support for the PayPal in IsReadyToPayRequest.

PayPalPaymentMethod = {
  "type": "PAYPAL",
  "parameters": {
    "purchase_context": {
      "purchase_units": [{
        "payee": {
          "merchant_id": "<paypal_merchant_id>"
        }
      }]
    }
  }
};

Call the isReadyToPay method from the Google Pay API to determine the buyer's ability to pay with one or more specified payment methods, including PayPal.

IsReadyToPayRequest = {
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        ...
      },
      "tokenizationSpecification": {
        ...
      }
    },
    PayPalPaymentMethod
  ]
};

PaymentsClient.isReadyToPay(IsReadyToPayRequest);

Add a tokenizationSpecification parameter to the request to have the PayPal payment token returned directly to your site or app.

PayPalPaymentMethod.tokenizationSpecification = {
"type": "DIRECT"
}

Set PAYPAL as the payment method type and pass the PayPal-specific parameters in purchase_context to receive a PayPal payment token for Android and Web in the Google integration.

The purchase_context object needs to be a formatted JSON string.

PaymentDataRequest = {
   "apiVersion": 2,
   "apiVersionMinor": 0,
   "allowedPaymentMethods": [
   {
      "type": "PAYPAL",
      "parameters": {
        // Use the merchant account ID from https://www.paypal.com
        "purchase_context": [{
          payee: {
            merchant_id: "<merchant_id>"
          }
        }]
      }
   }]
};

PaymentDataResponse = {
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    // Common fields
    "type": "PAYPAL",
    "description": "PayPal: john@gmail.com",
    "tokenizationData": {
      "type": "DIRECT",
      // This is the payment token you pass to the /payment call
      "token": "xxxxxxxxxxxxxxx"
    },
    }
  };

The following samples show minimum parameters required for the purchase_context object.

Note: Your PayPal merchant_id is required. Also, the default payment_intent is CAPTURE.

// Request with minimum fields

 {
   "purchase_context": {
     "purchase_units": [{
       "payee": {
         "merchant_id":"xxxxxxxxxxxxxxx"
       }
     }]
   }
 }

// Request with optional fields

{
  "purchase_context": {
    "payment_intent": "CAPTURE",
    "purchase_units": [
      {
        "reference_id": "PUHF",
        "description": "Sporting Goods",
        "custom_id": "CUST-HighFashions",
        "soft_descriptor": "HighFashions",
        "payee": {
          "merchant_id": "xxxxxxxxxxxxxxx"
        },
        "shipping": {
          "method": "United States Postal Service",
          "address": {
            "name": {
              "full_name": "John Doe"
            },
            "address_line_1": "123 Townsend St",
            "address_line_2": "Floor 6",
            "admin_area_2": "San Francisco",
            "admin_area_1": "CA",
            "postal_code": "94107",
            "country_code": "US"
          }
        }
      }
    ]
  }
}

After this step, customers now have the Google Pay button with the option to select PayPal if they've linked their PayPal account to their Google account. You'll use this token in the next step.

When a customer selects PayPal as a payment method, the Google Pay API response includes a PayPal payment token to complete the PayPal transaction.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-H "PayPal-Request-Id: <API caller-generated idempotency ID>" \
-d '{
  "intent": "sale",
  "payer": {
    "payment_method": "paypal",
    "funding_instruments": [
      {
        "pay_token": {
          "type": "PAYMENT_METHOD_TOKEN",
          "id": "<token>",
          "issuer": "PAYPAL"
        }
      }
    ]
  },
  "transactions": [
    {
      "amount": {
        "total": "30.11",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.07",
          "shipping": "0.03",
          "handling_fee": "1.00",
          "shipping_discount": "-1.00",
          "insurance": "0.01"
        }
      },
      "description": "The payment transaction description.",
      "invoice_number": "48787589673",
      "payment_options": {
        "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
      },
      "soft_descriptor": "ECHI5786786",
      "item_list": {
        "items": [
          {
            "name": "hat",
            "description": "Brown hat.",
            "quantity": "5",
            "price": "3",
            "tax": "0.01",
            "sku": "1",
            "currency": "USD"
          },
          {
            "name": "handbag",
            "description": "Black handbag.",
            "quantity": "1",
            "price": "15",
            "tax": "0.02",
            "sku": "product34",
            "currency": "USD"
          }
        ],
        "shipping_address": {
          "recipient_name": "Brian Robinson",
          "line1": "4th Floor",
          "line2": "Unit #34",
          "city": "San Jose",
          "country_code": "US",
          "postal_code": "95131",
          "phone": "011862212345678",
          "state": "CA"
        }
      }
    }
  ],
  "note_to_payer": "Contact us for any questions on your order.",
  "redirect_urls": {
    "return_url": "https://yourwebsite.com/return",
    "cancel_url": "https://yourwebsite.com/cancel"
  }
}'

PayPal recommends that you pass the PayPal-Request-ID header to ensure that you can expect an idempotent response in situations when failures arise (such as time outs). When you pass this header, an initial success response is returned with an HTTP status of 201 CREATED. An idempotent response has a status of HTTP 200 OK.
Refund a sale or captured payment transaction using the Payments API. This integration does not change how you process Refunds, Voids, Disputes or any other post-payment transaction calls.
PayPal recommends that you continue to pass the shipping_address (including shipping addresses from the Google API) in the POST /payments call for a complete record of the transaction.
Refer to Google Pay FAQs on the PayPal Help Center for more information about adding PayPal to Google Pay.

Parameter, Type, Description
Parameter	Type	Description
`payee.merchant_id`	String. Required.	The encrypted PayPal account ID of the merchant. A PayPal merchant ID is required for this integration.

Parameter, Type, Description
Parameter	Type	Description
`payment_intent`	Enum.	Specifies intent to either authorize or capture the payment. Valid values are: `CAPTURE` (default)– if the intention is to capture payment immediately. This is equivalent to specifying SALE if you currently use our NVP/SOAP or `v1/payments/payment`REST APIs. `AUTHORIZE` – if the intention is to authorize the payment. This is equivalent to specifying Authorization if you currently use our NVP/SOAP or "authorize" if you currently use `v1/payments/payment` REST APIs.

Parameter, Type, Description
Parameter	Type	Description
`reference_id`	String.	The ID for the purchase unit. Maximum length is 256.
`description`	String.	The purchase description. Maximum length is 127.
`custom_id`	String.	The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer. Maximum length is 127.
`invoice_id`	String.	The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. Maximum length is 127.
`soft_descriptor`	String.	The payment descriptor on the payer's credit card statement. Maximum length is 22.
`shipping.address.name.full_name`	String.	The name of the person to whom to ship the items. Maximum length is 300.
`shipping.address.name.address_line1`	String.	The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address. Maximum length is 300.
`shipping.address.name.address_line2`	String.	The second line of the address. For example, suite or apartment number. Maximum length is 300.
`shipping.address.name.address.admin_area_1`	String.	The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is: UK. A county. US. A state. Canada. A province. Japan. A prefecture. Switzerland. A kanton. Maximum length: 300.
`shipping.address.name.admin_area_2`	String.	A city, town, or village. Smaller than `admin_area_level_1`. Maximum length is 300.
`shipping.postal_code`	String.	The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. Maximum length is 60.
`shipping.address.country_code`	String.	The two-character ISO 3166-1 code that identifies the country or region. If `shipping.address` is specified `country_code` is required.

Enable PayPal in a Google Pay integration

Integrate the Google Pay API to enable PayPal in Google Pay

Prerequisites

Integrate

Best practices

Required parameter for this integration

Optional parameters for `purchase_context`

On this page

On this page

On this page

Enable PayPal in a Google Pay integration

Integrate the Google Pay API to enable PayPal in Google Pay

Prerequisites

Integrate

Best practices

Required parameter for this integration

Optional parameters for `purchase_context`

On this page

On this page

Enable PayPal in a Google Pay integration

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Enable PayPal in a Google Pay integration

On this page

On this page