Change payment methods

DOCS

Last updated: Sept 23rd, 9:29pm

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.

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 sale and authorize transactions.

This integration uses the v1/payments REST API.

How it works

The following is a sample workflow:

Create a payment resource by calling the v1/payments 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 proceeds with payment.

Step 1: Create a payment resource

Copy the following code and modify it.

Sample request

API endpoint used: Create payment

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment\
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-d '{
5  "intent": "sale",
6  "payer": {
7    "payment_method": "paypal"
8  },
9  "application_context": {
10    "preferred_payment_source": {
11      "token": {
12        "id": "B-2J280200NT939550G",
13        "type": "BILLING_AGREEMENT"
14      }
15    }
16  },
17  "transactions": [
18    {
19      "amount": {
20        "total": "3.11",
21        "currency": "USD",
22        "details": {
23          "subtotal": "3.00",
24          "tax": "0.07",
25          "shipping": "0.03",
26          "handling_fee": "1.00",
27          "shipping_discount": "-1.00",
28          "insurance": "0.01"
29        }
30      },
31      "description": "The payment transaction description.",
32      "custom": "EBAY_EMS_90048630024435",
33      "payment_options": {
34        "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
35      },
36      "soft_descriptor": "ECHI5786786",
37      "item_list": {
38        "items": [
39          {
40            "name": "hat",
41            "description": "Brown hat.",
42            "quantity": "5",
43            "price": "0.3",
44            "tax": "0.01",
45            "sku": "1",
46            "currency": "USD"
47          },
48          {
49            "name": "handbag",
50            "description": "Black handbag.",
51            "quantity": "1",
52            "price": "1.5",
53            "tax": "0.02",
54            "sku": "product34",
55            "currency": "USD"
56          }
57        ],
58        "shipping_address": {
59          "recipient_name": "Brian Robinson",
60          "line1": "4th Floor",
61          "line2": "Unit #34",
62          "city": "San Jose",
63          "country_code": "US",
64          "postal_code": "95131",
65          "phone": "011862212345678",
66          "state": "CA"
67        }
68      }
69    }
70  ],
71  "note_to_payer": "Contact us for any questions on your order.",
72  "redirect_urls": {
73    "return_url": "https://example.com/return",
74    "cancel_url": "https://example.com/cancel"
75  }
76}'

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.

A payment ID. In the sample response, the ID is PAYID-L2ZMPHI0XY83144MV337250T.

Multiple HATEOAS links.

Sample response

1{
2  "id": "PAYID-L2ZMPHI0XY83144MV337250T",
3  "intent": "sale",
4  "state": "created",
5  "payer": {
6    "payment_method": "paypal"
7  },
8  "application_context": {
9    "preferred_payment_source": {
10      "token": {
11        "id": "B-02R904040B876314G",
12        "type": "BILLING_AGREEMENT"
13      }
14    }
15  },
16  "transactions": [
17    {
18      "amount": {
19        "total": "30.11",
20        "currency": "USD",
21        "details": {
22          "subtotal": "30.00",
23          "tax": "0.07",
24          "shipping": "0.03",
25          "insurance": "0.01",
26          "handling_fee": "1.00",
27          "shipping_discount": "-1.00"
28        }
29      },
30      "description": "The payment transaction description.",
31      "custom": "EBAY_EMS_90048630024435",
32      "soft_descriptor": "ECHI5786786",
33      "payment_options": {
34        "allowed_payment_method": "INSTANT_FUNDING_SOURCE",
35        "recurring_flag": false,
36        "skip_fmf": false
37      },
38      "item_list": {
39        "items": [
40          {
41            "name": "hat",
42            "sku": "1",
43            "description": "Brown hat.",
44            "price": "3.00",
45            "currency": "USD",
46            "tax": "0.01",
47            "quantity": 5
48          },
49          {
50            "name": "handbag",
51            "sku": "product34",
52            "description": "Black handbag.",
53            "price": "15.00",
54            "currency": "USD",
55            "tax": "0.02",
56            "quantity": 1
57          }
58        ],
59        "shipping_address": {
60          "recipient_name": "Brian Robinson",
61          "line1": "4th Floor",
62          "line2": "Unit #34",
63          "city": "San Jose",
64          "state": "CA",
65          "postal_code": "95131",
66          "country_code": "US",
67          "phone": "011862212345678"
68        }
69      },
70      "related_resources": []
71    }
72  ],
73  "note_to_payer": "Contact us for any questions on your order.",
74  "create_time": "2020-05-06T14:20:13Z",
75  "links": [
76    {
77      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAYID-L2ZMPHI0XY83144MV337250T",
78      "rel": "self",
79      "method": "GET"
80    },
81    {
82      "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-9GB66157FY002784C",
83      "rel": "approval_url",
84      "method": "REDIRECT"
85    },
86    {
87      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAYID-L2ZMPHI0XY83144MV337250T/execute",
88      "rel": "execute",
89      "method": "POST"
90    }
91  ]
92}

Step 2: Redirect the buyer

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

HATEOAS link

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

Step 3: Make the payment

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 payment API call.

Once the buyer confirms their payment method, make the payment by calling the HATEOAS link with rel:execute to complete the transaction.

