Alternative payment methods

DOCSCURRENT

Last updated: May 12th, 3:19pm

Overview

Alternative payment methods (APMs) allow you to accept payments from customers worldwide who use their bank accounts, wallets, and local payment methods. When a buyer pays in a currency other than yours, PayPal handles currency conversion for you and presents conversion information to the buyer during checkout.

While displaying and accepting APMs is included with the checkout integration, we recommend subscribing to the CHECKOUT.ORDER.APPROVED webhook event in case a customer accidentally closes the browser and exits the checkout process after approving the transaction through their APM but before finalizing the transaction on your site.

Note: Inform your payers that PayPal is processing the payment by implementing one of the following options:

At checkout, include the following text and a link to the PayPal privacy notice - By paying with your card, you acknowledge that PayPal will process your data according to the PayPal Privacy Statement available at PayPal.com.

Include the following text in your privacy notice, which you'll need to show before payment - We use PayPal for payments and other services. If you want to use one of these services and pay on our website, PayPal may collect the personal data you provide, such as payment and other identifying information. PayPal uses this information to operate and improve the services it provides to us and others, including for fraud detection, harm and loss prevention, authentication, analytics related to the performance of its services, and to comply with applicable legal requirements. The processing of this information will be subject to the PayPal Privacy Statement available at PayPal.com.

Know before you code

Required
You need the following to use this integration:

This integration is available to select partners only.

If you don't want to accept APMs on your site, use the disable-funding parameter in the JavaScript SDK call disable APMs.

Refer to Supported alternative payment methods to become familiar with which APMs are accepted in different countries.

This procedure adds to an existing client-side checkout integration.

By adding funding sources to your checkout integration, you agree to the PayPal Alternative Payment Methods Agreement. This is in addition to the user agreement applicable to the country in which your business is physically located.

Complete the steps in Get started to get your credentials

Required
You need a developer account to get sandbox credentials

PayPal uses the following REST API credentials, which you can get from the developer dashboard:

Client ID: Authenticates your account with PayPal and identifies an app in your sandbox.

Client secret: Authorizes an app in your sandbox. Keep this secret safe and don't share it.

Required
You need both PayPal and third-party tools

PayPal JavaScript SDK

Webhooks Management REST API

Orders REST API

Optional
Explore PayPal APIs with Postman

You can use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

How it works

APMs show up automatically and differ by country or region. The flow for completing a payment through an APM is as follows:

The buyer selects an APM at checkout.

The buyer provides purchase details.

To confirm the purchase, PayPal redirects the buyer to an alternative payment provider, such as a bank or wallet.

The buyer approves and confirms payment.

The buyer returns to the merchant page to finalize the transaction.

The merchant initiates the completion of payment. PayPal moves the money to the merchant.

Maintain default integration values

While the checkout integration includes APMs by default, they display only when the buyer is eligible for one of the methods and when the following default integration values are maintained:

Parameter	Value	Description
`style.layout`	`vertical`	Default. Buttons are stacked vertically with a maximum of four buttons. Recommended when: Presenting a dynamic list of payment options on checkout and shopping cart pages. Leveraging Checkout as a full stack payments platform.
`intent`	`capture`	The money is captured immediately while the buyer is on your site.
`commit`	`true`	Show a Pay Now button in the Checkout flow. The final amount will not change after the buyer returns from PayPal to your site.
`vault`	`false`	Show all funding sources.

Because these are default values, you don't have to specify them in the JavaScript SDK call, but make sure you don't explicitly change any of them by passing a non-default value for the parameter.

Note:  APMs don't work with all payment configurations because some configurations change these default values. Payment configurations that don't work with APMs because they change these default values include: authorize and capture later, subscriptions, vaulting, and shipping changes callback scenarios.

Tip: For a no-code option, subscribe to the Checkout order approved webhook event in your sandbox REST API app in the Developer Dashboard. Open then app you're using for development, scroll to the webhooks section, and click Add Webhook.

API endpoint used: Create webhook

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/notifications/webhooks \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-H 'PayPal-Partner-Attribution-Id: &lt;BN-Code&gt;' \
5-d '{
6  "url": "https://example.com/example_webhook",
7  "event_types": [
8    {
9      "name": "CHECKOUT.ORDER.APPROVED"
10    }
11  ]
12}'

After you copy the code in the sample request, modify the following:

Access-Token - Your access token.

BN-Code - Change to your PayPal Partner Attribution ID.

url - The URL of your webhook handler that listens for webhooks you're subscribed to.

A successful request results in the following:

A return status code of HTTP 201 Created.

A JSON response body that contains the webhook ID.

An entry for the webhook in the REST API app you're using for development. Open then app you're using and scroll to the webhooks section to confirm the webhook appears with the same ID returned in this call.

1{
2    "id": "2CJ781045X895601X",
3    "url": "https://example.com/example_webhook",
4    "event_types": [{
5        "name": "CHECKOUT.ORDER.APPROVED",
6        "description": "An order has been approved by buyer."
7    }],
8    "links": [{
9            "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks/2CJ781045X895601X",
10            "rel": "self",
11            "method": "GET"
12        },
13        {
14            "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks/2CJ781045X895601X",
15            "rel": "update",
16            "method": "PATCH"
17        },
18        {
19            "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks/2CJ781045X895601X",
20            "rel": "delete",
21            "method": "DELETE"
22        }
23    ]
24}

Update handler logic

A webhook handler is a script you create on your server that completes specific actions on webhooks that hit your listener URL. Each handler script implementation is different, but for this task, ensure you have logic in your handler script that verifies each CHECKOUT.ORDER.APPROVED event has a completed transaction in your database. An incomplete transaction might signal a dropped cart, and you'll have to capture the payment to finalize the transaction.

