Change payment methods

DocsLast updated: December 8th 2023, @ 8:10:55 am

Give your buyers the option to change the payment method for a specific transaction. For example, buyers might choose a credit card with more points or a bank account with more funds.

This page is for merchants who have a PayPal v1/billing agreements REST API billing agreement with their buyer. When changing the payment method, the buyer can select an existing payment method or add a new one.

Warning: To continue providing a Pay Later option at checkout, it is essential that you integrate Billing With Purchase. This solution offers the same functionalities as Billing Agreement and is compatible with your existing payment options.

Know before you code

The buyer must already have a billing agreement with the merchant before they can change their payment method. The billing agreement ID should be in your records.
The buyer can change the payment option only if they're present to complete the transaction.
This integration works for intent capture and authorize transactions.
This integration uses the v2/orders REST API.

How it works

The following is a sample workflow:

Create an order by calling the v2/orders API and passing the Billing Agreement ID in the application_context object.
Get the HATEOAS URL from the response.
On your website, display a hyperlink using the HATEOAS URL. Give the hyperlink a name, such as Options. You can use JavaScript to create a pop-up window when the user selects the hyperlink.

Figure 1: Checkout page with the option to change the payment method.
Your buyer selects the hyperlink and changes the payment method.
Your buyer places the order.

Step 1: Create an order

Copy the following code and modify it.

Sample request

API endpoint used: Create order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "CAPTURE",
  "payer": {
    "address": {
      "address_line_1": "billing",
      "address_line_2": "address",
      "admin_area_2": "fremont",
      "admin_area_1": "CA",
      "postal_code": "94536",
      "country_code": "US"
    }
  },
  "application_context": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel",
    "preferred_payment_source": {
      "token": {
        "type": "BILLING_AGREEMENT",
        "id": "B-2SV62607B0766021W"
      }
    }
  },
  "purchase_units": [
    {
      "description": "Sporting Goods",
      "custom_id": "CUST-HighFashions",
      "soft_descriptor": "HighFashions",
      "amount": {
        "currency_code": "USD",
        "value": "220.00",
        "breakdown": {
          "item_total": {
            "currency_code": "USD",
            "value": "180.00"
          },
          "shipping": {
            "currency_code": "USD",
            "value": "20.00"
          },
          "handling": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax_total": {
            "currency_code": "USD",
            "value": "20.00"
          },
          "gift_wrap": {
            "currency_code": "USD",
            "value": "0.00"
          },
          "shipping_discount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        }
      },
      "items": [
        {
          "name": "T-Shirt",
          "description": "Green XL",
          "sku": "sku01",
          "unit_amount": {
            "currency_code": "USD",
            "value": "90.00"
          },
          "tax": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "quantity": "1",
          "category": "PHYSICAL_GOODS"
        },
        {
          "name": "Shoes",
          "description": "Running, Size 10.5",
          "sku": "sku02",
          "unit_amount": {
            "currency_code": "USD",
            "value": "45.00"
          },
          "tax": {
            "currency_code": "USD",
            "value": "5.00"
          },
          "quantity": "2",
          "category": "PHYSICAL_GOODS"
        }
      ],
      "shipping": {
        "method": "United States Postal Service",
        "address": {
          "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"
        }
      }
    }
  ]
}'

Modify the code

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

Change Access-Token to your access token.
Change return_url to the URL of the webpage where buyers land after completing a successful form submission.
Change cancel_url to the URL of the webpage where buyers land after cancelling a form submission.

Step result

A successful request returns:

A return status code of HTTP 201 Created.
An order ID. In the sample response, the ID is 38F59383Y76396014.
Multiple HATEOAS links.

Sample response

