How to Use EasyPost's Partner White Label

This guide will teach you how to use the Partner White Label API. We will show you how to create referral Users and manage their billing. For Shipping API, Tracking API, Address Verification API, Shipping Insurance API, and more, use EasyPost's main API documentation.

This is also available in our client libraries.

This guide will cover:

• Create and Updating ReferralCustomers
• Add Billing Information for ReferralCustomers

To create a referral User, you must provide a name, email, and phone number. The API keys of the referral User will be returned to you. Save the API keys securely as they will not be able to be retrieved again later.

NOTE: When a ReferralCustomer is created with your API key, you are certifying that the ReferralCustomer agrees to EasyPost Terms of Service.

1curl -X POST https://api.easypost.com/v2/referral_customers \
2  -u "$PARTNER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "user": {
6        "name": "Firstname Lastname",
7        "email": "email@example.com",
8        "phone_number": "8888888888"
9      }
10  }'

Partners are obligated to provide us with up-to-date ReferralCustomer emails. EasyPost does not plan to contact your customers; this information is for security purposes only.

1curl -X PUT https://api.easypost.com/v2/referral_customers \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "user": {
6        "email": "new_email@example.com"
7      }
8  }'

EasyPost allows each referral User to have one primary payment method and one secondary payment method. We highly recommend adding a secondary payment method to avoid interruptions.

Once a payment method has been added, EasyPost will automatically charge users their recharge_amount if their wallet balance is below their recharge_threshold. As a partner of EasyPost, you should make every effort to educate referral users about how billing works with our recharge threshold and recharge amount system.

Billing setup steps:

1. Create and attach Payment Methods to referral Users. EasyPost supports two methods of adding billing methods for referral Users. You can only choose one of the options below depending on the payment methods types to support. If you have already built an integration into one option but would like to migrate to a new option, a new EasyPost account must be created.

   1. Stripe Connect integration (supports credit cards and bank accounts)
   2. Direct credit card integration (only works for credit cards)

2. Allow referral Users to configure their recharge_amount and recharge_threshold.

3. (Optional) Allow referral Users to add an initial deposit to the EasyPost wallet.

There are two options to create and attach Payment Methods to referral Users. Option A "Stripe Connect integration" is recommended because it supports both credit cards and bank accounts, while Option B "Direct credit card integration" only supports credit cards. Option B is a quicker path if only credit card billing will be supported for your referral Users.

Follow the steps below to add bank accounts and credit cards to referral Users via the Stripe Connect integration.

Summarized steps are listed below for Option A.

1. Create/link Stripe account to EasyPost
2. Use Stripe to create customers, bank accounts, and credit cards
3. Submit Stripe information to EasyPost

Use this link to create or connect your existing Stripe account to EasyPost.

Using your new Stripe account, create Customers and use the Sources API to create bank accounts and credit cards.

1curl -X POST https://api.easypost.com/beta/referral_customers/payment_method \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "payment_method": {
6        "stripe_customer_id": "cus_...",
7        "payment_method_reference": "card_...",
8        "priority": "primary"
9      }
10  }'

Follow the steps below to attach a credit card to a referral User via a direct credit card integration. When using one of our client libraries, all of the following sub-steps will be handled on your behalf.

Summarized steps are listed below for Option A.

1. Retrieve EasyPost's Stripe public API key

2. Submit above key and the referral User's credit card info to Stripe to get a credit card token

3. Using the referral User's API key, submit the token from Stripe to EasyPost to attach the payment method to the referral User.

Please retrieve EasyPost's Stripe public API key every time you need to create a new payment method, as we may rotate the key for security at any time.

1curl -X GET https://api.easypost.com/v2/partners/stripe_public_key \
2  -u "$PARTNER_API_KEY:"

Use Stripe's JS library to create a token for the ReferralCustomer.

See Stripe JS documentation:

1. Initializing
2. Create Token

stripe = Stripe(<EP_STRIPE_PUBLIC_KEY>);
elements = stripe.elements();
cardElement = elements.create('card');
stripe.createToken(cardElement).then(function(result) {
  // handle result.token, "tok_1KPY4R2eZvKYlo2CGavzwUZv" for next step
});

1curl -X POST "https://api.easypost.com/v2/credit_cards" \
2  -u "<REFERRAL_USER_API_KEY>:" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "credit_card": {
6    "stripe_object_id": "tok_...",
7    "priority": "primary"
8  }
9}'

At this point, you've attached a credit card to a referral User. You should educate the referral Users about the recharge threshold and recharge amount system and allow them to configure their desired recharge threshold and recharge amount.

Configuring a recharge_threshold and recharge_amount is as simple as updating an email in the previous section.

1curl -X PUT "https://api.easypost.com/v2/users" \
2  -u "<REFERRAL_USER_API_KEY>:" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "recharge_amount": "100.00",
6  "secondary_recharge_amount": "50.00",
7  "recharge_threshold": "25.00",
8}'

You can optionally allow referral Users to deposit an initial sum of money into their EasyPost wallet so referral Users can start shipping right away. Provide the amount in cents to be deposited into the referral user's wallet.

1# Fund wallet by using credit card payment method
2curl -X POST https://api.easypost.com/v2/credit_cards/card_.../charges \
3  -u "$EASYPOST_API_KEY": \
4  -H 'Content-Type: application/json' \
5  -d '{
6  "amount": "2000"
7}'
8
9# Fund wallet by using bank account payment method
10curl -X POST https://api.easypost.com/v2/bank_accounts/bank_.../charges \
11  -u "$EASYPOST_API_KEY": \
12  -H 'Content-Type: application/json' \
13  -d '{
14  "amount": "2000"
15}'