Decentralized Quick Start Guide

The Decentralized white-label option in Forge enables Platforms and Marketplaces to embed shipping capabilities without managing postage and other fees on behalf of their customers. This implementation option has unique onboarding requirements that can be found in this guide.

For this option, the sub account object type is ReferralCustomer users.

A ReferralCustomer is an independent sub account with its own billing methods and wallet. These users can be created via API or through the Forge Dashboard.

ReferralCustomer users can be created using one of two methods:

1. Use the POST /referral_customers API to create a ReferralCustomer account.

   1. This request must be made in Production mode using the parent account's EasyPost API Key.
   2. Securely store the API keys for future use. If lost, they can be retrieved from the Sub Account Details page.
   POST /referral_customers

   cURL

   Copy code

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

1. Log in to the Forge Dashboard.
2. Navigate to the Sub Accounts section of the Forge Dashboard.
3. Click New Referral Account and complete the required fields.
4. Securely store the API keys generated for the ReferralCustomer user. If lost, API keys can be retrieved through the Sub Account Details page.

ReferralCustomer accounts are automatically enrolled in a pay-as-you-go EasyPost-managed subscription with access to standard rates, postage, insurance, and other shipping-related features.

ReferralCustomer users can manage onboarding and account configuration through EasyPost-hosted portals.

Co-branded, conversion-optimized flow for collecting billing and account details.

Customizable interface for managing carriers, billing, and other account-level settings.

Portals are accessed via the POST /customer_portal/account_link endpoint.

1curl -X POST https://api.easypost.com/v2/customer_portal/account_link \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "session_type": "account_management",
6    "user_id": "user_...",
7    "refresh_url": "https://example.com/refresh",
8    "return_url": "https://example.com/return",
9    "metadata": {"target": "wallet"}
10  }'

Platforms and marketplaces must build an interface that allows customers to:

• Set up Payment Methods
• Manage Wallet Settings within their application.

EasyPost uses the Stripe.js client to securely add payment methods for ReferralCustomer users.

1. The Stripe Public Key must be retrieved before initializing Stripe.js.

   GET /partners/stripe_public_key

   cURL

   Copy code

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

2. Include Stripe.js in the user's browser:

   <script src="https://js.stripe.com/v3/"></script>

3. Once the Stripe.js script is loaded in the DOM, the Stripe.js client can then be initialized using the public key retrieved above.

   const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

The Forge Decentralized option without Stripe Connect offers credit card and bank account payment methods. Each ReferralCustomer user can have one primary and one secondary payment method.

1. Retrieve a single-use unique client_secret using EasyPost’s POST /beta/setup_intents endpoint to be used with Stripe Elements.

   POST /beta/setup_intents

   cURL

   Copy code

   1curl -X POST "https://api.easypost.com/beta/setup_intents" \
   2  -u "$REFERRAL_USER_API_KEY:" \
   3  -H "Content-Type: application/json"

2. Using the Stripe.js client, use Stripe Elements to create a secure form for collecting credit card details and mount it to the DOM. The appearance and layout of this element can be customized using the options available in the Stripe create_element documentation. An event listener is also needed for handling errors and collecting the Stripe payment method ID.

3. Initialize Stripe Elements and capture the payment method ID.

4. Attach the credit card to theReferralCustomer user’s account using EasyPost’s POST /credit_cards endpoint with the payment method ID previously retrieved.

   POST /credit_cards

   cURL

   Copy code

   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      "payment_method_id": "pm_...",
   7      "priority": "primary"
   8    }
   9  }'

1. Retrieve a single-use unique client secret using EasyPost’s POST /beta/financial_connections_sessions endpoint to be used with Stripe Financial Connections.

   NOTE: The return URL specifies where the user will be redirected after completing the bank account addition process in Stripe Financial Connections.

    

   POST /beta/financial_connections_sessions

   cURL

   Copy code

   1curl -X POST "https://api.easypost.com/beta/financial_connections_sessions" \
   2  -u "$REFERRAL_USER_API_KEY:" \
   3  -H "Content-Type: application/json" \
   4  -d '{
   5    "return_url": "https://www.yourwebsite.com/redirect"
   6  }'

