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)

Copy

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.

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

Copy

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:

• amount. The subtotal from which the surcharge was calculated (in cents).
• surcharge_amount. The amount to be surcharged (in cents). This amount is equal to the surcharge fee or to the amount multiplied by the surcharge rate.
• total_amount. The total amount that should be used when running the final charge (in cents).

Retrieving surcharge information for an account and specified amount

curl -X GET --user public_key: https://api.affinipay.com/bank-accounts/bank_eZX3KANx7JyXDCrMQkdLj/surcharge?amount=500000

Copy

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:

• The value of the total_amount as the amount.
• The surcharge_amount, which enables it to show on the receipt.

Create a charge with surcharge

curl -X POST -H "Content-Type:application/json" --user <secret_key>: https://api.affinipay.com/v1/charges -d '
{
    "method": "veaDMtNmQ8SzfwpcKtUTWA",
    "account_id": "O4dotqecQnuNVM3o9ukr1A",
    "amount": 517500,
    "surcharge_amount": 17500;
    }
}'

Copy

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": 2025
  },
  "cvv_result": "MATCHED",
  "avs_result": "ADDRESS_AND_POSTAL_CODE"
}