Billing

The Billing functions enable account billing management by adding or deleting payment methods (credit cards and bank accounts), listing available payment methods, and funding wallets.

All endpoints are only available in production environments.

Endpoints

POST

/beta/financial_connections_sessions

POST

/bank_accounts

POST

/bank_accounts/:id/charges

POST

/credit_cards/:id/charges

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

Create Credit Card

Important: This endpoint only works for ReferralCustomers or to manage Child Useraccounts. If you feel this is applicable for your use case, please contact sales.

This section describes the steps to securely collect and store credit card details for ReferralCustomers using EasyPost’s integration with Stripe. This process includes obtaining a client_secret, securely collecting card details with Stripe.js, and storing the payment method using EasyPost’s /v2/credit_cards endpoint.

Obtain a Client Secret

Call the beta/setup_intents endpoint to get a client_secret for securely collecting credit card details.

POST /beta/setup_intents

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

Response

1{
2  "client_secret": "seti_0PzjqKDqT4huGUvdpewEw5Ky_secret_..."
3}

Confirm the SetupIntents via Stripe.js

Use the client_secret obtained in the previous step to confirm the SetupIntents via Stripe.js. This step securely collects card details from the user.

Create a Stripe Element using the client secret from the SetupIntents.
Create a Payment Method using the Stripe Element.

Store the Payment Method with EasyPost

Call the /v2/credit_cards endpoint with the resulting payment_method_id returned by Stripe. For additional details, refer to Stripe's SetupIntent Confirmation for Cards.

Request Parameters

payment_method_id

i.e. pm_...

The Stripe payment method ID returned after confirming the SetupIntents.

priority

i.e. primary

Possible values:

primary
secondary

POST /credit_cards

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

Response

1{
2  "id": "card_...",
3  "disabled_at": null,
4  "object": "CreditCard",
5  "requires_mandate_collection": false,
6  "name": null,
7  "last4": "1234",
8  "exp_month": 1,
9  "exp_year": 2025,
10  "brand": "Visa"
11}

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

ACH Integration (For Bank Accounts)

This section explains the process for securely linking bank accounts for ACH payments using Stripe Financial Connections.

Collect Bank Account Details

Call the /beta/financial_connections_sessions endpoint.

Request Parameters

return_url

i.e. https://www.yourwebsite.com/redirect

The URL to redirect users after successfully linking their bank account. If not provided, EasyPost’s default URL is used.

POST /beta/financial_connections_sessions

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

Response

1{
2  "client_secret": "fcsess_client_secret_..."
3}

Securely Link a Bank Account with Stripe.js

After receiving the client_secret, use Stripe.js to guide the customer through the Financial Connections process. This step allows the customer to securely log in and select a bank account. Refer to Stripe Financial Connections Process for more details.

Create a Bank Account

Once the bank account is linked, Stripe returns an account_id (e.g., fca_…). Use this account_id to call the /v2/bank_accounts endpoint with mandate data and the account owner’s full name.

Request Parameters

financial_connections_id

i.e. fca_...

The ID of the financial connection session returned after linking a bank account via Stripe.js.

mandate_data

Object containing mandate authorization details for ACH payments:

ip_address: The IP address of the user when the mandate was authorized.
user_agent: The user agent string of the browser or device used during authorization.
accepted_at: The unix timestamp when the user accepted the mandate.

priority

i.e. primary

Specifies the priority of the bank account. Possible values:

primary
secondary

POST /bank_accounts

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

Response

1{
2  "bank_name": "STRIPE TEST BANK",
3  "country": "US",
4  "disabled_at": null,
5  "id": "pm_...",
6  "last4": "6789",
7  "object": "BankAccount",
8  "requires_mandate_collection": false,
9  "verified": true
10}

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

Add Funds to your wallet (One-Time Charge)

Fund the EasyPost wallet by charging a primary or secondary payment method on file. The amount added must be greater than or equal to the current balance.

Adding funds with one-time charges is optional, as EasyPost uses an automatic recharge system to maintain a wallet balance.

The API response for this endpoint is empty. EasyPost's client libraries return true if the API call is successful; otherwise, an error is thrown.

Request Parameters

amount

i.e. 2000

Amount, in USD cents, to be deposited into the user's wallet. Amount must be greater than or equal to the user's current balance.

priority

i.e. "primary"

The payment method from your account: Possible values:

primary
secondary

POST /bank_accounts/:id/chargesPOST /credit_cards/:id/charges

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

Response

1{}

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

Retrieve Payment Methods

List payment methods associated with an account.

GET /payment_methods

1curl -X GET https://api.easypost.com/v2/payment_methods \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "id": "cust_...",
3  "object": "PaymentMethods",
4  "primary_payment_method": {
5    "id": "card_...",
6    "disabled_at": null,
7    "object": "CreditCard",
8    "name": null,
9    "last4": "4242",
10    "exp_month": 1,
11    "exp_year": 2025,
12    "brand": "Visa"
13  },
14  "secondary_payment_method": {
15    "id": "card_...",
16    "disabled_at": null,
17    "object": "CreditCard",
18    "name": null,
19    "last4": "4444",
20    "exp_month": 1,
21    "exp_year": 2025,
22    "brand": "Mastercard"
23  }
24}

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

Delete a Payment Method

Delete a payment method. The functions in our client libraries accept a priority parameter (primary or secondary), which abstracts the need to pass in payment method IDs or change endpoints used.

The API response for this endpoint is empty. The functions in our client libraries will return true if the API call succeeds or an error if it fails.

Request Parameters

priority

i.e. "primary"

The payment method to delete from your account. This parameter is only available via one of our client libraries. Possible values:

primary
secondary

DELETE /bank_accounts/:idDELETE /credit_cards/:id

1curl -X DELETE https://api.easypost.com/v2/credit_cards/card_... \
2  -u "EASYPOST_API_KEY":

Response

1{}