2. Have the user accept a mandate indicating consent to having their bank account automatically charged.

   

3. Open the Stripe Financial Connections modal in the user’s browser using the Stripe.js client with the client secret obtained during the previous step. See the official Stripe documentation.

   NOTE: When the above promise is resolved successfully, the returned result will contain a list of accounts in result.financialConnectionsSession.accounts. The id for each of these accounts is what must be used to create the bank account using the EasyPost API endpoint.

4. Create a bank account for the referral customer using EasyPost’s POST /bank_accounts endpoint once per ID retrieved along with data for the mandate acceptance.

   NOTE: Payment methods can be deleted using EasyPost’s DELETE /bank_accounts/:id and DELETE /credit_cards/:id endpoints.

    

   POST /bank_accounts

   cURL

   Copy code

   1curl -X POST "https://api.easypost.com/v2/bank_accounts" \
   2  -u "$REFERRAL_USER_API_KEY:" \
   3  -H "Content-Type: application/json" \
   4  -d '{
   5    "financial_connections_id": "fca_...",
   6    "mandate_data": {
   7      "ip_address": "127.0.0.1",
   8      "user_agent": "Mozilla/5.0",
   9      "accepted_at": 1722510730,
   10    },
   11    "priority": "primary"
   12  }'

ReferralCustomer users can deposit an initial amount into the EasyPost Wallet using EasyPost’s POST /bank_accounts/:id/charges or POST /credit_cards/:id/charges to start using services immediately.

1curl -X POST https://api.easypost.com/v2/credit_cards/card_.../charges \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "amount": "2000"
6  }'

Once a payment method is established, EasyPost can automatically charge a recharge_amount if a wallet balance falls below a recharge_threshold. To ensure uninterrupted service, platforms using the Decentralized white-label option should provide clear guidance on the recharge threshold and recharge amount system.

• recharge_amount is set to $100
• recharge_threshold is set to zero

This means that the wallet will not automatically recharge unless the balance falls below zero. A negative balance can occur if shipment adjustments are applied due to inaccurately specified weights, dimensions, or other shipment details.

If a charge to the primary payment method fails, EasyPost will automatically attempt to charge the ReferralCustomer’s secondary payment method, if one is available. To avoid service interruptions, It is recommended that ReferralCustomers have both a primary and secondary payment method configured.

Forge customers can configure the recharge_threshold, recharge_amount and secondary_recharge_amount for a ReferralCustomer using EasyPost’s PATCH /users API. These settings allow automatic maintenance of the wallet balance and prevent disruptions in service.

1# Update the authenticated user
2curl -X PATCH https://api.easypost.com/v2/users \
3  -u "EASYPOST_API_KEY": \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "user": {
7      "recharge_threshold": "50.00"
8    }
9  }'
10
11# Update a child user
12curl -X PATCH https://api.easypost.com/v2/users/user_... \
13  -u "EASYPOST_API_KEY": \
14  -H 'Content-Type: application/json' \
15  -d '{
16    "user": {
17      "name": "Test Child"
18    }
19  }'

Upon creation, the ReferralCustomer user automatically receives access to several Wallet Carrier Accounts, which are billed through the referralCustomer's wallet.

To add additional carrier accounts for a ReferralCustomer user, one of the following options can be used:

• API Integration: Use the Carrier Account API with the ReferralCustomer user’s Production API Key of the sub account to integrate additional carriers.
• Forge Dashboard: Manually add carriers through the Carriers section of the Forge Dashboard.

Creating shipments for ReferralCustomer users follows the same process as Parent Users, with key differences being the requirement to use the ReferralCustomer user’s API Keys.

A Shipment Object consists of:

• A valid to_address and from_address
• A parcel with shipping details
• Any required forms for international deliveries

Once a shipment is created, a Shipment Object is used to retrieve shipping rates and purchase a label.

Please visit the Help Center for more information.