When processing payments via the Payment Component, you can enable BIN lookup to retrieve information about the card to compliantly apply surcharging with four steps:

• Enable BIN lookup and configure your merchants billing profiles
• Configure the payin config to request BIN lookup
• Configure the Payment Component to respond to the BIN lookup
• Configure the Deposit Report Component to show the billing details

Configure the merchant

In the Rainforest Sandbox and Production environments, Rainforest will need to enable this feature for your platform. Once you're ready to enable, reach out to [email protected] and Rainforest will help you with your merchant's billing profile setup and enabling BIN lookup for your merchants.

Set the BIN lookup fee

A BIN lookup fee is applied for every BIN lookup request. BIN lookup fees can be passed onto the merchant via the merchant billing profile. See the billing section for additional information on how the BIN lookup fee is billed to the merchant.

We can update the BIN lookup fee on an existing billing profile that currently has the BIN lookup fee set to $0. Or head over to the Rainforest Platform Portal to create a new billing profile with a BIN lookup fee.

Enable your platform

Reach out to [email protected]and Rainforest will enable your platform for BIN lookup. Once we've enabled the feature, the payin config must be configured to request BIN lookup when the user enters their card number into the Payment Component.

Configure the payin

BIN lookup is enabled by passing the allow_bin_lookup value of true on the create payin config request.

{
    "merchant_id": "{{merchant_id}}",
    "idempotency_key": "{{idempotency_key}}",
    "amount": 10000,
    "currency_code": "USD",
+   "allow_bin_lookup": "true"
}

The allow_bin_lookup of true tells Rainforest to retrieve BIN information once the user enters their card number into the Payment Component.

Configure the payment component

Hide the submit button

When embedding the Payment Component in your platform, you should hide the submit button so that you can listen to the results of the BIN lookup and make a decision, such as removing the surcharge if the user entered a debit card.

First, render the component with the hide-button attribute, so that it no longer renders the Rainforest-controlled button. Then render your own submit button and add appropriate styling and behavior to it. Ensure your submit button is not enabled until the Payment Component is valid and you're ready to process the payment.

  <rainforest-payment
      session-key="REPLACE_ME"
      payin-config-id="REPLACE_ME"
+     hide-button
  ></rainforest-payment>

+ <input type="submit" id="submit" disabled>

Listen to the BIN lookup event

If BIN lookup was requested in the payin config, the Payment Component will emit the bin-lookup every time the user enters the full card number into the Payment Component. This means if the user enters one card number, then changes their mind and enters another card number, the Payment Component will emit 2 bin-lookup events.

The bin-lookup event will return a payload in the format of the response from the BIN lookup endpoint:

{
    "status": "SUCCESS",
    "data": {
        "bin_lookup_id": "sbx_bin_2xSzUXqaaPMX684vEXOSDVb96nB",
        "billable_merchant_id": "sbx_mid_2xSzXQoAprorB7EZ0sFBvEKTy7y",
        "bin": "41111111",
        "brand": "VISA",
        "type": "CREDIT",
        "last_4": "1111",
        "country": "US",
        "is_business": false,
        "is_healthcare": false
    },
    "errors": null
}

Listen to this event and parse the event data:

const component = document.getElementById('payment-component');
component.addEventListener('bin-lookup', function (data) {
    if (data.detail[0].type) {
        console.log('Type: ' + data.detail[0].type);
    }
});

International and Business Surcharging

If the merchant wants to surcharge on International cards or Business cards, then the platform should utilize the country and is_business fields in the BIN lookup response.

Update the payin config

If the user's card number is determined to be a debit card, and per surcharging compliance if the surcharge needs to be removed, the payin config can be updated without having to re-render the Payment Component and lose the information the user has already entered.

You should create a new payin config with the new amount of the payin, then update the config attribute by using the JavaScript DOM attribute API:

component.removeAttribute('payin-config-id');
component.setAttribute('payin-config-id', newPayinConfigId;

Confirm the payin config was updated by listening to the config-update-accepted event before processing the payin.

Submit the payin

Once the payment is ready to be submitted and the user has hit your submit button, you can call the Payment Component's submit method.

component.submit();

📘

Surcharging compliance

It's important that you follow all the surcharging regulations within your checkout flow. Ensure you are displaying the surcharging fees and the end user has been notified of the surcharge.

Configure deposit report for billing

BIN lookups do incur an additional billing fee. If you're passing the fee onto the merchant, then the deposit will include a billing adjustment.

Configure the Deposit Report Component to include the memo column in the Deposit Details activity report to provide the context on the billing adjustment to your merchant.

<rainforest-deposit-report
    activity-columns='[
    {"name":"Created","type":"builtin","value":"created_at"},
    {"name":"Type","type":"builtin","value":"type"},
    {"name":"ID","type":"builtin","value":"id"},
    {"name":"Memo","type":"builtin","value":"memo"},
    {"name":"Customer","type":"builtin","value":"billing_contact_name"},
    {"name":"Method","type":"builtin","value":"payment_method"},
    {"name":"Amount","type":"builtin","value":"gross_amount"},
    {"name":"Fees","type":"builtin","value":"billing_fees_amount"},
    {"name":"Net","type":"builtin","value":"net_amount"}
]'
></rainforest-deposit-report>