Managed Surcharging API

Determine surcharging eligibility, required disclosures, and tax treatment from a card BIN, merchant, and payer address. Requests authenticate by secret key.

Determine Surcharging

Determine surcharging before authorization. With an amount, the response carries the surcharge and total. Present the disclosure text to the payer with the surcharge and total, because disclosure requirements vary by state.

Request

POST /surcharge/determine
Authorization: sk_findustryai_kkkkkkkkkkkk_nnnnn

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

Field	Type	Required	Description
`amount`	Number	No	Base amount before surcharge, in dollars
`cardBin`	String (6 or 8 digits)	Yes	Leading six or eight digits of payer’s card
`merchantIdentifier`	String	No	Merchant whose jurisdiction and surcharging configuration apply. Without it, rate is `0.03`
`payer`	Object	No	Payer billing address
`payer.address`	String	No	Street address, including apartment, suite, or unit
`payer.city`	String	No
`payer.country`	String (2 letters)	No	Country code. Default `"US"`
`payer.postalCode`	String	No	ZIP or ZIP+4
`payer.state`	String (2 letters)	No

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
`card.bin`	String	Leading six or eight digits of payer’s card
`card.brand`	String	`"americanexpress"`, `"discover"`, `"mastercard"`, or `"visa"`
`card.type`	String	`"credit"`, `"debit"`, or `"prepaid"`
`disclosure`	String \| `null`	Disclosure text for payer at checkout, `null` when transaction is not eligible
`eligible`	Boolean	`true` when transaction may carry a surcharge
`merchantIdentifier`	String \| `null`	Merchant whose configuration applies, `null` when omitted or not found
`rate`	Number	Rate for `surcharge` as a decimal. `0.03` without `merchantIdentifier`, `0` when card type or jurisdiction does not permit surcharging
`reason`	String \| `null`	`"card_not_eligible"` for debit and prepaid cards, `"jurisdiction_prohibited"` when jurisdiction prohibits surcharging, or `null` when eligible
`surcharge`	Number	Surcharge in dollars, `0` when not eligible
`taxable`	Boolean	`true` when surcharge is subject to sales tax, otherwise `false`
`total`	Number	`amount` plus `surcharge` in dollars, before tax

Examples

Eligible Credit Card

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

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

{
  "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_nnnnn
Content-Type: application/json

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

{
  "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 Managed Surcharging API enabled, contact support@findustryai.com