Charge with surcharge

A surcharge typically covers the cost to the merchant of accepting a particular means of payment. You can add a surcharge to a charge, although rules on surcharge vary by profession and state.

1: Enable surcharge for hosted fields

You must use hosted fields 1.4 or later to determine which transactions are surchargable. To enable surcharge when implementing hosted fields, add surchargeEnabled: true to the top level of the hosted fields configuration object passed to window.AffiniPay.HostedFields.initializeFields.

Here is an example:

const hostedFieldsConfiguration = {
    publicKey: "m_1234567890",
    surchargeEnabled: true,
    input: {
      …
    }
  }
  window.AffiniPay.HostedFields.initializeFields(hostedFieldsConfiguration, callback)

When surcharge is enabled, hosted fields will provide a new surchargeable field in its state. The hosted fields library requires at least 12 digits in the card number input to trigger the surcharge decision making process.

StatusDescription
surchargeable: trueThe card can be surcharged
surchargeable: falseThe card cannot be surcharged
surchargeable: “unknown”A surcharge decision has not been made

2: Retrieve the bank account ID

Before you can retrieve surcharge information, you must retrieve the bank account ID for the account for which you’re implementing surcharge. The bank account ID has a prefix of bank_. You’ll provide it as the bank_account_id when you retrieve the surcharge amount.

Example request: Retrieving a list of bank accounts for the merchant
curl -X GET -H "Content-Type:application/json" "Authorization: Bearer <access_token>" https://api.affinipay.com/bank-accounts
Example response
[
  {
    "id": "bank_eZX3KANx7JyXDCrMQkdLj",
    "name": "Chase",
    "bank_name": "JPMorgan Chase & Co.",
    "trust": false,
    "account_id": "*****1234",
    "currency": "USD",
    "processing_accounts": [
      {
        "id": "edqJpNHmSPqmpCepvkP2SA",
        "name": "eCheck",
        "required_payment_fields": "name",
        "type": "bank"
      },
      {
        "id": "O4dotqecQnuNVM3o9ukr1A",
        "name": "card",
        "required_payment_fields": "cvv,postal_code",
        "accepted_card_types": "VISA,MASTERCARD,AMERICAN_EXPRESS,DISCOVER",
        "cvv_policy": "OPTIONAL",
        "avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_cvv_policy": "OPTIONAL",
        "swipe_avs_policy": "SUBMIT_IGNORE_RESULT",
        "swipe_required_payment_fields": "cvv",
        "type": "card"
      }
    ]
  }
]

3: Retrieve the surcharge total_amount

Next, retrieve the surcharge rate and fee for the specified bank account. The surcharge rate is set at the merchant level and can be a percentage or a flat rate. This includes rates and fees for card, bank, and loan types, when available. If a bank account has more than one of the same type, the first one is returned. If the merchant does not have surcharge enabled, a null set is returned.

When an amount is specified, the response includes:

Retrieving surcharge information for an account and specified amount
curl -X GET --user public_key: https://api.affinipay.com/v1/bank_accounts/bank_eZX3KANx7JyXDCrMQkdLj/surcharge?amount=500000
Example response
[
  {
      "type": "card",
      "surcharge_rate": 350,
      "surcharge_fee": 0,
      "amount": 500000,
      "surcharge_amount": 17500,
      "total_amount": 517500
  },
  {
      "type": "bank",
      "surcharge_rate": 0,
      "surcharge_fee": 1001,
      "amount": 500000,
      "surcharge_amount": 1001,
      "total_amount": 501001
  }
]

4: Charge with surcharge

Finally, submit a charge that includes:

Create a charge with surcharge
curl -X POST -H "Content-Type:application/json" --user <secret_key>: https://api.chargeio.com/v1/charges -d '
{
    "method": "veaDMtNmQ8SzfwpcKtUTWA",
    "account_id": "O4dotqecQnuNVM3o9ukr1A",
    "amount": 517500,
    "surcharge_amount": 17500;
    }
}'
Example response
{
  "id": "Avwol61UQL6L7u9KFFNQeA",
  "created": "2022-09-30T17:09:12.460Z",
  "modified": "2022-09-30T17:09:12.497Z",
  "client_id": "43d3aea07dfef86f74a2466ddb87dcdd6ea3fc63b9961e5867200d441928f8",
  "account_id": "O4dotqecQnuNVM3o9ukr1A",
  "status": "AUTHORIZED",
  "auto_capture": true,
  "amount": 517500,
  "currency": "USD",
  "authorization_code": "FECDKS",
  "surcharge_amount": 17500,
  "amount_refunded": 0,
  "type": "CHARGE",
  "method": {
      "name": "Ellen Grace",
      "address1": "111 New Street",
      "postal_code": "78756",
      "email": "egrace@example.com",
      "type": "card",
      "number": "************4242",
      "fingerprint": "5rxmQGOSB7jqlPd-vbux",
      "card_type": "VISA",
      "exp_month": 10,
      "exp_year": 2023
  },
  "cvv_result": "MATCHED",
  "avs_result": "ADDRESS_AND_POSTAL_CODE"
}