On this page
No Headings
Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.
Client CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheaderScopes
readwriteapplication/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets" \ -H "Content-Type: application/json" \ -d '{ "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"
}{
"name": "INVALID_REQUEST",
"message": "Request is not well-formed, syntactically incorrect, or violates schema.",
"debug_id": "dc99e3955cdd8",
"details": [
{
"field": "/email",
"value": "abc",
"location": "body",
"issue": "INVALID_PARAMETER_VALUE",
"description": "The value of a field does not conform to the expected format."
}
]
}{
"name": "NOT_AUTHORIZED",
"message": "Authorization failed due to insufficient permissions.",
"debug_id": "565f78f101498",
"details": [
{
"issue": "PERMISSION_DENIED",
"description": "You do not have permission to access or perform operations on this resource."
}
]
}{
"name": "UNPROCESSABLE_ENTITY",
"message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
"debug_id": "90957fca61718",
"details": [
{
"field": "/email",
"value": "[email protected]",
"location": "body",
"issue": "UNSUPPORTED_EMAIL",
"description": "The email provided is not supported."
}
]
}{
"name": "INTERNAL_SERVER_ERROR",
"message": "An internal server error has occurred.",
"debug_id": "90957fca61718"
}External reference to the customer
Currency in which the wallet operates
^[A-Z]{3}$3 <= length <= 3Name of the wallet
Cost rate per credit unit, must be non zero positive value
^(?!0+(?:\.0+)?$)\d+(\.\d+)?$Number of paid credits to initialize, must be positive value
^(0|[1-9]\d*)(\.\d+)?$Number of granted credits to initialize, must be positive value
^(0|[1-9]\d*)(\.\d+)?$Cancelled date of the subscription
date-timeList of recurring transaction rules for automatic top-ups