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 inpurchase_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 defaultpayment_intent
isCAPTURE
.// 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 theshipping address
from the Google API, you can continue to pass thePOST /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 usingpayer.funding_instruments.pay_token
. Not all fields are required. Refer to thev1/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 bymerchant_id
) that was passed as part of thepurchase_context
parameters for the Google Pay call. If not, you receive aPERMISSION_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 HTTP200 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 |
---|---|---|
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 |
---|---|---|
payment_intent |
Enum. | Specifies intent to either authorize or capture the payment. Valid values are:
|
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:
|
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. |