Apply surcharge

Last updated: September 10, 2023

A surcharge is an additional fee you can add to credit card payments to help you offset the cost of processing. Surcharges are permitted by Visa and Mastercard in the United States, subject to certain exceptions and strict guidelines.

Note

This feature is available for merchants in the United States only.

To apply a surcharge, you must comply with the following:

Ensure surcharges are allowed in your state.
Follow state and local laws.
Only credit card payments are eligible.
The surcharge amount must not exceed your cost of acceptance for the credit card.
Disclose the surcharge amount on the receipt and at the checkout. This ensures that the cardholder is fully aware of the total cost of the transaction and the surcharge applied.

To enable surcharging, contact your account manager or request support.

When you call the Request a payment or payout endpoint:

Provide the processing.surcharge_amount field.
Ensure that the total amount includes the surcharge.

For partial captures, you must also include the surcharge amount in the capture request. If the surcharge amount is applied in the payment request but not in the partial capture, the surcharge is not submitted to the card scheme.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "card",
4    "number": "4010050999999999904",
5    "expiry_month": 12,
6    "expiry_year": 2026
7  },
8  "amount": 10100,
9  "currency": "USD",
10  "processing": {
11    "surcharge_amount": 100
12  }
13}

If the authorization was:

Successful – The approved field in the response returns true: "approved": true.
Unsuccessful – The payment may have used an invalid or expired card, or a valid card with insufficient funds.

If you received a 202 response, the payment is asynchronous and requires a redirect. For example, if the payment requires 3D Secure.

Information

For more information about the response, see also:

API response codes – For unsuccessful authorizations
AVS codes
CVV codes and descriptions

The status field can have the following values:

Authorized
Card Verified
Captured
Declined
Paid
Pending – 3D Secure payments only


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 10200,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "type": "card",
20    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
21    "billing_address": {
22      "address_line1": "123 Anywhere St.",
23      "address_line2": "Apt. 456",
24      "city": "Anytown",
25      "state": "AL",
26      "zip": "123456",
27      "country": "US"
28    },
29    "phone": {
30      "country_code": "+1",
31      "number": "555 123 4567"
32    },
33    "last4": "9904",
34    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
35    "bin": "424242"
36  },
37  "customer": {
38    "id": "cus_udst2tfldj6upmye2reztkmm4i",
39    "email": "[email protected]",
40    "name": "John Smith"
41  },
42  "processed_on": "2024-09-10T10:11:12Z",
43  "reference": "ORD-5023-4E89",
44  "processing": {
45    "retrieval_reference_number": "909913440644",
46    "acquirer_transaction_id": "440644309099499894406"
47  },
48  "eci": "06",
49  "scheme_id": "489341065491658",
50  "links": {
51    "self": {
52      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
53    },
54    "action": {
55      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
56    },
57    "void": {
58      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
59    },
60    "capture": {
61      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
62    }
63  }
64}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "John Smith"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "instruction": {
15    "value_date": "2024-08-25"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
20    },
21    "redirect": {
22      "href": "https://api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4"
23    }
24  }
25}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Apply surcharge

Note

Before you begin

Apply a surcharge

Request example

Response example

Information