Alternative payment methods

DocsCurrent

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

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.
  • 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.
Get access tokenRead the guide

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

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:

  1. The buyer selects an APM at checkout.
  2. The buyer provides purchase details.
  3. To confirm the purchase, PayPal redirects the buyer to an alternative payment provider, such as a bank or wallet.
  4. The buyer approves and confirms payment.
  5. The buyer returns to the merchant page to finalize the transaction.
  6. The merchant initiates the completion of payment. PayPal moves the money to the merchant.
How it works

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.

1

Subscribe to webhook

To subscribe to the CHECKOUT.ORDER.APPROVED event, copy the following code and modify it.

Sample request

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}'

    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}
      2

      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:

      3

      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}
          4

          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.

          1. Add the following parameters to the JavaScript SDK call with an associated code:

          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. *

            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.

            1. Log into the PayPal sandbox using the business sandbox account from the Developer Dashboard.
            2. 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

            Required
            Go live

            How to take your integration live.

            Optional
            See also

            Learn more about working with PayPal webhooks

            We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies