How to use Partner White Label - Golang

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:

Before You Start

  1. You must contact our Sales team to access the free Partner White Label API. Once you're a registered Partner, your EasyPost user account and API keys will be able to access the Partner API.

  2. Once the Partner integration method is determined, our Account Management Team will configure your account with the correct settings to ensure the proper payment method is attached to your referral Users.
  3. Once you have registered as a Partner and configured your integration method, be sure to access one of our official client libraries.

Creating & Managing Referral Users

Creating Referral Users

Production OnlyThis call will only work with your production API Key.

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 Referral User is created with your API key, you are certifying that the Referral User agrees to EasyPost Terms of Service.

Create a Referral User
package example

import (
    "fmt"
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    name := "Test Referral"
    email := "test@example.com"
    phone := "5555555555"

    referralUser, _ := client.CreateReferralCustomer(
        &easypost.UserOptions{
            Name:  &name,
            Email: &email,
            Phone: &phone,
        },
    )

    fmt.Println(referralUser)
}
Create a Referral User JSON Response
{
  "id": "user_...",
  "object": "User",
  "parent_id": null,
  "created_at": "2022-02-03T00:38:06Z",
  "name": "Firstname Lastname",
  "email": "email@example.com",
  "phone_number": "8888888888",
  "verified": true,
  "balance": "0.00",
  "price_per_shipment": "0.0000",
  "recharge_amount": "100.00",
  "secondary_recharge_amount": "100.00",
  "recharge_threshold": "25.00",
  "has_billing_method": false,
  "cc_fee_rate": "0.03",
  "default_insurance_amount": null,
  "insurance_fee_rate": "0.005",
  "insurance_fee_minimum": "0.50",
  "children": [],
  "api_keys": [
    {
      "object": "ApiKey",
      "key": "...",
      "mode": "test",
      "created_at": "2022-02-03T00:38:06Z"
    },
    {
      "object": "ApiKey",
      "key": "...",
      "mode": "production",
      "created_at": "2022-02-03T00:38:06Z"
    }
  ]
}

Updating Referral Users' Emails

Production OnlyThis call will only work with your production API Key.

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

Update a Referral User email
package example

import (
    "os"

    "github.com/EasyPost/easypost-go/v2"
)

func main() {
    apiKey := os.Getenv("<YOUR_TEST/PRODUCTION_API_KEY>")
    client := easypost.New(apiKey)

    _, _ = client.UpdateReferralCustomerEmail("user_...", "new_email@example.com")
}
Update a Referral User email JSON Response
{
  "message": "Email updated successfully"
}

Adding Billing Information

Production OnlyThis call will only work with your production API Key.

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

Step 1: Create and Attach Payment Methods to Referral Users

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.

OPTION A: STRIPE CONNECT INTEGRATION

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
Option A.1: Create/Link Stripe Account to EasyPost

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

Option A.2: Use Stripe to create customers, bank accounts, and credit cards

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

Option A.3: Submit Stripe information to EasyPost
Submit Stripe information to EasyPost
package example

import (
	"fmt"
	"os"

	"github.com/EasyPost/easypost-go/v3"
)

func main() {
	apiKey := os.Getenv("EASYPOST_API_KEY")
	client := easypost.New(apiKey)

	paymentMethod, _ := client.BetaAddPaymentMethod("cus_...", "card_...", easypost.PrimaryPaymentMethodPriority)

	fmt.Println(paymentMethod)
}
Submit Stripe Token to EasyPost JSON Response
{
  "id": "card_...",
  "disabled_at": null,
  "object": "CreditCard",
  "name": null,
  "last4": "1234",
  "exp_month": 7,
  "exp_year": 2024,
  "brand": "MasterCard"
}

OPTION B: DIRECT CREDIT CARD INTEGRATION

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.
Option B.1: Retrieve EasyPost's Stripe Public API Key

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.

Retrieve EasyPost's Stripe Public API Key
This step has been abstracted away in our golang client library and happens on your behalf when adding a credit card.
Retrieve EasyPost's Stripe Public API Key JSON Response
{
  "public_key": "pk_..."
}
Option B.2: Get Token From Stripe

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

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
});

See complete example

Option B.3: Submit Stripe Token to EasyPost
Submit Stripe Token to EasyPost
This step has been abstracted away in our golang client library and happens on your behalf when adding a credit card.
Submit Stripe Token to EasyPost JSON Response
{
  "id": "card_...",
  "object": "CreditCard",
  "name": null,
  "last4": "1234",
  "exp_month": 1,
  "exp_year": 2025,
  "brand": "Visa"
}

Step 2: Configure Recharge Threshold and Recharge Amount

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.

Configure Recharge Threshold and Recharge Amount
package example

import (
	"os"

	"github.com/EasyPost/easypost-go/v2"
)

func main() {
	apiKey := os.Getenv("<YOUR_PRODUCTION_API_KEY>")
	client := easypost.New(apiKey)

	_, _ = client.RetrieveMe()
	rechargeThreshold := "50.00"

	_, _ = client.UpdateUser(
		&easypost.UserOptions{
			RechargeAmount: &rechargeThreshold,
		},
	)
}
Configure Recharge Threshold and Recharge Amount JSON Response
{
  "id": "user_qqUy4rWef",
  "object": "User",
  "parent_id": null,
  "created_at": "2018-03-03T00:38:06Z",
  "name": "Update Me",
  "email": "c.vader@example.com",
  "phone_number": "555-123-4321",
  "verified": true,
  "balance": "1234.99000",
  "price_per_shipment": 0.05,
  "recharge_amount": "50.00",
  "secondary_recharge_amount": "250.00",
  "recharge_threshold": "100.00",
  "cc_fee_rate": "0.03",
  "insurance_fee_rate": "0.005",
  "insurance_fee_minimum": "0.50",
  "children": []
}

[Optional] Step 3: Fund a Wallet ("One Time Charge")

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.

Fund your EasyPost wallet
package example

import (
	"os"

	"github.com/EasyPost/easypost-go/v2"
)

func main() {
	apiKey := os.Getenv("YOUR_PRODUCTION_API_KEY")
	client := easypost.New(apiKey)

	_ = client.FundWallet("2000", easypost.PrimaryPaymentMethodPriority)
}
Fund your EasyPost wallet JSON Response
{}