Gateway Change Process

A gateway change may allow you to update the payment gateway that your existing Advanced Billing site is connected to without requiring your customers to re-enter their credit card information. There are also situations where a merchant is migrating to Advanced Billing from a legacy system and changing payment gateways simultaneously. It is best to provide a seamless transition for a better customer experience.

Advanced Billing does not store full credit card numbers.

This information is stored by your third party payment gateway.
When a customer enters their credit card information at signup, or updates the existing credit card on file, Advanced Billing sends the full credit card information to the payment gateway who then stores the data and sends back a “vault token”.
Vault tokens are stored in Advanced Billing and are what we use to link the customer in Advanced Billing to the card data associated with that customer in your payment gateway.

When you change payment gateways, the credit card information stored in your beginning gateway is not stored in your ending gateway. In order to change gateways without requiring your customers to re-enter their credit card information, you will need to ensure your beginning gateway can export credit card data and your ending gateway can import that data to generate new vault tokens. The new vault tokens will need to be provided to Advanced Billing so we can update them in our database while updating the gateway credentials and forcing the gateway change.

Please note: If your beginning gateway does not support data portability and is unable to export the stored credit card information, you will need to ask your customer’s to re-enter their credit cards when you switch to a new payment gateway.

Requirements

Advanced Billing requires a 1-month notice to schedule a gateway change.
Your beginning gateway must support data portability (ability to export your customers credit card data). If you are unsure, please contact your beginning gateway to verify.
Your ending gateway must support data imports either by receiving the file from the beginning gateway or through their API. If you are unsure, please contact your ending gateway to verify. Additionally, if your ending gateway imports the file from your beginning gateway, they must also send Advanced Billing a mapping file that links the customer’s old vault token to the new vault token generated during import.
Coordinate a data export with your beginning gateway, and provide Advanced Billing with the scheduled date of this export.
The site must be using the Multi-Gateway feature. Once a gateway change is requested, this feature will be turned on for your site.

IMPORTANT: Do NOT export from the beginning gateway until the Advanced Billing site has been pointed to the ending gateway. Credit card data for all new signups WILL be left behind.

Coordinate with your ending gateway, and provide us with an estimated delivery date of when your ending gateway can send Advanced Billing the token mapping file.
Provide the contact information (email addresses) for the contacts at your beginning gateway and your ending gateway.
Provide the name of your Advanced Billing subdomain(s) where the gateway change will take place.
Verify your ending gateway credentials are working properly in Advanced Billing.

The merchant will then be required to take the following steps:

Add the ending gateway and connect it by entering your credentials.
Perform a test signup in the Admin UI using a real credit card to ensure new signups will process successfully through your ending gateway.
Make the ending gateway the default for the payment types that are being moved.

It is the merchant’s responsibility to ensure ending gateway credentials are correct and the new payment gateway is working as expected.

Scenario A

Existing Advanced Billing Merchants Ending Gateway Receives File From Beginning Gateway

The vast majority of gateway changes for existing Advanced Billing merchants will fit into this category.

Your beginning gateway has the ability to export your customers credit card data and your ending gateway is able to receive the file, perform the import, and tokenize the cards.

You will configure the ending gateway as the default gateway for the payment types being moved.
Signups and updates using Advanced Billing-hosted pages will flow into the default gateway.
Renewals will continue processing in the beginning gateway. (If you do NOT want this to happen, please notify support.)
Your beginning gateway should perform an export and deliver the file to the ending gateway.
The ending gateway will import the credit card data and deliver a mapping file to Advanced Billing from the the beginning gateway tokens to the ending gateway tokens.
Advanced Billing will briefly delay renewals and perform a “token swap”, replacing the beginning gateway tokens with the ending gateway tokens.

Cost for Scenario A

Free of charge

Scenario B

Existing Advanced Billing Merchants Ending Gateway Requires Import Through API

In some cases, the beginning gateway is able to provide an export of your customers’ credit card data, but your ending gateway does not support receiving the file and performing the import on your behalf.

Because full credit card numbers should only be handled by level 1 PCI compliant entities, it is suggested the file be sent directly to Advanced Billing and we can perform the API import on your behalf.

You will configure the ending gateway as the default gateway for the payment types being moved.
Signups and updates using Advanced Billing-hosted pages will flow into the default gateway.
Renewals will continue processing in the beginning gateway. (If you do NOT want this to happen, please notify support.)
The beginning gateway will perform the export and send the secure file to Advanced Billing directly.
Advanced Billing will format the information and perform the import to tokenize the credit cards at the ending gateway.
Advanced Billing will briefly delay renewals and perform a “token swap”, replacing the beginning gateway tokens with the ending gateway tokens

Cost for Scenario B

Advanced Billing will import the credit card data using the file received by the beginning gateway. The import and any required formatting will be charged at a rate of $250/hr.

Scenario C

Merchant Is Migrating From Another Legacy System and Ending Gateway Requires Import Through API

