Partner White Label Guide

This guide provides instructions on using EasyPost’s Partner White Label API to create and manage ReferralCustomers. A ReferralCustomer is a white label User that can have its own billing methods.

For information on other APIs, such as the Shipping, Tracking, Address Verification, and Shipping Insurance APIs, refer to EasyPost's API Docs.

This guide is also accessible via EasyPost's Client Libraries.

1. Contact the EasyPost Sales team to request access to the free Partner White Label API.
2. After becoming a registered Partner, EasyPost user accounts and API keys gain access to the Partner API.
3. Work with the Account Management team to determine the most suitable integration method for attaching payment methods to referral customers. Options include:
   1. Direct Stripe.js Credit Card Integration (recommended)
   2. Direct Stripe Financial Connections Integrations (for adding bank accounts)
   3. Stripe Connect Integration
4. Once the integration method is selected, the Account Management team configures the account with the correct settings to ensure the appropriate payment method is attached to referral customers.
5. After registration and configuration, access one of EasyPost’s Client Libraries.
6. Review the Getting Started Guide to become familiar with the basic functionalities of EasyPost.

To create a ReferralCustomer, provide a name, email, and phone number. The referral customer's API keys will be returned. Save the API keys securely as they cannot be retrieved again.

NOTE: Creating a ReferralCustomer with an API key certifies agreement to the 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 must keep ReferralCustomer email addresses updated for security purposes.

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  }'

Each referral customer can have one primary and one secondary payment method. Adding a secondary method is highly recommended to avoid payment interruptions.

Once a payment method is established, EasyPost charges the recharge_amount if a user’s wallet balance falls below the recharge_threshold. As a partner of EasyPost, every effort should be made to educate users about EasyPost’s billing process using the recharge threshold and recharge amount system.

The Partner White Label Integration without Stripe Connect offers two options for adding bank accounts and credit cards to referral customers.

1. Credit Cards

   Credit Card Verification

   Refer to the Credit Card Integration API Docs - /v2/credit_cards for technical implementation details.

    

2. Bank Accounts (ACH Direct Debits)

   Stripe Financial Connections

   Refer to the ACH Integration (for Bank Accounts) API Docs - /v2/bank_accounts for technical implementation details.

   NOTE: There is no need to send the Mandate ID to EasyPost, as it will be retrieved directly from Stripe when a charge is initiated.

This integration is recommended for partners who wish to independently manage their Stripe integration and Stripe account.

1. Use Stripe to Create and Verify Payment Methods

   Using the connected Stripe account, create and verify payment methods (credit cards or bank accounts) for referral customers.

   IMPORTANT: Ensure all payment methods are fully verified, including any necessary verification steps, such as ACH micro-deposit verification for bank accounts or 3D Secure authentication for credit cards.

    

   Bank Accounts (ACH Direct Debits)

   Stripe Financial Connections

   1. Use Stripe’s Financial Connections Integration to collect the customer’s bank account information in a tokenized format for ACH debits on your website.
   2. Use Stripe’s Payment Method API to create a payment method using a financial connections account ID and attach it to the referral user’s Stripe customer.
   3. Use Stripe’s Setup Intent API to collect a mandate for the payment method.
   4. Ensure the mandate is in place to allow EasyPost to process ACH transactions.

   Microdeposit Verification

   1. Use Stripe’s Setup Intent API to create the payment method and mandate to initiate the microdeposit verification process, and verify the descriptor code or microdeposit amounts.
   2. Ensure the mandate is in place and the bank account is verified successfully to allow EasyPost to process ACH transactions.

   NOTE: There is no need to send the Mandate ID to EasyPost, as it will be retrieved directly from Stripe when a charge is initiated.

    

   Credit Cards

   Credit Card Verification

   1. Use Stripe’s Setup Intent API to generate a client secret that can be used by Stripe’s Elements API to collect card details on your website.
   2. Use Stripe’s Payment Method API to create a payment method and handle the authentication process required by the card issuer.
   3. Ensure any required additional verification (e.g., 3D Secure authentication) is completed to allow EasyPost to process credit card transactions.

    

2. Submit Payment Method Information to EasyPost

   After creating and verifying the payment methods in Stripe, submit the necessary information to EasyPost to link the payment methods to referral customers.

   Required Information

   • stripe_customer_id: The ID of the customer in the Stripe account.
   • payment_method_reference: Stripe payment method ID (e.g., pm_…)
   • priority: Set to primary to designate this as the primary payment method.
   POST /beta/referral_customers/payment_method

   cURL

   Copy code

   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  }'

Allow referral customers to configure the recharge_threshold and recharge_amount to maintain the account balance automatically.

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}'

Referral customers can deposit an initial amount into the EasyPost Wallet to start using services immediately.

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}'

• API Docs - User Billing