Smart Surcharging API

The Smart Surcharging API takes a card BIN, merchant, and payer information and returns surcharging eligibility, required disclosures, and tax requirements. When an amount is provided the exact surcharge and total are returned. Requests authenticate with a secret key.

Determine Surcharging

Disclosure requirements vary by state. Call the Smart Surcharging API before authorization and present the returned disclosure text to the payer with the surcharge amount and updated total.

Request

POST /surcharge/determine
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn

{
  data: {
    amount: Number,
    cardBin: String,
    merchantIdentifier: String,
    payer: {
      address: String,
      city: String,
      state: String,
      postalCode: String,
      country: String
    }
  }
}

Field	Type	Required	Description
`amount`	Number	No	Base amount before surcharge, in dollars (e.g., `1250`)
`cardBin`	String (6 or 8 digits)	Yes	Leading six or eight digits of the payer’s card
`merchantIdentifier`	String	No	Loads merchant jurisdiction and surcharging configuration. When omitted, the rate is `0.03`
`payer`	Object	No	Payer billing address
`payer.address`	String	No	Include apartment, suite, or unit
`payer.city`	String	No
`payer.state`	String (2 letters)	No
`payer.postalCode`	String	No	ZIP or ZIP+4
`payer.country`	String (2 letters)	No	Two-character country code, defaults to `"US"`

Response

{
  data: {
    amount: Number,
    card: {
      bin: String,
      brand: String,
      type: String
    },
    disclosure: String | null,
    eligible: Boolean,
    merchantIdentifier: String | null,
    rate: Number,
    reason: String | null,
    surcharge: Number,
    taxable: Boolean,
    total: Number
  }
}

Field	Type	Description
`amount`	Number	Base amount before surcharge, in dollars (e.g., `1250`)
`card.bin`	String	Leading six or eight digits of the payer’s card
`card.brand`	String	`"americanexpress"`, `"discover"`, `"mastercard"`, or `"visa"`
`card.type`	String	`"credit"`, `"debit"`, or `"prepaid"`
`disclosure`	String \| `null`	Disclosure text to provide cardholder at checkout, `null` when not eligible for surcharging
`eligible`	Boolean	Whether this transaction may carry a surcharge
`merchantIdentifier`	String \| `null`	Merchant identifier configuration applied to this request, `null` if none requested or not found
`rate`	Number	Rate used for `surcharge` as a decimal (e.g., `0.03` for 3%). `0.03` when no `merchantIdentifier` is provided, `0` when card type or jurisdiction does not permit surcharging
`reason`	String \| `null`	`"card_not_eligible"` for debit and prepaid cards, `"jurisdiction_prohibited"` where surcharging is not allowed, or `null` when eligible
`surcharge`	Number	Surcharge in dollars, `0` when not eligible
`taxable`	Boolean	`true` when the surcharge is subject to sales tax, `false` when the surcharge is not taxable or no surcharge applies
`total`	Number	`amount` plus `surcharge` in dollars, before tax

Examples

Eligible Credit Card

POST /surcharge/determine
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn
Content-Type: application/json

{
  "data": {
    "amount": 1250,
    "cardBin": "41111111",
    "merchantIdentifier": "123456789012",
    "payer": {
      "address": "909 Davis Street",
      "city": "Evanston",
      "state": "IL",
      "postalCode": "60201",
      "country": "US"
    }
  }
}

{
  "data": {
    "amount": 1250,
    "card": {
      "bin": "41111111",
      "brand": "visa",
      "type": "credit"
    },
    "disclosure": "To cover the cost of credit card acceptance, we pass on a 3.0% credit card fee. This fee is not more than the cost of accepting these cards. There is no fee for debit cards.",
    "eligible": true,
    "merchantIdentifier": "123456789012",
    "rate": 0.03,
    "reason": null,
    "surcharge": 37.5,
    "taxable": true,
    "total": 1287.5
  }
}

Ineligible Debit Card

POST /surcharge/determine
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnn
Content-Type: application/json

{
  "data": {
    "amount": 1250,
    "cardBin": "40000566",
    "merchantIdentifier": "123456789012",
    "payer": {
      "address": "909 Davis Street",
      "city": "Evanston",
      "state": "IL",
      "postalCode": "60201",
      "country": "US"
    }
  }
}

{
  "data": {
    "amount": 1250,
    "card": {
      "bin": "40000566",
      "brand": "visa",
      "type": "debit"
    },
    "disclosure": null,
    "eligible": false,
    "merchantIdentifier": "123456789012",
    "rate": 0,
    "reason": "card_not_eligible",
    "surcharge": 0,
    "taxable": false,
    "total": 1250
  }
}

Errors

{
  errors: [
    {
      status: Number,
      title: String,
      detail: String
    }
  ]
}

Status	Cause
`400 Bad Request`	Missing or malformed field, see `detail` for mitigation
`401 Unauthorized`	Invalid secret key
`403 Forbidden`	Organization does not have the Smart Surcharging API enabled, contact support@findustryai.com