{
  "id": "38F59383Y76396014",
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "reference_id": "default",
      "amount": {
        "currency_code": "USD",
        "value": "220.00",
        "breakdown": {
          "item_total": {
            "currency_code": "USD",
            "value": "180.00"
          },
          "shipping": {
            "currency_code": "USD",
            "value": "20.00"
          },
          "handling": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "tax_total": {
            "currency_code": "USD",
            "value": "20.00"
          },
          "shipping_discount": {
            "currency_code": "USD",
            "value": "10.00"
          }
        }
      },
      "payee": {
        "email_address": "hjohari-facilitator@paypal.com",
        "merchant_id": "N4XE6SG5NQP6N"
      },
      "description": "Sporting Goods",
      "custom_id": "CUST-HighFashions",
      "soft_descriptor": "HighFashions",
      "items": [
        {
          "name": "T-Shirt",
          "unit_amount": {
            "currency_code": "USD",
            "value": "90.00"
          },
          "tax": {
            "currency_code": "USD",
            "value": "10.00"
          },
          "quantity": "1",
          "description": "Green XL",
          "sku": "sku01",
          "category": "PHYSICAL_GOODS"
        },
        {
          "name": "Shoes",
          "unit_amount": {
            "currency_code": "USD",
            "value": "45.00"
          },
          "tax": {
            "currency_code": "USD",
            "value": "5.00"
          },
          "quantity": "2",
          "description": "Running, Size 10.5",
          "sku": "sku02",
          "category": "PHYSICAL_GOODS"
        }
      ],
      "shipping": {
        "method": "United States Postal Service",
        "address": {
          "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"
        }
      }
    }
  ],
  "payer": {
    "address": {
      "address_line_1": "billing",
      "address_line_2": "address",
      "admin_area_1": "CA",
      "postal_code": "94536",
      "country_code": "US"
    }
  },
  "create_time": "2020-01-09T03:20:53Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/38F59383Y76396014",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=38F59383Y76396014",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/38F59383Y76396014",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/38F59383Y76396014/capture",
      "rel": "capture",
      "method": "POST"
    }
  ],
  "status": "CREATED"
}

Step 2: Redirect the buyer

Use the HATEOAS URL returned in step 1 to redirect the buyer so they can login to their PayPal account, choose the payment method, and approve the transaction.

HATEOAS link

{
"href": "https://www.sandbox.paypal.com/checkoutnow?token={id}",
"rel": "approve",
"method": "GET"
}

Replace id with the order ID returned from step 1.

Step 3: Capture the order

After the buyer chooses the payment method and approves the transaction, the PayPal window closes. The API then redirects the buyer to the return_url from the Create order API call.

Once the buyer confirms their order, capture the order by calling the HATEOAS link with rel:capture to complete the transaction.

Copy the following code and replace id with the order ID.

Sample request

API endpoint used: Capture the payment

{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/{id}/capture",
"rel": "capture",
"method": "POST"
}

After you copy the code in the sample request, replace id with the order ID.

Step result

A successful request returns:

The HTTP 201 Created status code.
A JSON response body that shows the captured payment details.

Sample response

{
  "id": "38F59383Y76396014",
  "purchase_units": [
    {
      "reference_id": "default",
      "shipping": {
        "name": {
          "full_name": "test buyer"
        },
        "address": {
          "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"
        }
      },
      "payments": {
        "captures": [
          {
            "id": "7R598468U3262991D",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "220.00"
            },
            "final_capture": true,
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "220.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "6.68"
              },
              "net_amount": {
                "currency_code": "USD",
                "value": "213.32"
              }
            },
            "custom_id": "CUST-HighFashions",
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/7R598468U3262991D",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/7R598468U3262991D/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/38F59383Y76396014",
                "rel": "up",
                "method": "GET"
              }
            ],
            "create_time": "2020-01-09T03:42:24Z",
            "update_time": "2020-01-09T03:42:24Z"
          }
        ]
      }
    }
  ],
  "payer": {
    "name": {
      "given_name": "test",
      "surname": "buyer"
    },
    "email_address": "hjohari-buyer@paypal.com",
    "payer_id": "84BRDHAWM4VE8",
    "phone": {
      "phone_number": {
        "national_number": "4087991221"
      }
    },
    "address": {
      "country_code": "US"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/38F59383Y76396014",
      "rel": "self",
      "method": "GET"
    }
  ],
  "status": "COMPLETED"
}

Change payment methods

Know before you code

How it works

Step 1: Create an order

Sample request

Modify the code

Step result

Sample response

Step 2: Redirect the buyer

HATEOAS link

Step 3: Capture the order

Sample request

Step result

Sample response

See also