Integrating with Hyperwallet

Learning Experience Team

August 19, 2021 18:01

Hyperwallet is a platform owned by PayPal. They provide you with a fast, efficient, and transparent way to distribute funds to your Associates. You can integrate Hyperwallet as a commissions payout merchant or standard payment processor. To set up your integration, you need to enter the credentials provided to you by Hyperwallet in Corporate Admin.

Basic E-Wallet Payment Process

When an Associate receives commission payments, the system funds their E-Wallet hosted by Hyperwallet. The funds are available to purchase more of your products if configured to do so.

The Associate selects their inventory items and begins the checkout process.

The Associate selects "Hyperwallet" as the payment provider and clicks the Checkout button.

Hyperwallet displays the Associate’s available balance here as well. A balance of "-1" means the Associate’s account is not yet set up. The Associate should contact you to resolve this issue.

The order processing system retrieves the balance from the Associate’s account to verify funds and then sends the request to charge.
Hyperwallet processes the request and sends back confirmation of acceptance (or denial if there are insufficient funds).

Before You Start

Contact Hyperwallet to set up an account.
For testing on Hyperwallet’s side, reach out to your account manager and gain credentials to their Sandbox site. On the DirectScale side, if you have a Stage environment, you can create test orders there before setting up on Live. See the Testing on Stage/Sandbox section for more info.
You must "whitelist" your DirectScale Live and Stage IP addresses with Hyperwallet. Contact Customer Care for assistance.
Acquire the necessary credentials and information (provided by Hyperwallet when your account is created.):
- Hyperwallet API URL - Base API URL.
  
  https://api.paylution.com
  
  Do not include a trailing slash /.
- Hyperwallet Program Token - Programs are what Hyperwallet calls their setup for each client account. The provided token will begin with prg-.
  
  This cannot be the program token for the base program, like "DirectScale". It must be the one for something like "DirectScale - Portal".
- Hyperwallet API Username - Your username ID (for example, restapiuser@123456789012).
- Hyperwallet API Password - Your chosen password.

Testing on Stage/Sandbox

Admin: Corporate Admin
Page: Settings > Advanced Settings > Merchants
URL: [CLIENTID].corpadmin.directscale[ENVIRONMENT].com/Settings?category=Merchants
Permission: ViewAdministration(), ViewAdvancedSettings()

Hyperwallet offers a Sandbox site where you can test your payment processing before going live. You must request access to this Sandbox site from Hyperwallet. You can add the provided testing credentials on your Corporate Admin Stage environment when you have access.

Navigate to the Merchants page.
Locate the Hyperwallet credential form.
Enter the testing credentials:
- Test Hyperwallet API URL
  
  https://api.sandbox.hyperwallet.com
  
  Do not include a trailing slash /.
- Test Hyperwallet Program Token
- Test Hyperwallet API Username
- Test Hyperwallet API Password
Enable any additional settings you would like to test:
- Split Payment - Enable to split the remaining balance of Hyperwallet with a backup Merchant for AutoShips. You must also complete the Backup Merchant Id field.
- Create Prepaid Card - If enabled, when a Hyperwallet account is created, a prepaid credit card is sent to the Associate.
- Destination Token - It’s possible to set up Hyperwallet as a payment processor (money-in). Work with your Hyperwallet configuration contact and request to enable. Hyperwallet should then provide you with an ID that starts with act-. Enter this ID in the Destination Token field. Learn more in the Setting up as a Payment Processor section.
- Commission Program Token (AUD) - If you’ll be paying out in more than one currency or multiple countries, you may need to use a different "Program Token" for each currency or country. Learn more in the Paying Commissions in Multiple Currencies section.
- Backup Merchant ID - You can optionally integrate with a second merchant provider for backup. For AutoShips, the backup merchant splits the remaining balance to cover the difference if an Associate doesn’t have enough funds to complete a purchase. You must also enable the Split Payment checkbox.
- Region Currency - Used to determine the currency when making a payment and getting a balance.
Ensure Is Live is disabled while testing. When disabled, the merchant is in a simulated transaction mode that allows you to test payments on your Stage environment.
Click Save Changes.