The following resources might be useful as you create webhook handler code:

Webhook Management API - Manage webhooks, list event notifications, and more.

Webhook events
- Checkout webhook events - Checkout buyer approval-related webhooks.
- Order webhook events - Other order-related webhooks.

Show order details endpoint - Determine the status of an order.

Capture payments

If there are incomplete transactions that indicate a customer completed authorization with their APM but closed the window before finalizing the transaction on your site, you can capture the payments for those transactions.

To capture the payment for an authorized but incomplete transaction, copy the following code and modify it.

Sample request

API endpoint used: Capture payment for order

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/2BE65243S8119680R/capture \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer Access-Token" \
4  -H 'PayPal-Partner-Attribution-Id: &lt;BN-Code&gt;' \
5  -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440040" \

Modify the code

After you copy the code in the sample request, modify the following:

Access-Token - Your access token.

Order ID - In the URI for the API call, replace the sample ID with the order ID returned by the CHECKOUT.ORDER.APPROVED webhook event.

BN-Code - Change to your PayPal Partner Attribution ID.

PayPal-Request-Id - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate captures if the API call is disrupted. See also: API Idempotency.

Step result

A successful request results in the following:

A return status code of HTTP 201 Created.

A JSON response body that contains details for the captured payment. Use the ID returned if you need to refund the transaction in the future.

Sample response

1{
2    "id": "2BE65243S8119680R",
3    "purchase_units": [{
4        "reference_id": "default",
5        "shipping": {
6            "name": {
7                "full_name": "John Doe"
8            },
9            "address": {
10                "address_line_1": "Badensche Straße 24",
11                "admin_area_2": "Berlin-Wilmersdorf",
12                "postal_code": "10715",
13                "country_code": "DE"
14            }
15        },
16        "payments": {
17            "captures": [{
18                "id": "9XR60255JN8591232",
19                "status": "PENDING",
20                "status_details": {
21                    "reason": "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION"
22                },
23                "amount": {
24                    "currency_code": "EUR",
25                    "value": "15.00"
26                },
27                "final_capture": true,
28                "seller_protection": {
29                    "status": "ELIGIBLE",
30                    "dispute_categories": [
31                        "ITEM_NOT_RECEIVED",
32                        "UNAUTHORIZED_TRANSACTION"
33                    ]
34                },
35                "links": [{
36                        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9XR60255JN8591232",
37                        "rel": "self",
38                        "method": "GET"
39                    },
40                    {
41                        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9XR60255JN8591232/refund",
42                        "rel": "refund",
43                        "method": "POST"
44                    },
45                    {
46                        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/2BE65243S8119680R",
47                        "rel": "up",
48                        "method": "GET"
49                    }
50                ],
51                "create_time": "2020-02-26T22:52:00Z",
52                "update_time": "2020-02-26T22:52:00Z"
53            }]
54        }
55    }],
56    "payer": {
57        "name": {
58            "given_name": "John",
59            "surname": "Doe"
60        },
61        "email_address": "buyer@example.com",
62        "payer_id": "PPFAH5AWAX7RS",
63        "address": {
64            "country_code": "DE"
65        }
66    },
67    "links": [{
68        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/2BE65243S8119680R",
69        "rel": "self",
70        "method": "GET"
71    }],
72    "status": "COMPLETED"
73}

Test

APMs show up automatically and differ by country based on locale and country settings. You can force APMs to show to test an APM transaction.

Add the following parameters to the JavaScript SDK call with an associated code:
- currency - Supported currency codes
- locale - Supported locale codes
- buyer-country - Supported country codes

Sample call:

1<script
2src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=EUR&locale=de_DE&buyer-country=DE">
3// Required. Replace YOUR_CLIENT_ID with your sandbox client ID.
4</script>

2. Test the transaction as a buyer: On your checkout page, click one of the APM payment buttons. For example, if you are testing a German APM transaction, you might select the giropay button. *

Important: giropay will be sunset on June 30, 2024. PayPal will not support giropay payments starting July 1, 2024. Offer your users PayPal wallet and other alternative payment methods.

3. Click the pre-fill information button at the top of the checkout screen to enter test user information. In the following example, you'd select: Pre-fill button.

4. Enter a test email address. You can use the email address for your personal sandbox account.

5. Click through the flow to complete the transaction. The simulation server displays options for testing successful and failed authorizations.

6. Confirm the money shows up in the merchant account.

Log into the PayPal sandbox using the business sandbox account from the Developer Dashboard.

Verify that the money, minus any fees, has been received in the business account.

7. You can confirm the CHECKOUT.ORDER.APPROVED event fires as you expect in any of the following ways:

In Developer Dashboard - Confirm the Checkout order approved webhook shows up in the REST API app you're using for development. Open the app you're using and scroll to the webhooks section to confirm the webhook shows up with the same ID returned in the Create Webhook REST API call.

On your listener URL - Confirm your listener URL received the webhook when you completed a test transaction.

In your Webhook handler - Run any tests you've developed for your webhook handler script to confirm code updates you've made for handling the CHECKOUT.ORDER.APPROVED webhook.

Alternative payment methods

Overview

Know before you code

Required
You need the following to use this integration:

Required
You need a developer account to get sandbox credentials

Required
You need both PayPal and third-party tools

Optional
Explore PayPal APIs with Postman

How it works

Maintain default integration values

Update handler logic

Capture payments

Sample request

Modify the code

Step result

Sample response

Test

Sample call:

Next steps & customizations

Required
Go live

Optional
See also

Alternative payment methods

Overview

Know before you code

How it works

Maintain default integration values

Subscribe to webhook

Sample request

Modify the code

Step result

Sample response

Update handler logic

Capture payments

Sample request

Modify the code

Step result

Sample response

Test

Sample call:

Next steps & customizations

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