Overcharge handling

DocsCurrentStandard

Last updated: Oct 25th, 10:12am

In PSD2 rules, an overcharge is when a customer is charged an amount that is more than what they agreed to pay for a product or service. The payment service provider applies strong customer authentication (SCA) to the final amount of the transaction or declines the transaction if the final amount is higher than the amount the buyer agreed to when initiating the transaction. PayPal defines SCA as re-authorization in this case. For more information, see New overcapture requirements. If you charge more than the amount the buyer has approved to pay during checkout, the Capture Order API returns a PAYER_ACTION_REQUIRED error. The API provides a URL redirecting the buyer to re-approve the new amount.

How it works

The payer checks out and approves the amount presented on PayPal pages.

A higher amount than the payer approved is authorized and captured.

A PAYER_ACTION_REQUIRED error is returned.

Optional: Use the Confirm Payment Source API to provide a return_url or cancel_url. The API can also block shipping address changes in which "shipping_preferences=SET_PROVIDED_ADDRESS".

Redirect the buyer to the payer-action URL.

The buyer approves the higher amount and is redirected to the return URL.

The order is captured.

Integration

The flow chart shows the following integration steps:

Create an order with the Orders V2 API.

The smart button redirects the buyer to PayPal.

The buyer approves the order on the PayPal checkout pages.

The PayPal checkout window closes. The buyer is returned to merchant’s checkout.

The buyer selects a shipping method and confirms other details.

Use the Patch Order API to update the shipping costs, shipping address, and other details.

Capture the order. For more information on how to capture an order, see Orders V2 API.

If capture fails with the error, http422 PAYER_ACTION_REQUIRED, redirect the buyer to PayPal using the payer-action URL.

Buyer re-approves the order and is redirected to the return URL.

Capture the order. For more information on how to capture an order, see Orders V2 API.

Sample request - Patch Order

1[{
2  "op": "replace",
3  "path": "/purchase_units/@reference_id=='default'/amount",
4  "value": {
5    "currency_code": "USD",
6    "value": "101",
7    "breakdown": {
8      "item_total": {
9        "currency_code": "USD",
10        "value": 1.00
11      },
12      "shipping": {
13        "currency_code": "USD",
14        "value": 100.00
15      }
16    }
17  }
18}]

The request returns the HTTP 204 status code.

Sample request - Capture Order

For sample requests, see the Capture Order endpoint of the Orders V2 API.

Sample response - successful capture

A successful request returns the following response:

1{
2  "id": "5KM89009KL896372M",
3  "intent": "CAPTURE",
4  "status": "COMPLETED",
5}

Sample response - overcapture error

An overcapture error will give you an HTTP 422 error code response, which means that payer action is needed.

1{
2    "name": "UNPROCESSABLE_ENTITY",
3    "details": [{
4      "issue": "PAYER_ACTION_REQUIRED",
5      "description": "Payer needs to perform the following action before proceeding with payment."
6    }],
7    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
8    "debug_id": "9495b4f46e3ff",
9    "links": [{
10        "href": "https://developer.paypal.com/docs/api/orders/v2/#error-PAYER_ACTION_REQUIRED",
11        "rel": "information_link",
12        "method": "GET"
13      },
14      {
15        "href": "https://www.sandbox.paypal.com/checkoutnow?token=XYZ",
16        "rel": "payer-action",
17        "method": "GET"
18      }
19    ]
20  }

Sample request - confirm payment source

Set the shipping_preference to SET_PROVIDED_ADDRESS to confirm the payment source.

You need to pass return_url and cancel_url if you don't provide them in the Create Order API call.

1{
2  "payment_source": {
3    "paypal": {
4      "experience_context": {
5        "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
6        "shipping_preference": "SET_PROVIDED_ADDRESS",
7        "user_action": "PAY_NOW",
8        "return_url": "https://example.com/returnUrl",
9        "cancel_url": "https://example.com/cancelUrl"
10      }
11    }
12  }
13}

Sample response

1{
2  "id": "3VD082734S317882J",
3  "intent": "CAPTURE",
4  "status": "PAYER_ACTION_REQUIRED",
5  "payment_source": {
6    "paypal": {}
7  },
8  "purchase_units": [{
9    "reference_id": "default",
10    "amount": {
11      "currency_code": "USD",
12      "value": "101.00",
13      "breakdown": {
14        "item_total": {
15          "currency_code": "USD",
16          "value": "1.00"
17        },
18        "shipping": {
19          "currency_code": "USD",
20          "value": "100.00"
21        }
22      }
23    },
24    "payee": {
25      "email_address": "buyer@example.com",
26      "merchant_id": "1234567890"
27    },
28    "description": "Payment for order",
29    "custom_id": "1234567890",
30    "invoice_id": "JAkqXHx5UlAvzHf",
31    "items": [{
32      "name": "shoes",
33      "unit_amount": {
34        "currency_code": "USD",
35        "value": "1.00"
36      },
37      "quantity": "1",
38      "description": "Nadfsdf"
39    }],
40    "shipping": {
41      "name": {
42        "full_name": "Firstname Lastname"
43      },
44      "address": {
45        "address_line_1": "123 Main St",
46        "admin_area_2": "Anytown",
47        "postal_code": "12345",
48        "country_code": "US"
49      }
50    }
51  }],
52  "links": [{
53      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/3VD082734S317882J",
54      "rel": "self",
55      "method": "GET"
56    },
57    {
58      "href": "https://www.sandbox.paypal.com/checkoutnow?token=3VD082734S317882J",
59      "rel": "payer-action",
60      "method": "GET"
61    }
62  ]
63}