You can now create test orders on your Stage environment. See Creating Test Orders Guide for more information.

Once you’ve created orders, log in to Hyperwallet’s Sandbox site and view the payments. If there are any errors, you may need to contact either DirectScale’s Customer Care or Hyperwallet’s Support, depending on the origin of the issue.

Adding Credentials for Live

Navigate to the Merchants page.
Locate the Hyperwallet credential form.
Enter the testing credentials:
- Hyperwallet API URL
- Hyperwallet Program Token
- Hyperwallet API Username
- Hyperwallet API Password
Enable any additional settings you need:
- Split Payment - Enable to split the remaining balance of Hyperwallet with a backup Merchant for AutoShips. You must also complete the Backup Merchant Id field.
- Create Prepaid Card - If enabled, when a Hyperwallet account is created, a prepaid credit card is sent to the Associate.
- Destination Token - It’s possible to set up Hyperwallet as a payment processor (money-in). Work with your Hyperwallet configuration contact and request to enable. Hyperwallet should then provide you with an ID that starts with act-. Enter this ID in the Destination Token field. Learn more in the Setting up as a Payment Processor section.
- Commission Program Token (AUD) - If you’ll be paying out in more than one currency or multiple countries, you may need to use a different "Program Token" for each currency or country. Learn more in the Paying Commissions in Multiple Currencies section.
- Backup Merchant ID - You can optionally integrate with a second merchant provider for backup. For AutoShips, the backup merchant splits the remaining balance to cover the difference if an Associate doesn’t have enough funds to complete a purchase. You must also enable the Split Payment checkbox.
- Region Currency - Used to determine the currency when making a payment and getting a balance.
When you’re ready to start using Hyperwallet to accept/payout real money, enable this setting on your Live environment.

All integrated payment merchants must have Is Live enabled on Live to function.

Click Save Changes.

Setting up Hyperwallet as a Commissions Merchant

Admin: Corporate Admin
Page: Settings > Advanced Settings > Commission
URL: [CLIENTID].corpadmin.directscale.com/Settings?category=Commission
Permission: ViewAdministration(), ViewAdvancedSettings()

If you plan to use Hyperwallet as your commissions payout merchant, you must enter the Merchant ID in Corporate Admin.

For testing purposes, add credentials to your Stage environment first (if available).

On Settings > Advanced Settings > Commission:

Locate the Money Out section.
In the Default Commission Merchant ID field, enter Hyperwallet’s Merchant ID for the currency you want to use as the default.
- 104 - USD
- 115 - EUR
- 117 - HKD
- 138 - AUD
Other currencies will need custom development.
Click the Save Changes button.

Additional Commission Merchant Settings

For additional commission merchant settings, see Integrating with a Commission Merchant Provider.
For restricting Hyperwallet to specific regions or Associate Types, see Mapping Commission Merchants

Paying Commissions in Multiple Currencies

Suppose you are paying out in more than one currency or multiple countries. In that case, you may need to use a different Program Token for each currency or country. If the documentation you receive from Hyperwallet Production Support contains multiple "Program Tokens", please talk with your DirectScale Customer Success Manager to arrange a visit with the Consulting team.

To assign the correct token with each outbound request:

A client table will need to be added
Along with added logic in the HyperwalletProgramToken hook

If you only provide the Program Token that’s in Advanced Settings > Merchants > Hyperwallet, and multiple Program Tokens are required. The payout may fail until you do this. The error message you receive at payout time should be clear.

Setting up as a Payment Processor

It’s possible to set up Hyperwallet as a payment processor merchant (money-in). Meaning, that an Associate with a Hyperwallet balance can use that balance as payment on an order placed in the DirectScale system.

To use this solution, the Hyperwallet "Program" (what Hyperwallet calls their setup for each client account) needs to have Spendback enabled. Work with your Hyperwallet configuration contact and request this enabled. Hyperwallet should then provide you with an ID that starts with act-, that you’ll put in the Destination Token field in Advanced Settings > Merchants > Hyperwallet.