Ecommerce

View surcharge recommendation

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

📘 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).

⚠️ Try It

To use the Try It feature for this endpoint, you must use the credentials for your Sandbox API user.

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.

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>

post/pay/v3/surcharge

Request body

Example request

{
  "data": {
    "customer": {
      "billToState": "PA"
    }
  },
  "card": {
    "firstSix": "479300"
  }
}

Response

Success

surchargeAllowedboolean

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.

messagestring

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-nnnnnnnRandomNnnn — unresolved $ref

Changes

No recorded changes to this endpoint across all 1 revision of this API.