Copy the following code:

Sample request

API endpoint used: Execute the payment

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment/{payment_id}/execute\
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-d '{
5  "payer_id": "4BFTN5WTU4HME"
6}'

After you copy the code in the sample request, replace payment_id with the ID of the payment that you need to execute.

The payer_id is the ID of the payer that PayPal passes in the return_url.

Step result

A successful request returns:

The HTTP 201 Created status code.

A JSON response body that shows the executed payment details.

Sample response

1{
2  {
3    "id": "PAYID-L2ZMPHI0XY83144MV337250T",
4    "intent": "sale",
5    "state": "approved",
6    "cart": "28010880FR2210136",
7    "payer": {
8      "payment_method": "paypal",
9      "status": "VERIFIED",
10      "payer_info": {
11        "email": "sb-vftg0329193@personal.example.com",
12        "first_name": "John",
13        "last_name": "Doe",
14        "payer_id": "4BFTN5WTU4HME",
15        "shipping_address": {
16          "recipient_name": "Brian Robinson",
17          "line1": "4th Floor",
18          "line2": "Unit #34",
19          "city": "San Jose",
20          "state": "CA",
21          "postal_code": "95131",
22          "country_code": "US"
23        },
24        "country_code": "US"
25      }
26    },
27    "transactions": [
28      {
29        "amount": {
30          "total": "30.11",
31          "currency": "USD",
32          "details": {
33            "subtotal": "30.00",
34            "tax": "0.07",
35            "shipping": "0.03",
36            "insurance": "0.01",
37            "handling_fee": "1.00",
38            "shipping_discount": "-1.00"
39          }
40        },
41        "payee": {
42          "merchant_id": "AXQJVJNJYCL2J",
43          "email": "jeet-usb1@paypal.com"
44        },
45        "description": "The payment transaction description.",
46        "custom": "EBAY_EMS_90048630024435",
47        "soft_descriptor": "PAYPAL *JEETPATELST ECHI5786786",
48        "item_list": {
49          "items": [
50            {
51              "name": "hat",
52              "sku": "1",
53              "description": "Brown hat.",
54              "price": "3.00",
55              "currency": "USD",
56              "tax": "0.01",
57              "quantity": 5
58            },
59            {
60              "name": "handbag",
61              "sku": "product34",
62              "description": "Black handbag.",
63              "price": "15.00",
64              "currency": "USD",
65              "tax": "0.02",
66              "quantity": 1
67            }
68          ],
69          "shipping_address": {
70            "recipient_name": "Brian Robinson",
71            "line1": "4th Floor",
72            "line2": "Unit #34",
73            "city": "San Jose",
74            "state": "CA",
75            "postal_code": "95131",
76            "country_code": "US"
77          },
78          "shipping_phone_number": "011862212345678"
79        },
80        "related_resources": [
81          {
82            "sale": {
83              "id": "4FR33985CW436351L",
84              "state": "completed",
85              "amount": {
86                "total": "30.11",
87                "currency": "USD",
88                "details": {
89                  "subtotal": "30.00",
90                  "tax": "0.07",
91                  "shipping": "0.03",
92                  "insurance": "0.01",
93                  "handling_fee": "1.00",
94                  "shipping_discount": "-1.00"
95                }
96              },
97              "payment_mode": "INSTANT_TRANSFER",
98              "protection_eligibility": "ELIGIBLE",
99              "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE",
100              "transaction_fee": {
101                "value": "1.17",
102                "currency": "USD"
103              },
104              "receivable_amount": {
105                "value": "30.11",
106                "currency": "USD"
107              },
108              "exchange_rate": "0.692213615971749",
109              "parent_payment": "PAYID-L26E5MY3U933524UB102730M",
110              "create_time": "2020-05-13T19:49:25Z",
111              "update_time": "2020-05-13T19:49:25Z",
112              "links": [
113                {
114                  "href": "https://api-m.sandbox.paypal.com/v1/payments/sale/4FR33985CW436351L",
115                  "rel": "self",
116                  "method": "GET"
117                },
118                {
119                  "href": "https://api-m.sandbox.paypal.com/v1/payments/sale/4FR33985CW436351L/refund",
120                  "rel": "refund",
121                  "method": "POST"
122                },
123                {
124                  "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAYID-L26E5MY3U933524UB102730M",
125                  "rel": "parent_payment",
126                  "method": "GET"
127                }
128              ],
129              "soft_descriptor": "PAYPAL *JEETPATELST ECHI5786786"
130            }
131          }
132        ]
133      }
134    ],
135    "failed_transactions": [],
136    "create_time": "2020-05-13T19:46:58Z",
137    "update_time": "2020-05-13T19:49:25Z",
138    "links": [
139      {
140        "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAYID-L26E5MY3U933524UB102730M",
141        "rel": "self",
142        "method": "GET"
143      }
144    ]
145  }
146}

Change payment methods

Know before you code

How it works

Step 1: Create a payment resource

Sample request

Modify the code

Step result

Sample response

Step 2: Redirect the buyer

HATEOAS link

Step 3: Make the payment

Sample request

Step result

Sample response

See also