Apply surcharge

Last updated: October 11, 2023

Surcharge is an additional fee added to a cardholder’s transaction when they use a credit card. This helps you offset the cost of processing. Adding a surcharge is permitted by Visa and Mastercard in the United States with certain exceptions and strict guidelines.

Note

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

To apply a surcharge, you're required to comply with the following:

You’re responsible for determining if surcharge is allowed in your state.
You must follow state and local laws.
Only credit card transactions are permitted.
The surcharge amount must not exceed your cost of acceptance for the credit card.
You must disclose the surcharge amount on each receipt and at the checkout. This ensures that the cardholder is fully aware of the total cost of the transaction and the surcharge applied.

If you’d like to enable surcharging, contact your Account Manager or [email protected].

Submit the surcharge amount as a separate field, and ensure that the total amount includes the surcharge.

For partial captures, the surcharge amount must be submitted in the capture request. If the surcharge amount is sent in the payment request and a partial capture follows without the surcharge amount, no data will be 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}

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid or expired card. A valid card with an insufficient available balance will also cause the payment to fail.

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

Information

The following pages can help you understand the response message:

CVV codes and descriptions
AVS codes
API response codes (if the authorization was unsuccessful)

The possible values for the status field include Authorized, Pending, Card Verified, Captured, Declined, or Paid. Note that Pending only applies to 3D Secure payments.


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": "2019-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": "2020-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

Submit a surcharge

Request example

Response example

Information