Skip to main content
POST
/
wallets
Create a new wallet
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_customer_id": "client-xyz456",
  "currency": "USD",
  "rate_amount": "1.5"
}'
{
  "id": "13fddcdc-725b-4ca7-a522-a162ff038567",
  "external_customer_id": "ext_cus_1234567890abcdef",
  "status": "ACTIVE",
  "available_balance": {
    "value": 110,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 110,
    "currency_code": "USD"
  },
  "name": "Prepaid Wallet",
  "rate_amount": "1.0",
  "available_credits": "110.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "110.0",
  "created_at": "2025-09-17T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "expiration_at": "2026-08-12T12:43:31Z"
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json
​
external_customer_id
string
required

External reference to the customer

Example:

"client-xyz456"

​
currency
string
required

Currency in which the wallet operates Currency code in ISO 4217 format.

Required string length: 3
Example:

"USD"

​
rate_amount
string
required

Cost rate per credit unit, must be non zero positive value

Example:

"1.5"

​
name
string

Name of the wallet

Example:

"Prepaid Wallet"

​
paid_credits
string

Number of paid credits to initialize, must be positive value

Example:

"10.0"

​
granted_credits
string

Number of granted credits to initialize, must be positive value

Example:

"5.0"

​
expiration_at
string<date-time>

Cancelled date of the subscription Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
applies_to
object

Indicates whether the prepaid credit applies to the entire invoice or only to specific line items.

​
recurring_transaction_rules
object[]

List of recurring transaction rules for automatic top-ups

Response

Wallet created successfully

​
external_customer_id
string
required

External system reference to the customer

Example:

"client-12345"

​
status
enum<string>
required

Current status of the wallet

Available options:
ACTIVE,
TERMINATED,
PENDING
Example:

"ACTIVE"

​
rate_amount
string
required

Price charged per credit unit

Example:

"1.5"

​
available_balance
object
​
ongoing_usage
object

The ongoing usage of the wallet, and it reflects all current usage and draft invoices including taxes.

Example:
{ "value": 100, "currency_code": "USD" }
​
net_balance
object

This represents the real-time balance after accounting for current usage,.

Example:
{ "value": 50, "currency_code": "USD" }
​
name
string

Human-readable wallet name

Example:

"Prepaid Wallet"

​
available_credits
string

Current credit balance available

Example:

"28.0"

​
ongoing_usage_credits
string

This reflects all current usage and draft invoices.

Example:

"10.0"

​
net_balance_credits
string

This represents the real time balance after accounting for current usage.

Example:

"18.0"

​
consumed_credits
string

Total credits consumed so far

Example:

"2.0"

​
created_at
string<date-time>

Date and time when the wallet was created, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
expiration_at
string<date-time>

Date and time when the wallet is set to expire, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
terminated_at
string<date-time>

Date and time when the wallet was terminated, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
applies_to
object

Indicates whether the prepaid credit applies to the entire invoice or only to specific line items.

​
recurring_transaction_rules
object[]

List of recurring transaction rules for automatic top-ups

​
id
string

Unique identifier for the wallet

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

⌘I