Change payment methods

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 NVP/SOAP billing agreement with their buyer. When changing the payment method, the buyer can select an existing payment method or add a new one.

Note: Changing the payment method doesn't replace the buyer's original payment method.

Know before you code

• Before you can create the option to change the payment method, integrate the PayPal NVP/Soap billing agreement API with reference transactions.
• 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 instant sale and authorization and capture transactions.
• This integration uses NVP/SOAP (version 215 or higher).

How it works

The following is a sample workflow:

1. Call the SetExpressCheckout object and pass a new parameter called BILLING_AGREEMENT_ID along the other request parameters.
2. Use the token from the response of the SetExpressCheckout call to create the redirect URL.
3. On the checkout page, add an Options link next to the vaulted PayPal email address.
   
   Figure 1: Checkout page with the option to change the payment method.
4. When the buyer selects the Options link, the buyer is redirected to a page and chooses a different payment method. After the buyer chooses a payment method, the redirect URL takes them back to the merchant website.
5. If the buyer chooses to change the payment method, first call the GetExpressCheckoutDetails object to get the PayerID, then call the DoExpressCheckoutPayment object.
   Otherwise, if the buyer chooses not to use the Options link to change the payment method, call the DoReferenceTransaction object.

1. Set up the payment authorization

After setting up a billing agreement, help the buyer change the payment method that's associated with their billing agreement. Start by calling the PayPal SetExpressCheckout object.

Sample request

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=insert_merchant_user_name_here
&PWD=insert_merchant_password_here
&SIGNATURE=insert_merchant_signature_value_here
&METHOD=SetExpressCheckout
&VERSION=215
&PAYMENTREQUEST_0_PAYMENTACTION=SALE
&PAYMENTREQUEST_0_AMT=25.00
&PAYMENTREQUEST_0_CURRENCYCODE=USD
&BILLING_AGREEMENT_ID=B-8SX93041AH336464H
&cancelUrl=https://example.com/cancel
&returnUrl=https://example.com/success

Response
--------
TOKEN=EC%2d2B984685J43051234
&ACK=Success
...

Modify the code

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

• (Required) Change cancelUrl to the URL where the buyer is redirected after choosing not to pay with PayPal.
• (Required) Change returnUrl to the URL where the buyer is redirected after choosing to pay with PayPal.
• Change PAYMENTREQUEST_0_PAYMENTACTION to your desired payment action, such as an authorization or a final sale.
• Change PAYMENTREQUEST_0_AMT to the total cost of the transaction.
• Change PAYMENTREQUEST_0_CURRENCYCODE to the country currency of your choice.
• Change L_BILLINGTYPE0 to your type of billing agreement, such as MerchantInitiatedBilling.
• Change BILLING_AGREEMENT_ID to the billing agreement ID that associates the buyer to a billing agreement or reference transaction.

Step result

A successful request returns:

• A &ACK=Success message
• A token ID in the format EC%<id-number>

2. Create a redirect URL

Use the token from the response of the SetExpressCheckout call to create the redirect URL.

Example: https://www.paypal.com/webapps/hermes?token=EC%

3. Redirect the buyer to the approval page

On your checkout page, add an edit link or button using the redirect URL from step 2. When buyers select this option, they're redirected to the buyer approval page.

Step result

The buyer sees a page displaying a list of payment methods associated with the buyer. The buyer can select any payment method for this transaction.

4. (Conditional) Redirect the buyer to the cancel URL

If the buyer didn't authorize changing the payment method, the API redirects them to the cancel URL that the SetExpressCheckout call specified. This means the buyer didn't approve paying with the new payment method.

Capture future payments

You can capture future payments by calling the DoReferenceTransaction API on behalf of the buyer.

However, a DoReferenceTransaction call moves the money from the payment method that's initially associated with existing billing agreement.

Learn more about capturing future payments.

5. Get the required details to process the transaction

If the buyer approves the payment, call the GetExpressCheckoutDetails object to get the PayerID (which uniquely identifies the customer) and other details you might need to process the transaction.

Sample request

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: GET
USER=insert_merchant_user_name_here
&PWD=insert_merchant_password_here
&SIGNATURE=insert_merchant_signature_value_here
&METHOD=GetExpressCheckoutDetails
&VERSION=215
&TOKEN=EC-XXXXXXX

Step result

The API response returns:

• A &ACK=Success message
• A PayerID
• The EC token

6. Capture the payments

Call the DoExpressCheckoutPayment object to capture the payment against the new payment method chosen by the buyer.

Sample requests

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=insert_merchant_user_name_here
&PWD=insert_merchant_password_here
&SIGNATURE=insert_merchant_signature_value_here
&METHOD=DoExpressCheckoutPayment
&VERSION=215
&PAYERID=payerID
&TOKEN=EC-XXXXXXXX

Step result

The API response returns:

• A &ACK=Success message
• A PayerID
• The EC token

PayPal processes the DoExpressCheckoutPayment object. During the process, PayPal captures the payment by transferring the funds from the buyer account to the merchant account. PayPal then sends a confirmation e-mail to the buyer.