# Change payment methods (/limited-release/payment-method/orders)



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.

> **Note:** **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 [#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 [#how-it-works]

The following is a sample workflow:

1. Create an order by calling the `v2/orders` API and passing the Billing Agreement ID in the `application_context` object.
2. Get the HATEOAS URL from the response.
3. 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.
   <img src="https://www.paypalobjects.com/ppdevdocs/img/docs/edit-fi/edit-fi.png" alt="options" />
   *Figure 1: Checkout page with the option to change the payment method.*
4. Your buyer selects the hyperlink and changes the payment method.
5. Your buyer places the order.

## Step 1: Create an order [#step-1-create-an-order]

Copy the following code and modify it.

### Sample request [#sample-request]

API endpoint used: [Create order](/api/orders/v2/orders-create)

<div className="pl-[1.625rem]" />

```bash lineNumbers
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 [#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 [#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 [#sample-response]

<div className="pl-[1.625rem]" />

```bash lineNumbers
{
  "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 [#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 [#hateoas-link]

<div className="pl-[1.625rem]" />

```bash lineNumbers
{
"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 [#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 [#sample-request-1]

API endpoint used: [Capture the payment](/api/orders/v2/orders-capture)

<div className="pl-[1.625rem]" />

```bash lineNumbers
{
"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 [#step-result-1]

A successful request returns:

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

#### Sample response [#sample-response-1]

<div className="pl-[1.625rem]" />

```bash lineNumbers
{
  "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"
}
```

## See also [#see-also]

[Billing Agreements and Reference Transactions](/limited-release/reference-transactions/)