If you’re migrating to Advanced Billing from another system, please review the migration process.

If the ending gateway does not support receiving the file from the beginning gateway and performing the import on your behalf, the file will need to be sent directly to Advanced Billing. Advanced Billing will then complete a full import of card data along with customers and subscriptions.

The beginning gateway will perform the export and send the secure file to Advanced Billing directly.
The merchant will be required to export their customer and subscription data from their current system and format it in the required Advanced Billing CSV import format. The completed file will need to be provided to Advanced Billing prior to the card data being received from the beginning gateway.
Advanced Billing will run a script to merge the CSV import file provided by the merchant and the file provided by the Beginning Gateway containing the full credit card numbers of each customer.
Advanced Billing will perform the CSV import or API import if you require component allocations at the time of import.
Advanced Billing will make a note of any errors or issues during import and work with the merchant to resolve these errors, if possible.

Cost for Scenario C

CSV import: $150/hr for the merging the beginning gateway file with the CSV import file provided by the merchant and reformatting and $150/hr for the actual CSV import once the file is formatted properly.

API import: $250/hour for the entire process

Scenario D

Merchant Is Migrating From Another Legacy System and Ending Gateway Receives File From Beginning Gateway

If your ending gateway supports receiving the card data file from the beginning gateway and performing the import on your behalf to tokenize the credit cards, you will be able to import your customers, subscribers and new vault tokens into Advanced Billing using the CSV import or API import. Advanced Billing does not need to be notified in this scenario.

The beginning gateway will perform the credit card data export and send the secure file to the ending gateway.
The ending gateway will import the credit card data and tokenize the cards.
The merchant will be required to export subscription data from their current system as well as the vault tokens in the Ending Gateway and format it in the required Advanced Billing CSV import or API import format.
Merchant will perform the Import.

Cost for Scenario D

Self-service Import: Free of charge

If you require Advanced Billing’s assistance, this is a paid service. Please review the CSV import assistance or Developer Assistance pricing for API imports.

Scenario E

Migration over time as cards expire and are updated

If you would like to direct all new signups and updates to a new gateway, you can configure the new gateway as the default gateway for the relevant payment types. Renewals will still work, however the next time the customer updates their payment method, the update will essentially be adding a new payment method in the new default gateway. Keep in mind that if you are using Chargify.js for card updates and you specify a gateway handle - you need to change it to the new gateway as well. In this way, you can slowly migrate to a new gateway without involving the gateways to export and import payment details. This may be useful if your beginning gateway does not have the ability to export the payment details.

Cost for Scenario E

Free of charge

Available Dates, Communication, Timelines, and Deadlines

The scheduled date must be a business day, Monday through Thursday. We do not perform gateway changes on Fridays, weekends, or holidays.
Once the date has been scheduled, Advanced Billing will delay your subscription renewals on the scheduled date.
If you need to cancel, please notify us immediately.
If you need to reschedule, the new date is subject to the required 2 weeks notice.

Based on the information you provide to us, Advanced Billing will provide a schedule outlining the estimated completion date of each step of your gateway change, and communicate with you each step of the way in the designated support ticket.

Before beginning the gateway change process, a deadline will be established when we must receive the mapping file from your ending gateway. This deadline will be set to one week after we originally delay your renewals. We will provide you with the specific date and time of the deadline, so you know when to expect your renewals to resume.

There may be cases where there is a delay on the payment gateway side (ie. the token mapping file is not sent to Advanced Billing by the date expected). Therefore, the deadline will be missed. If necessary, Advanced Billing will push out your renewals another week to ensure that you do not experience any failed renewals. Any scheduled steps that have not occurred yet will be pushed out in parallel.

No other changes will be permitted once the process has begun.

Submitting your request

To get started, please submit a gateway change request by emailing support@maxio.com or submit a request while logged into the application to indicate you wish to change your gateway.

Please include the following information:

Indicate which gateway change scenario is applicable (A, B, or C). You will not need to notify Advanced Billing for scenario D unless you require paid import assistance.
Name of beginning gateway
Name of ending gateway
Scheduled date of your beginning gateway data export – please note that this must be at least one month ahead of the date you submit your request
The name of your Advanced Billing subdomain(s) where the change will take place
A link to the payment where you have successfully verified your ending gateway credentials

Once we receive your request, we will reply with additional details, instructions and timeline tailored to your specific needs.

Handling Refunds When Changing Gateways

As long as your beginning gateway account is still functioning, you may be able to process refunds for transactions created prior to the gateway change through Advanced Billing. This will depend on your relationship with that gateway and how funds are managed with them.

If you still have access to a web portal for your beginning gateway, you may be able to process the refund there. Or, once the cards have been imported to the ending gateway, you may be able to process an ‘unlinked refund’ to the customer’s card. Otherwise, you may need to send the customer a check or use some other manual method of returning the funds to them. If funds are returned to the customer, you should record an external refund in Advanced Billing so that the subscription details are correct.