Decentralized (with Stripe Connect)

This guide provides instructions on using Forge’s decentralized white label option to create and manage ReferralCustomers using Stripe Connect with a Stripe Account. For a more detailed overview of the White Label product, please refer to the Forge Overview page.

1. Complete all prerequisites to Get Started with Forge.
2. Already manage a Stripe account and have flows for creating Stripe Customers and Stripe Payment Methods.

Use EasyPost’s POST /referral_customers endpoint to create a ReferralCustomer. Save the API keys securely for use in later steps. If API keys are lost, they can be retrieved from the Sub Account Details page.

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

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

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

Forge Decentralized with Stripe Connect allows platforms and marketplaces to collect payment methods with their own custom Stripe integration. Use EasyPost’s POST /beta/referral_customers` endpoint to create a referral customer payment method. Each referral customer can have one primary and one secondary payment method.

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

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 EasyPost-Powered Carrier Accounts, which are billed through the platforms’ 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.