Balance Accounts API

Overview

A balance account is a PayPal account balance, or holdings, for a customer. PayPal customers can hold multiple currencies at any given point in time.

The Balance Accounts API enables PayPal partners to list the total available and total reserved account balances for a PayPal account for a customer. For example, if a bank partners with PayPal, the bank can use this API to list a PayPal balance account for a customer.

Other types of partners, such as service providers, can use this API to display PayPal account information for customers who might want to simultaneously access their service and PayPal accounts.

Integration steps

1. Required Meet the prerequisites.
2. Required List PayPal balance accounts.

Prerequisites

To use the Balance Accounts API, you must:

  1. Be a partner in the PayPal Partner Program.

  2. Request third-party permissions from the account owner so that you can make calls on behalf of the third party.

  3. Get an access token.

    In exchange for these credentials, the PayPal authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

List PayPal balance accounts

To list PayPal balance accounts for a customer, include a bearer token in the Authorization: Bearer request header. A bearer token is an access token that the PayPal authorization server issues to the API caller with the approval of the resource owner. You can use a bearer token to complete an action on behalf of the resource owner.

Note: For information about obtaining a bearer token, contact your PayPal account manager.

This sample request uses a bearer token to list balance accounts for a customer:

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

This sample response shows a typical 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": "https://api.sandbox.paypal.com/v2/wallets/balance-accounts"
    }
  ]
}

The response includes:

  • Summary

    The total available and 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 in the list shows available and reserved holdings in the holding currency for the account.

Additional information