Alternative payment methods
Last updated: Oct 24th, 5:06pm
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.
Available payment methods
Payment method | Payment type | Payment flow | Countries | Currencies | Minimum amount | Refunds |
---|---|---|---|---|---|---|
Apple Pay | push | direct | Country list | Currency list | 1 USD |
Up to 180 days |
Google Pay | push | direct | Country list | Currency list | 1 USD |
Up to 180 days |
ACH Direct Debit | push | Bank Direct Debits | USA | USD |
1 USD |
Yes |
Know before you code
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. - 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.
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.
You need both PayPal and third-party tools
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:
|
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.
Subscribe to webhook
To subscribe to the CHECKOUT.ORDER.APPROVED
event, copy the following code and modify it.
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: <BN-Code>' \5-d '{6 "url": "https://example.com/example_webhook",7 "event_types": [8 {9 "name": "CHECKOUT.ORDER.APPROVED"10 }11 ]12}'
Modify the code
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.
Step result
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.
Sample response
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: <BN-Code>' \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 codeslocale
- Supported locale codesbuyer-country
- Supported country codes
Sample call:
1<script2src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=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. *
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.
Next steps & customizations
Go live
How to take your integration live.
See also
Learn more about working with PayPal webhooks