Balance Accounts API

Use the Balance Accounts API to list PayPal balance accounts for a customer. A balance account is the PayPal account balance, or holdings, for a customer. A balance account reflects the state and currency of the account. PayPal customers can hold multiple currencies at any point in time.

PayPal partners can use the Balance Accounts API to list the total available and total reserved account balances for a customer's PayPal account. Each balance account in the list shows available and reserved holdings in the holding currency for the account.

Balance accounts (resource group)

Use the /balance-accounts resource to list balance accounts.

List balance accounts

GET /v2/wallet/balance-accounts
Lists PayPal balance accounts for a customer. To list balance accounts for a customer, the API caller includes a bearer token in the Authorization header with the Bearer authentication scheme. A bearer token is an access token that the PayPal authorization server issues to the API caller with the approval of the resource owner.

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows a summary of customer holdings and lists the PayPal balance accounts for a customer:
  • Summary. Shows the total available and total reserved holdings in the customer's primary currency. To calculate the totals in the summary, the API uses the PayPal exchange rate to convert any balances held in other currencies to the customer's primary currency.
  • List of balance accounts. Each balance account shows available and reserved holdings in the customer's holding currency.
  • total_available

    object

    The currency code and amount of the total available holdings in the customer's primary currency.
  • total_reserved

    object

    The currency code and amount of the total reserved holdings in the customer's primary currency.
  • balance_accounts

    array (contains the balance_account object)

    An array of balance accounts.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

Sample Response

{
  "total_available": {
    "currency_code": "USD",
    "value": "2800"
  },
  "total_reserved": {
    "currency_code": "USD",
    "value": "1920"
  },
  "balance_accounts": [
    {
      "id": "HO1069997",
      "open": true,
      "primary": true,
      "available": {
        "currency_code": "USD",
        "value": "1000.00"
      },
      "reserved": {
        "currency_code": "USD",
        "value": "00.00"
      },
      "links": []
    },
    {
      "id": "HO1069998",
      "open": true,
      "primary": false,
      "available": {
        "currency_code": "AUD",
        "value": "1000"
      },
      "reserved": {
        "currency_code": "AUD",
        "value": "00.00"
      }
    },
    {
      "id": "HO1070000",
      "open": true,
      "primary": false,
      "available": {
        "currency_code": "CAD",
        "value": "1000"
      },
      "reserved": {
        "currency_code": "CAD",
        "value": "100"
      },
      "links": []
    },
    {
      "id": "HO1069999",
      "open": true,
      "primary": false,
      "available": {
        "currency_code": "GBP",
        "value": "1000"
      },
      "reserved": {
        "currency_code": "GBP",
        "value": "1000"
      },
      "links": []
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "http://api.sandbox.paypal.com/v2/wallets/balance-accounts"
    }
  ]
}

Show balance account details

GET /v2/wallet/balance-accounts/{balance_id}
Shows details for a balance account, by ID.

Path parameters

  • balance_id

    string

    required

    The ID of the balance account for which to show details.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v2/wallet/balance-accounts/HO1069997 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the PayPal balance account.
  • available

    object

    The amount that is available for purchases or transfers.
  • reserved

    object

    The amount that is reserved and not yet available for purchases or transfers.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

Sample Response

{
  "id": "HO1069997",
  "open": true,
  "primary": true,
  "available": {
    "currency_code": "USD",
    "value": "1000.00"
  },
  "reserved": {
    "currency_code": "USD",
    "value": "00.00"
  },
  "links": []
}

Unavailable balance accounts (resource group)

Use the /unavailable-balance-accounts resource to list unavailable balance accounts.

List unavailable balance accounts

GET /v2/wallet/unavailable-balance-accounts
Lists unavailable balance accounts for a customer, by account number. Enables the customer to pay any negative balance that he or she has incurred to PayPal.

Query parameters

  • status

    string

    Filters the balance accounts in the response by one or more status values. Use the comma (,) character to separate multiple status values. A valid value is INACTIVE, ON_HOLD, or BLOCKED.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v2/wallet/unavailable-balance-accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists the unavailable PayPal balance accounts for a customer.

Sample Response

{
  "balance_accounts": [
    {
      "id": "HO1078386",
      "open": false,
      "primary": false,
      "available": {
        "currency_code": "USD",
        "value": "0"
      },
      "reserved": {
        "currency_code": "USD",
        "value": "0"
      }
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "http://api.sandbox.paypal.com/v2/wallets/unavailable-balance-accounts"
    },
    {
      "rel": "balance_accounts",
      "href": "http://api.sandbox.paypal.com/v2/wallets/balance-accounts"
    }
  ]
}

Common object definitions

balance_account

  • available

    object

    required

    The amount that is available for purchases or transfers.
  • reserved

    object

    required

    The amount that is reserved and not yet available for purchases or transfers.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

balance_accounts

  • total_available

    object

    required

    The currency code and amount of the total available holdings in the customer's primary currency.
  • total_reserved

    object

    required

    The currency code and amount of the total reserved holdings in the customer's primary currency.
  • balance_accounts

    array (contains the balance_account object)

    An array of balance accounts.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

currency_code

error

  • name

    string

    required

    The human-readable, unique name of the error.
  • message

    string

    required

    The message that describes the error.
  • debug_id

    string

    required

    The PayPal internal ID that is used for correlation purposes.
  • information_link

    string

    The information link, or URI, that shows detailed information about this error for the developer.
  • details

    array (contains the error_details object)

    An array of additional details about the error.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

error_details

  • field

    string

    The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
  • value

    string

    The value of the field that caused the error.
  • location

    string

    The location of the field that caused the error. A valid value is body, path, or query. Default is body.
  • issue

    string

    required

    The unique and fine-grained application-level error code.
  • description

    string

    The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.

money

  • currency_code

    string

    required

    The three-character ISO-4217 currency code that identifies the currency.

    Minimum length: 3.

    Maximum length: 3.

  • value

    string

    required

    The value, which might be:
    • An integer for currencies like JPY that are not typically fractional.
    • A decimal fraction for currencies like TND that are subdivided into thousandths.
    For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    Maximum length: 32.

    Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

unavailable_balance_accounts

Additional API information

Error messages

In addition to common HTTP status codes that the REST APIs return, the Balance Accounts API can return the following errors.

  • INTERNAL_SERVICE_ERROR

    An internal service error has occurred. Try the request later.

  • PERMISSION_DENIED

    No permission for requested operation. Verify your credentials.