---
title: "View surcharge recommendation"
method: POST
path: "/pay/v3/surcharge"
tags: ["Ecommerce"]
---

# View surcharge recommendation

`POST /pay/v3/surcharge`

Allows you to get a surcharge recommendation for a transaction based on the customer's billing state and information about the payment. The response provides information about whether surcharging is recommended or what restrictions apply for surcharging with the transaction.

If the saved card token includes `data.customer.billToState`, you only need to include that token in the request. Otherwise, you must explicitly include `data.customer.billToState` and just one of the following parameters:
- `card.firstSix`
- `card.pan`
- `tokenex.token`
- `tokenex.firstSix`


<!-- theme: info -->
> 📘 Note
>
> In order to use this endpoint, the Surcharging feature must be enabled for the account and the new agreement must be accepted (which displays upon logging into the [Dashboard](https://dashboard.nexiopaysandbox.com/)).

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you must use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).
> 
> If the saved card token includes `data.customer.billToState`, you only need to include that token in the request. Otherwise, you must include `data.customer.billToState` plus just one of the following parameters: `card.firstSix`, `card.pan`, `tokenex.token`, or `tokenex.firstSix`.


<div style="display:none;">

## Request parameters
- data
- data.amount
- data.surcharge
- data.currency
- data.allowedCardTypes
- data.cart
- data.cart.items
- data.cart.items.item
- data.cart.items.description
- data.cart.items.quantity
- data.cart.items.price
- data.cart.items.type
- data.customer
- data.customer.customerRef
- data.customer.orderNumber
- data.customer.orderDate
- data.customer.invoice
- data.customer.firstName
- data.customer.lastName
- data.customer.birthDate
- data.customer.nationalIdentificationNumber
- data.customer.billToAddressOne
- data.customer.billToAddressTwo
- data.customer.billToCity
- data.customer.billToCountry
- data.customer.billToPhone
- data.customer.billToPostal
- data.customer.billToState
- data.customer.createdAtDate
- data.customer.email
- data.customer.phone
- data.customer.shipToAddressOne
- data.customer.shipToAddressTwo
- data.customer.shipToCity
- data.customer.shipToCountry
- data.customer.shipToPhone
- data.customer.shipToPostal
- data.customer.shipToState
- data.customFields
- data.customFields.exampleKey
- data.description
- data.descriptor
- data.descriptor.name
- data.descriptor.address
- data.descriptor.city
- data.descriptor.state
- data.descriptor.postal
- data.descriptor.country
- data.descriptor.phone
- data.descriptor.url
- data.descriptor.merchantId
- data.descriptor.mcc
- data.lodging
- data.lodging.advanceDeposit
- data.lodging.checkInDate
- data.lodging.checkOutDate
- data.lodging.noShow
- data.lodging.roomNumber
- data.lodging.roomRate
- paymentMethod
- tokenex
- tokenex.token
- tokenex.firstSix
- tokenex.lastFour
- card
- card.cardType
- card.cardHolderName
- card.encryptedNumber
- card.expirationMonth
- card.expirationYear
- card.securityCode
- card.firstSix
- card.lastFour
- card.classification
- card.businessNumber
- card.password
- card.pan
- card.expirationMonth
- card.expirationYear
- tokenex.token
- tokenex.firstSix
- recurringId
- shouldUpdateCard
- merchantId
- processingOptions
- processingOptions.merchantId
- processingOptions.check3ds
- processingOptions.paymentType
- processingOptions.customerRedirectUrl
- processingOptions.checkFraud
- processingOptions.paymentOptionTag
- processingOptions.retryOnSoftDecline
- processingOptions.shouldUseFingerprint
- processingOptions.verboseResponse
- clientIp
- isAuthOnly
- installment
- installment.period
- external3ds
- external3ds.eci
- external3ds.cavv
- external3ds.xid
- external3ds.version

## Response parameters
- surchargeAllowed
- cardType
- message

</div>

## Request body

- union
  - object — This option allows you to view a surcharge recommendation based on the `card.firstSix` parameter.
    - `data` object, required — Customer data for viewing surcharge recommendation.
      - `customer` object, required — Required billing state for viewing a surcharge recommendation.
        - `billToState` string, required — The state or province on file with the card provider. This must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)) for the United States.
    - `card` object, required — Card information.
      - `firstSix` string, required — The first six digits of the card number.
  - object — This option allows you to view a surcharge recommendation based on the `card.pan` parameter.
    - `data` Data, required — unresolved $ref
    - `card` object, required — Full card number. <!-- theme: warning --> > 🛑 Important > > Sending full card numbers could increase PCI scope.
      - `pan` number, required — The full card number. You can send this value as a number or as a string. For information about test card numbers and values you can use, see the documentation for the specific [gateway/connection integration guide](https://docs.nexiopay.com/docs/connections). <!-- theme: warning --> > 🛑 Important > > Sending full card numbers could increase PCI scope.
  - object — This option allows you to view a surcharge recommendation based on the `tokenex.firstSix` parameter.
    - `data` Data, required — unresolved $ref
    - `tokenex` object, required — The first six digits of the card number for a previously saved [card token](https://docs.nexiopay.com/reference/savecardtoken).
      - `firstSix` FirstSix, required — unresolved $ref
  - object — This option allows you to view a surcharge recommendation based on the `tokenex.token` parameter.
    - `tokenex` object, required — A previously saved [card token](https://docs.nexiopay.com/reference/savecardtoken).
      - `token` string, required — The TokenEx card token. This is the saved card token.
    - `data` object — Customer data for viewing surcharge recommendation.
      - `customer` object — Billing state information for viewing a surcharge recommendation. You must provide a state value here if it is not already saved in the card token referenced by `tokenex.token`.
        - `billToState` string — **Conditionally required.** If the `billToState` value is saved in the card token referenced by `tokenex.token`, you do not need to include the value here. However, if you do not include the value here and the saved card token does not contain the `billToState` information, the system returns an error. This value is the state or province on file with the card provider. It must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)) for the United States.

## Response `200`

Success

- object — The response from a successful request for a surcharge recommendation.
  - `surchargeAllowed` boolean — Indicates whether a surcharge can be added to a transaction using the payment method indicated in the request.
  - `cardType` 'amex' | 'discover' | 'mastercard' | 'visa' — The card type, as determined by the payment method indicated in the request. Card types have different requirements and recommendations for surcharging and surcharge amounts. The system only returns this parameter when `surchargeAllowed` is `true`.
  - `message` string — When `surchargeAllowed` is `false`, the system also includes a message describing why surcharging with the given payment method is not recommended. When `surchargeAllowed` is `true`, the system does not return this parameter. Use the message information to determine how to handle surcharging for a transaction with the payment method indicated in the request. - "Billing state does not allow surcharges" - Some states do not allow surcharges with a transaction. Nexio recommends against surcharging in this situation. - "Surcharges can only be processed on credit cards" - If a surcharge is included in a transaction with the indicated payment method, the merchant could be subject to fines from the card brands for surcharging non-credit-card card types. Nexio recommends that the merchant not include a surcharge or that the merchant request a different card from the customer. - "Surcharges can only be processed on US credit cards" - Surcharging is allowed only with credit cards issued to a customer in the United States. If a surcharge is included in a transaction with the indicated payment method, the transaction will probably fail.
  - `random-nnnnnnn` RandomNnnn — unresolved $ref

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)