Managed Accounts API

Important: The PayPal Commerce Platform is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.

The Managed Accounts API enables a partner to add PayPal managed accounts. It supports the Connected path and Managed path partner models:

  • With Connected path, you host a button on your website that takes sellers to PayPal to create and configure a PayPal account. The Onboarding API enables you to collect seller data and pass it to the account creation and setup forms, reducing the burden on sellers during the signup and setup process.

  • With Managed path, you create and configure reference accounts that enable you to make payments to sellers on your platform. The Managed Accounts API enables you to create reference accounts without involving your sellers.

For the Managed path, you can call the create managed account, repopulate managed account, and update managed account methods.

Merchant accounts (resource group)

Use the /partners/merchant-accounts resource to create, show details for, repopulate, update, partially update, show the balance for, and show financial instrument details for managed accounts.

Create managed account

POST /v1/customer/partners/merchant-accounts
Creates a managed account. Submit the account information in the JSON request body.

Request body

  • owner_info

    object

    required

    The account holder's information.
  • business_info

    object

    required

    The business information for the merchant.
  • account_status

    enum

    The account status.

    Allowed values: A, PV, PUA.

  • account_currency

    string

    required

    The three-character ISO-4217 currency code for the account.

    Minimum length: 3.

    Maximum length: 3.

  • secondary_currency

    array (contains the currency_code object)

    An array of the three-character ISO-4217 currency codes for the secondary currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    enum

    The time zone.

    Allowed values: Pacific/Honolulu, America/Anchorage, America/Los_Angeles, America/Phoenix, America/Denver, America/Chicago, America/Indianapolis, America/New_York, America/Puerto_Rico, America/Vancouver, America/Dawson_Creek, America/Edmonton, America/Regina, America/Winnipeg, America/Atikokan, America/Toronto, America/Halifax, America/Goose_Bay, America/Blanc-Sablon, America/St_Johns, America/Tijuana, America/Hermosillo, America/Chihuahua, America/Mexico_City, America/Rio_Branco, America/Manaus, America/Campo_Grande, America/Argentina/Buenos_Aires, America/Sao_Paulo, America/Fortaleza, America/Noronha, America/Thule, America/Godthab, America/Scoresbysund, America/Danmarkshavn, Atlantic/Azores, Europe/Lisbon, Europe/Dublin, Europe/London, Europe/Luxembourg, Europe/Berlin, Atlantic/Faroe, Europe/Oslo, Europe/Copenhagen, Europe/Stockholm, Europe/Helsinki, Europe/Prague, Europe/Bratislava, Europe/Athens, Europe/Istanbul, Africa/Johannesburg, Asia/Jerusalem, Asia/Dubai, Europe/Kaliningrad, Europe/Kiev, Europe/Moscow, Europe/Samara, Asia/Yekaterinburg, Asia/Omsk, Asia/Krasnoyarsk, Asia/Irkutsk, Asia/Yakutsk, Asia/Vladivostok, Asia/Magadan, Asia/Kamchatka, Asia/Calcutta, Asia/Bangkok, Asia/Jakarta, Asia/Saigon, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Hong_Kong, Asia/Makassar, Asia/Manila, Asia/Taipei, Asia/Shanghai, Asia/Seoul, Asia/Tokyo, Asia/Jayapura, Australia/Perth, Australia/Darwin, Australia/Adelaide, Australia/Hobart, Australia/Sydney, Australia/Brisbane, Australia/Lord_Howe, Pacific/Auckland, Pacific/Chatham, Pacific/Niue, Pacific/Fakaofo, Pacific/Rarotonga, Europe/Bucharest, GMT.

  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account allows the merchant to log in.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
  • signup_options

    object

    The options, preferences, and agreements for the account.
  • financial_instruments

    array

    An array of financial instruments.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "owner_info": {
    "email": "sample-user@example.com",
    "name": {
      "prefix": "Mr",
      "given_name": "John",
      "surname": "Collins",
      "middle_name": "Davis",
      "suffix": "Jr"
    },
    "country_code_of_nationality": "US",
    "addresses": [
      {
        "type": "HOME",
        "line1": "150 E San Fernando St",
        "line2": "apt #1",
        "city": "San Jose",
        "state": "CA",
        "country_code": "US",
        "postal_code": "95112"
      }
    ],
    "date_of_birth": "1990-01-01",
    "identifications": [
      {
        "type": "SOCIAL_SECURITY_NUMBER",
        "value": "123456789",
        "masked": true,
        "issuer_country_code": "US"
      }
    ],
    "phones": [
      {
        "type": "HOME",
        "country_code": "1",
        "national_number": "4089679174",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "1",
        "national_number": "4089679175",
        "extension_number": "123"
      }
    ]
  },
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "name": "US Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYMENT_IDENTIFICATION_NUMBER",
        "value": "111234501",
        "masked": false,
        "issuer_country_code": "US"
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "line1": "585 Franklin Str",
        "line2": "apt #1",
        "city": "Mountain View",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94041"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "1",
        "national_number": "4089672222",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "1",
        "national_number": "4081234567"
      }
    ],
    "category": "1004",
    "sub_category": "2940",
    "merchant_category_code": "3011",
    "date_business_established": "2001-01-17",
    "date_of_registration": "2011-04-17",
    "dispute_email": "dispute@example.com",
    "business_sales_details": {
      "average_price": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://example.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "1",
        "national_number": "4089673333",
        "extension_number": "123"
      },
      "message": [
        {
          "type": "ONLINE",
          "headline": "Your online purchase",
          "logo_image_url": "https://example.com/logo/online/",
          "service_image_url": "https://example.com/service/online/",
          "seller_message": "Your online purchase"
        },
        {
          "type": "RETAIL",
          "headline": "Your retail purchase",
          "logo_image_url": "https://example.com/logo/retail/",
          "service_image_url": "https://example.com/service/retail/",
          "seller_message": "Your retail purchase"
        }
      ]
    }
  },
  "account_status": "A",
  "account_currency": "USD",
  "secondary_currency": [
    "CAD",
    "JPY"
  ],
  "payment_receiving_preferences": {
    "block_unconfirmed_us_address_payments": true,
    "block_non_us_payments": true,
    "block_echeck_payments": true,
    "block_cross_currency_payments": true,
    "block_send_money_payments": true,
    "alternate_payment_url": "https://example.com/alternate/",
    "display_instructions_text_input": true,
    "cc_soft_descriptor": "USCCSOFTDES",
    "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
    {
      "type": "PARTNER"
    }
  ],
  "account_permissions": [
    {
      "permissions": [
        "EXPRESS_CHECKOUT",
        "RECURRING_PAYMENT",
        "EXTENDED_PRO_PROCESSING",
        "EXCEPTION_PROCESSING",
        "MASS_PAY",
        "ENCRYPTED_WEBSITE_PAYMENTS"
      ]
    }
  ],
  "timezone": "America/Los_Angeles",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows managed account details.
  • payer_id

    string

    The payer ID. If the account was not created, this value is blank.

    Maximum length: 127.

  • partner_merchant_external_id

    string

    The partner-specified ID for the account, which was passed in the partner_merchant_external_id request parameter.

    Maximum length: 127.

  • merchant_authorization_code

    string

    The merchant authorization code.
  • custom_data

    array (contains the keyvalue object)

    An array of key-and-value pairs that contain custom data. For example, aa_token: token.
  • errors

    array (contains the error object)

    An array of errors, if any, that occurred during account creation.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "payer_id": "7G4EPEEPEF74L",
  "partner_merchant_external_id": "abc123",
  "links": [
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}

Repopulate managed account

POST /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Repopulates information for a managed account, by merchant payer ID.
Important: This method is deprecated as of v1.1. Please use the PUT method.

Path parameters

  • merchant_payer_id

    string

    required

    The payer ID of the merchant for which to repopulate an account.

Request body

  • owner_info

    object

    required

    The account holder's information.
  • business_info

    object

    required

    The business information for the merchant.
  • account_status

    enum

    The account status.

    Allowed values: A, PV, PUA.

  • account_currency

    string

    required

    The three-character ISO-4217 currency code for the account.

    Minimum length: 3.

    Maximum length: 3.

  • secondary_currency

    array (contains the currency_code object)

    An array of the three-character ISO-4217 currency codes for the secondary currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    enum

    The time zone.

    Allowed values: Pacific/Honolulu, America/Anchorage, America/Los_Angeles, America/Phoenix, America/Denver, America/Chicago, America/Indianapolis, America/New_York, America/Puerto_Rico, America/Vancouver, America/Dawson_Creek, America/Edmonton, America/Regina, America/Winnipeg, America/Atikokan, America/Toronto, America/Halifax, America/Goose_Bay, America/Blanc-Sablon, America/St_Johns, America/Tijuana, America/Hermosillo, America/Chihuahua, America/Mexico_City, America/Rio_Branco, America/Manaus, America/Campo_Grande, America/Argentina/Buenos_Aires, America/Sao_Paulo, America/Fortaleza, America/Noronha, America/Thule, America/Godthab, America/Scoresbysund, America/Danmarkshavn, Atlantic/Azores, Europe/Lisbon, Europe/Dublin, Europe/London, Europe/Luxembourg, Europe/Berlin, Atlantic/Faroe, Europe/Oslo, Europe/Copenhagen, Europe/Stockholm, Europe/Helsinki, Europe/Prague, Europe/Bratislava, Europe/Athens, Europe/Istanbul, Africa/Johannesburg, Asia/Jerusalem, Asia/Dubai, Europe/Kaliningrad, Europe/Kiev, Europe/Moscow, Europe/Samara, Asia/Yekaterinburg, Asia/Omsk, Asia/Krasnoyarsk, Asia/Irkutsk, Asia/Yakutsk, Asia/Vladivostok, Asia/Magadan, Asia/Kamchatka, Asia/Calcutta, Asia/Bangkok, Asia/Jakarta, Asia/Saigon, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Hong_Kong, Asia/Makassar, Asia/Manila, Asia/Taipei, Asia/Shanghai, Asia/Seoul, Asia/Tokyo, Asia/Jayapura, Australia/Perth, Australia/Darwin, Australia/Adelaide, Australia/Hobart, Australia/Sydney, Australia/Brisbane, Australia/Lord_Howe, Pacific/Auckland, Pacific/Chatham, Pacific/Niue, Pacific/Fakaofo, Pacific/Rarotonga, Europe/Bucharest, GMT.

  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account allows the merchant to log in.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
  • signup_options

    object

    The options, preferences, and agreements for the account.
  • financial_instruments

    array

    An array of financial instruments.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/F9E99K66P3G77 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "owner_info": {
    "email": "sample-user@example.com",
    "name": {
      "prefix": "Mr",
      "given_name": "John",
      "surname": "Collins",
      "middle_name": "Davis",
      "suffix": "Jr"
    },
    "country_code_of_nationality": "US",
    "addresses": [
      {
        "type": "HOME",
        "line1": "150 E San Fernando St",
        "line2": "apt #1",
        "city": "San Jose",
        "state": "CA",
        "country_code": "US",
        "postal_code": "95112"
      }
    ],
    "date_of_birth": "1990-01-01",
    "phones": [
      {
        "type": "HOME",
        "country_code": "1",
        "national_number": "4089679174",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "1",
        "national_number": "4089679175",
        "extension_number": "123"
      }
    ],
    "identifications": [
      {
        "type": "SOCIAL_SECURITY_NUMBER",
        "value": "1234",
        "masked": true,
        "issuer_country_code": "US"
      }
    ]
  },
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "name": "US Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYMENT_IDENTIFICATION_NUMBER",
        "value": "111234501",
        "masked": false,
        "issuer_country_code": "US"
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "line1": "585 Franklin Str",
        "line2": "apt #1",
        "city": "Mountain View",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94041"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "1",
        "national_number": "4089672222",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "1",
        "national_number": "4081234567"
      }
    ],
    "category": "1004",
    "sub_category": "2940",
    "merchant_category_code": "3011",
    "date_business_established": "2001-01-17",
    "date_of_registration": "2011-04-17",
    "dispute_email": "dispute@example.com",
    "business_sales_details": {
      "average_price": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://example.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "1",
        "national_number": "4089673333",
        "extension_number": "123"
      },
      "message": [
        {
          "type": "ONLINE",
          "headline": "Your online purchase",
          "logo_image_url": "https://example.com/logo/online/",
          "service_image_url": "https://example.com/service/online/",
          "seller_message": "Your online purchase"
        },
        {
          "type": "RETAIL",
          "headline": "Your retail purchase",
          "logo_image_url": "https://example.com/logo/retail/",
          "service_image_url": "https://example.com/service/retail/",
          "seller_message": "Your retail purchase"
        }
      ]
    }
  },
  "account_status": "A",
  "account_currency": "USD",
  "secondary_currency": [
    "CAD",
    "JPY"
  ],
  "payment_receiving_preferences": {
    "block_unconfirmed_us_address_payments": true,
    "block_non_us_payments": true,
    "block_echeck_payments": true,
    "block_cross_currency_payments": true,
    "block_send_money_payments": true,
    "alternate_payment_url": "https://example.com/alternate/",
    "display_instructions_text_input": true,
    "cc_soft_descriptor": "USCCSOFTDES",
    "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
    {
      "type": "PARTNER"
    }
  ],
  "account_permissions": [
    {
      "permissions": [
        "EXPRESS_CHECKOUT",
        "RECURRING_PAYMENT",
        "EXTENDED_PRO_PROCESSING",
        "EXCEPTION_PROCESSING",
        "MASS_PAY",
        "ENCRYPTED_WEBSITE_PAYMENTS"
      ]
    }
  ],
  "timezone": "America/Los_Angeles",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows managed account details.
  • payer_id

    string

    The payer ID. If the account was not created, this value is blank.

    Maximum length: 127.

  • partner_merchant_external_id

    string

    The partner-specified ID for the account, which was passed in the partner_merchant_external_id request parameter.

    Maximum length: 127.

  • merchant_authorization_code

    string

    The merchant authorization code.
  • custom_data

    array (contains the keyvalue object)

    An array of key-and-value pairs that contain custom data. For example, aa_token: token.
  • errors

    array (contains the error object)

    An array of errors, if any, that occurred during account creation.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "payer_id": "7G4EPEEPEF74L",
  "partner_merchant_external_id": "abc123",
  "links": [
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}

Partially update managed account

PATCH /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Partially updates information for a managed account, by merchant payer ID.

Path parameters

  • merchant_payer_id

    string

    required

    The ID of the merchant.

Request body

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/F9E99K66P3G77 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "op": "replace",
    "path": "create_account_details/owner_info/name/given_name",
    "value": "John"
  },
  {
    "op": "replace",
    "path": "create_account_details/owner_info/address/line1",
    "value": "123 Garden St."
  }
]'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Update managed account

PUT /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Updates managed account information, by merchant payer ID. Specify the information to update in the JSON request body.

Path parameters

  • merchant_payer_id

    string

    required

    The payer ID of the merchant for which to update account information.

Request body

  • owner_info

    object

    The account holder's information.
  • business_info

    object

    The business information for the merchant.
  • account_status

    string

    The account status.
  • account_currency

    string

    The currency code for the account.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies. In addition to the account currency, the managed account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    An array of account relationships between the parent and this account.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.
    Note: You cannot fetch this information.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account enables the merchant to log in. You cannot log in to accounts that are only managed by their parent.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
    Note: You cannot fetch this information.
  • signup_options

    object

    The partner options to assign to the managed account.
  • errors

    array (contains the error object)

    An array of errors for adding bundles to a given customer account.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/F9E99K66P3G77 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "owner_info": {
    "email": "owner-info@example.com",
    "name": {
      "prefix": "US Prefix",
      "given_name": "USFirstName",
      "surname": "US LastName",
      "middle_name": "US MiddleName",
      "suffix": "US Suffix"
    },
    "country_code_of_nationality": "US",
    "addresses": [
      {
        "type": "HOME",
        "line1": "150 E San Fernando St",
        "line2": "apt #1",
        "city": "San Jose",
        "state": "CA",
        "country_code": "US",
        "postal_code": "95112"
      }
    ],
    "date_of_birth": "1990-01-01",
    "phones": [
      {
        "type": "HOME",
        "country_code": "1",
        "national_number": "4089679174",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "1",
        "national_number": "4089679175",
        "extension_number": "123"
      }
    ],
    "identifications": [
      {
        "type": "SOCIAL_SECURITY_NUMBER",
        "value": "1234",
        "masked": true,
        "issuer_country_code": "US"
      }
    ]
  },
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "name": "US Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYMENT_IDENTIFICATION_NUMBER",
        "value": "111234501",
        "masked": false,
        "issuer_country_code": "US"
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "line1": "585 Franklin Str",
        "line2": "apt #1",
        "city": "Mountain View",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94041"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "1",
        "national_number": "4089672222",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "1",
        "national_number": "4081234567"
      }
    ],
    "category": "1004",
    "sub_category": "2940",
    "merchant_category_code": "3011",
    "date_business_established": "2001-01-17",
    "date_of_registration": "2011-04-17",
    "dispute_email": "dispute@example.com",
    "business_sales_details": {
      "average_price": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://example.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "1",
        "national_number": "4089673333",
        "extension_number": "123"
      },
      "message": [
        {
          "type": "ONLINE",
          "headline": "headline1",
          "logo_image_url": "https://example.com/logoimage/",
          "service_image_url": "https://example.com/serviceimageurl1/",
          "seller_message": "seller message"
        },
        {
          "type": "RETAIL",
          "headline": "headline2",
          "logo_image_url": "https://example.com/logoimageurl2/",
          "service_image_url": "https://example.com/serviceimageurl2/",
          "seller_message": "seller message"
        }
      ]
    }
  },
  "account_status": "A",
  "account_currency": "USD",
  "secondary_currency": [
    "CAD",
    "JPY"
  ],
  "payment_receiving_preferences": {
    "block_unconfirmed_us_address_payments": true,
    "block_non_us_payments": true,
    "block_echeck_payments": true,
    "block_cross_currency_payments": true,
    "block_send_money_payments": true,
    "alternate_payment_url": "www.original.com",
    "display_instructions_text_input": true,
    "cc_soft_descriptor": "USCCSOFTDES",
    "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
    {
      "type": "PARTNER"
    }
  ],
  "account_permissions": [
    {
      "permissions": [
        "EXPRESS_CHECKOUT",
        "RECURRING_PAYMENT",
        "EXTENDED_PRO_PROCESSING",
        "EXCEPTION_PROCESSING",
        "MASS_PAY",
        "ENCRYPTED_WEBSITE_PAYMENTS"
      ]
    }
  ],
  "timezone": "America/Los_Angeles",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true
}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

204 No Content

Show managed account details

GET /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Shows details for a managed account, by merchant payer ID.

Path parameters

  • merchant_payer_id

    string

    required

    The payer ID of the merchant for which to show account details.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC \
-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 managed account details.
  • owner_info

    object

    The account holder's information.
  • business_info

    object

    The business information for the merchant.
  • account_status

    string

    The account status.
  • account_currency

    string

    The currency code for the account.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies. In addition to the account currency, the managed account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    An array of account relationships between the parent and this account.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.
    Note: You cannot fetch this information.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account enables the merchant to log in. You cannot log in to accounts that are only managed by their parent.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
    Note: You cannot fetch this information.
  • signup_options

    object

    The partner options to assign to the managed account.
  • errors

    array (contains the error object)

    An array of errors for adding bundles to a given customer account.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "owner_info": {
    "email": "owner-info@example.com",
    "name": {
      "prefix": "US Prefix",
      "given_name": "USFirstName",
      "surname": "US LastName",
      "middle_name": "US MiddleName",
      "suffix": "US Suffix"
    },
    "country_code_of_nationality": "US",
    "addresses": [
      {
        "type": "HOME",
        "line1": "150 E San Fernando St",
        "line2": "apt #1",
        "city": "San Jose",
        "state": "CA",
        "country_code": "US",
        "postal_code": "95112"
      }
    ],
    "date_of_birth": "1990-01-01",
    "identifications": [
      {
        "type": "SOCIAL_SECURITY_NUMBER",
        "value": "****",
        "masked": true,
        "issuer_country_code": "US"
      }
    ],
    "phones": [
      {
        "type": "HOME",
        "country_code": "1",
        "national_number": "4089679174",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "1",
        "national_number": "4089679175",
        "extension_number": "123"
      }
    ]
  },
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "name": "US Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYMENT_IDENTIFICATION_NUMBER",
        "value": "****",
        "masked": false,
        "issuer_country_code": "US"
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "line1": "585 Franklin Str",
        "line2": "apt #1",
        "city": "Mountain View",
        "state": "CA",
        "country_code": "US",
        "postal_code": "94041"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "1",
        "national_number": "4089672222",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "1",
        "national_number": "4081234567"
      }
    ],
    "category": "1004",
    "sub_category": "2940",
    "merchant_category_code": "3011",
    "date_business_established": "2001-01-17",
    "date_of_registration": "2011-04-17",
    "dispute_email": "dispute@example.com",
    "business_sales_details": {
      "average_price": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "USD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "USD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://example.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "1",
        "national_number": "4089673333",
        "extension_number": "123"
      },
      "message": [
        {
          "type": "ONLINE",
          "headline": "headline1",
          "logo_image_url": "https://example.com/logoimage/",
          "service_image_url": "https://example.com/serviceimageurl1/",
          "seller_message": "seller message"
        },
        {
          "type": "RETAIL",
          "headline": "headline2",
          "logo_image_url": "https://example.com/logoimageurl2/",
          "service_image_url": "https://example.com/serviceimageurl2/",
          "seller_message": "seller message"
        }
      ]
    }
  },
  "account_status": "A",
  "account_currency": "USD",
  "secondary_currency": [
    "CAD",
    "JPY"
  ],
  "payment_receiving_preferences": {
    "block_unconfirmed_us_address_payments": true,
    "block_non_us_payments": true,
    "block_echeck_payments": true,
    "block_cross_currency_payments": true,
    "block_send_money_payments": true,
    "alternate_payment_url": "www.original.com",
    "display_instructions_text_input": true,
    "cc_soft_descriptor": "USCCSOFTDES",
    "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
    {
      "type": "PARTNER"
    }
  ],
  "account_permissions": [
    {
      "permissions": [
        "EXPRESS_CHECKOUT",
        "RECURRING_PAYMENT",
        "EXTENDED_PRO_PROCESSING",
        "EXCEPTION_PROCESSING",
        "MASS_PAY",
        "ENCRYPTED_WEBSITE_PAYMENTS"
      ]
    }
  ],
  "timezone": "America/Los_Angeles",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true,
  "links": [
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Show managed account balance

GET /v1/customer/partners/merchant-accounts/{merchant_payer_id}/balances
Shows details for a managed account balance by merchant payer ID. Balance includes the available, negative, and pending balances.

Path parameters

  • merchant_payer_id

    string

    required

    The payer ID of the merchant for which to show account balances.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC/balances \
-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 the managed account balance.
  • payer_id

    string

    An immutable account identifier which identifies the PayPal account.

    Minimum length: 13.

    Maximum length: 13.

    Pattern: ^[2-9A-HJ-NP-Z]{13}$.

  • available_balances

    array (contains the money object)

    This field contains the total available balances based on currency.
  • pending_balances

    array (contains the money object)

    This field contains the total pending reversal balances based on currency.

Sample Response

{
  "payer_id": "9KGJMW85LN4KC",
  "available_balances": [
    {
      "currency_code": "USD",
      "value": "3000"
    },
    {
      "currency_code": "CAD",
      "value": "-100"
    },
    {
      "currency_code": "EUR",
      "value": "0"
    }
  ],
  "pending_balances": [
    {
      "currency_code": "USD",
      "value": "0"
    },
    {
      "currency_code": "CAD",
      "value": "0"
    },
    {
      "currency_code": "EUR",
      "value": "0"
    }
  ]
}

Show financial instrument details

GET /v1/customer/partners/merchant-accounts/{merchant_payer_id}/financial-instruments
Shows financial instrument details for a managed account.

Path parameters

  • merchant_payer_id

    string

    required

    The merchant ID.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/9KGJMW85LN4KC/financial-instruments \
-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 the financial instrument details for the managed account.
  • financial_instruments

    array (contains the financial_instrument object)

    An array of financial instruments.

Sample Response

{
  "financial_instruments": [
    {
      "type": "BANK",
      "id": "BA-HS6DWCX4ETHL4",
      "account_type": "CHECKING",
      "account_number": "5258",
      "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
      "routing_number": "081500875",
      "currency_code": "USD",
      "country_code": "US",
      "account_holder_details": {
        "name": "My company Inc"
      },
      "bank_name": "Bank of America",
      "branch_location": "North 1st street",
      "links": {
        "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
        "rel": "self",
        "method": "PATCH"
      }
    }
  ]
}

Common object definitions

account_holder_details

  • name

    string

    The name on the account holder's bank account.
  • type

    enum

    The type of bank account, which is business or individual. The possible values are:
    • BUSINESS. A business bank account.
    • INDIVIDUAL. An individual bank account
  • identifier

    object

    The details of the account holder's ID.

account_holder_identifier

  • type

    enum

    The account holder's ID type. The possible values are:
    • NATIONAL_ID. The ID type is a national ID.
    • TAX_ID. The ID is a tax ID.
  • value

    string

    The account holder's ID value.

account_owner_relationship

  • name

    object

    required

    The name of the familial relation.
  • relation

    enum

    required

    The type of familial relationship.

    Possible values: MOTHER.

  • country_code_of_nationality

    string

    required

    The country code for the nationality of the familial relation.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

account_permission

  • third_party

    string

    The third-party ID for the account.
  • permissions

    array (contains the permissions object)

    The permission to assign to the account.
    Note: The SETTLEMENT_CONSOLIDATION permissions is not applicable to all partners.
    PermissionDescription
    DIRECT_PAYMENTProcesses direct credit card transactions for the managed account by using PayPal Payments Pro, if the account is enabled for it. Provides access to the DoDirectPayment API.
    EXPRESS_CHECKOUTProcesses Express Checkout transactions. Provides access to these APIs:
    • SetExpressCheckout
    • GetExpressCheckoutDetails
    • DoExpressCheckoutPayment
    • GetPalDetails
    If you are subscribed to any of the following reports, this permission consolidates the reporting information from the managed account into your reports:
    • Preapproved Payment Agreement Report
    • Subscription Agreement Report
    • Order Report
    RECURRING_PAYMENTProcesses recurring payments for the managed account. Provides access to these APIs:
    • BillAgreementUpdate
    • BillUser
    • SetCustomerBillingAgreement
    • GetBillingAgreementCustomerDetails
    • CreateBillingAgreement
    • DoReferenceTransaction
    EXTENDED_PRO_PROCESSINGCompletes back-end processing functions for the managed account. Provides access to these APIs:
    • DoCapture
    • DoAuthorization
    • DoReauthorization
    • DoVoid
    This permission also allows you to use PayPal’s batch processing, if you are enabled for it, to perform batch captures on behalf of the managed account.
    EXCEPTION_PROCESSINGCompletes certain customer service functions for the managed account. Provides access to these APIs:
    • RefundTransaction
    • TransactionSearch
    • GetTransactionDetails
    If you are subscribed to any of the following reports, this permission consolidates the reporting information from the managed account into your reports:
    • Transaction Detail Report
    • Case Report
    This permission also allows you to use PayPal’s batch processing, if you are enabled for it, to complete batch captures on behalf of the managed account.
    SETTLEMENT_CONSOLIDATIONConsolidates funds from the managed account into your account on a daily basis. With this permission set, PayPal sweeps all funds from the managed account into your account on a daily basis. If the managed account balance is negative, PayPal deducts the negative balance from your account to true-up the account’s balance back to zero.
    If you are subscribed to any of the following reports, this permission consolidates the reporting information from the managed account into your reports:
    • Transaction Detail Report
    • Settlement Report
    SETTLEMENT_REPORTINGConsolidates reporting information from the managed account into your account.
    If you are subscribed to any of the following reports, this permission consolidates the reporting information from the managed account into your reports:
    • Transaction Detail Report
    • Settlement Report
    MASS_PAYMakes payments from the managed account using PayPal’s MassPay API.
    ENCRYPTED_WEBSITE_PAYMENTSEncrypts standard PayPal payments buttons on behalf of the managed account using PayPal’s Encrypted Website Payments feature.
    DISPUTE_RESOLUTIONResponds to disputes on behalf of the managed account. With this permission set, disputes opened against the campaign appear in the Resolution Center for your account.
    SHARED_REFUNDProcesses refunds against your own account for transactions originally accepted by the managed account.
    SHARED_AUTHORIZATIONCaptures transactions using your own account against authorizations originally obtained by the managed account.
    VIEW_BALANCERetrieves the managed account’s PayPal balance. Provides access to the following GetBalance API.
    VIEW_PROFILEShows the managed account’s profile.
    EDIT_PROFILEEdits the managed account’s profile.

account_relationship

  • subject_payer_id

    string

    The payer ID of the subject.
  • type

    enum

    required

    The type of relationship.

    Possible values: PARTNER, SAME_MERCHANT.

account_status

  • account_status

    enum

    The account status.

    Possible values: A, PV, PUA.

address

  • type

    enum

    required

    The address type. The possible values are:
    • HOME. The home address.
    • WORK. The work address.
    • PRINCIPAL_BUSINESS. The principal business address.
    • REGISTERED_OFFICE. The registered office address.
    • MAILING_ADDRESS. The mailing address.
  • line1

    string

    required

    The first line of the address. For example, number, street, and so on. Maximum length is 300 characters.

    Maximum length: 300.

  • line2

    string

    The second line of the address. For example, the suite or apartment number.

    Maximum length: 300.

  • line3

    string

    The third line of the address. For example, the street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

    Maximum length: 300.

  • suburb

    string

    The suburb or neighborhood.

    Maximum length: 300.

  • city

    string

    required

    The city.

    Maximum length: 120.

  • state

    string

    The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
  • country_code

    string

    required

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
  • postal_code

    string

    The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See Postal code.

address_portable_postal_code_validation

  • address_portable_postal_code_validation

bank_account

  • id

    string

    The PayPal-generated ID for the bank account.

    Read only.

  • last_4_digits

    string

    The last four digits of bank account number.

    Read only.

    Pattern: [0-9]{4}.

  • account_number

    string

    required

    The account number in either:

    Maximum length: 34.

  • account_number_type

    enum

    required

    The type of bank account number. The possible values are:
  • account_type

    enum

    The type of bank account. The possible values are:
    • SAVINGS. A savings account.
    • CHECKING. A checking account.

    Default: CHECKING.

  • routing_number

    string

    The routing transit number, or bank code, of the bank. Typically used for domestic accounts only. For international accounts, the IBAN includes the bank code.

    Maximum length: 34.

  • bic

    string

    The bank identification code (BIC) for countries that support BIC.

    Maximum length: 16.

  • currency_code

    string

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

    Minimum length: 3.

    Maximum length: 3.

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • account_holder_details

    object

    The details for the account holder who owns the bank account.
  • branch_code

    string

    The branch code of the bank account.

    Maximum length: 16.

  • bank_name

    string

    The name of the bank.

    Maximum length: 34.

  • branch_location

    string

    The branch location of the bank.

    Maximum length: 34.

business_info

  • type

    enum

    required

    The type of business, such as corporation or sole proprietorship.

    Possible values: INDIVIDUAL, PROPRIETORSHIP, PARTNERSHIP, CORPORATION, NONPROFIT, GOVERNMENT, PUBLIC_COMPANY, REGISTERED_COOPERATIVE, PROPRIETORY_COMPANY, ASSOCIATION, PRIVATE_CORPORATION, LIMITED_PARTNERSHIP, LIMITED_LIABILITY_PROPRIETORS, LIMITED_LIABILITY_PRIVATE_CORPORATION, LIMITED_LIABILITY_PARTNERSHIP, PUBLIC_CORPORATION, OTHER_CORPORATE_BODY.

  • sub_type

    string

    The business sub-type. Value is ASSO_TYPE_INCORPORATED, ASSO_TYPE_NON_INCORPORATED, GOVT_TYPE_EMANATION, GOVT_TYPE_ENTITY, GOVT_TYPE_ESTD_COMM, GOVT_TYPE_ESTD_FC, GOVT_TYPE_ESTD_ST_TR, or UNSELECTED.
  • government_body

    object

    The government body.
  • place_of_establishment

    object

    The place of establishment.
  • names

    array (contains the name object)

    required

    An array of different names for the business. For example, the legal name and the stock-trading name.
    Note: You must set at least one /names/type to LEGAL.
  • identifications

    array (contains the identification object)

    An array of identification documents for the business.
    US only: This field is only required when type is set to CORPORATION, PARTNERSHIP, or GOVERNMENT.
  • employer_identification_number

    string

    Deprecated. EIN ID. US only. Use business_info/identifications for non-US accounts.

    Pattern: ^\d+$.

  • phones

    array (contains the phone_with_type object)

    required

    An array of phones for the business. Includes the type, which is BUSINESS or WORK. Requires at least one phone number.
  • category

    string

    The category of the business. Either merchant_category_code or both category and sub_category are required.

    Minimum length: 4.

    Maximum length: 4.

  • sub_category

    string

    The sub-category of the business. Either merchant_category_code or both category and sub_category are required.

    Minimum length: 4.

    Maximum length: 4.

  • merchant_category_code

    string

    A merchant category code. Either merchant_category_code or both category and sub_category are required.

    Minimum length: 4.

    Maximum length: 4.

  • date_business_established

    string

    The date when the merchant's business was established, in Internet date and time full-date format.
  • date_of_registration

    string

    The date when the business was registered, in Internet date and time full-date format.
  • dispute_email

    string

    The email address to which to send disputes, in Simple Mail Transfer Protocol as defined in RFC 5321 or in Internet Message Format as defined in RFC 5322. Does not support Unicode email addresses.
  • vat_id

    string

    Deprecated. Use business_info/identifications.

    Pattern: ^\d+$.

  • vat_country_code

    string

    Deprecated. Use business_info/identifications.
  • business_sales_details

    object

    The details of business sales.
  • customer_service

    object

    The customer service information.
  • addresses

    array (contains the address object)

    required

    An array of merchant addresses.
  • country_code_of_incorporation

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
  • stakeholders

    array (contains the stakeholder object)

    An array of business stakeholder information.
  • designation

    object

    The business owner title and area.

business_owner_info

  • email

    string

    required

    The account holder's email address, in Simple Mail Transfer Protocol as defined in RFC 5321 or in Internet Message Format as defined in RFC 5322. Does not support Unicode email addresses.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • name

    object

    required

    The account holder's name.
  • account_owner_relationships

    array (contains the account_owner_relationship object)

    An array of relationships for the account holder.
  • country_code_of_nationality

    string

    required

    The two-character IS0-3166-1 country code of the account holder's country of residence.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • addresses

    array (contains the address object)

    required

    An array of addresses for the account holder.
  • date_of_birth

    string

    The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD. Not required for all countries.

    Minimum length: 10.

    Maximum length: 10.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

  • ssn

    string

    Deprecated. Social security number. For US account holders only. For non-US accounts, use owner_info/identifications.

    Pattern: ^\d+$.

  • language_code

    string

    The language code for the account holder's preferred language.
  • phones

    array (contains the phone_with_type object)

    An array of phone numbers for the account holder. Includes the type, which is HOME or MOBILE.
  • identifications

    array (contains the identification object)

    An array of identification documents for the account holder. This field is only required when /business_info/type is set to INDIVIDUAL or PROPRIETORSHIP. When required, this property must contain an identification whose type is set to SOCIAL_SECURITY_NUMBER.
  • occupation

    string

    The account holder's occupation.

business_sales_details

  • average_price

    object

    The average transaction price.
  • average_monthly_volume

    object

    The average volume of monthly sales.
  • sales_venues

    array (contains the sales_venue object)

    An array of sales venues for the business.
  • website

    string

    The primary URL of the business.

    Maximum length: 255.

  • revenue_from_online_sales

    object

    The percentage of revenue attributable to online sales.

country_code

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

country_code

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

create_account

  • owner_info

    object

    required

    The account holder's information.
  • business_info

    object

    required

    The business information for the merchant.
  • account_status

    enum

    The account status.

    Possible values: A, PV, PUA.

  • account_currency

    string

    required

    The three-character ISO-4217 currency code for the account.

    Minimum length: 3.

    Maximum length: 3.

  • secondary_currency

    array (contains the currency_code object)

    An array of the three-character ISO-4217 currency codes for the secondary currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    enum

    The time zone.

    Possible values: Pacific/Honolulu, America/Anchorage, America/Los_Angeles, America/Phoenix, America/Denver, America/Chicago, America/Indianapolis, America/New_York, America/Puerto_Rico, America/Vancouver, America/Dawson_Creek, America/Edmonton, America/Regina, America/Winnipeg, America/Atikokan, America/Toronto, America/Halifax, America/Goose_Bay, America/Blanc-Sablon, America/St_Johns, America/Tijuana, America/Hermosillo, America/Chihuahua, America/Mexico_City, America/Rio_Branco, America/Manaus, America/Campo_Grande, America/Argentina/Buenos_Aires, America/Sao_Paulo, America/Fortaleza, America/Noronha, America/Thule, America/Godthab, America/Scoresbysund, America/Danmarkshavn, Atlantic/Azores, Europe/Lisbon, Europe/Dublin, Europe/London, Europe/Luxembourg, Europe/Berlin, Atlantic/Faroe, Europe/Oslo, Europe/Copenhagen, Europe/Stockholm, Europe/Helsinki, Europe/Prague, Europe/Bratislava, Europe/Athens, Europe/Istanbul, Africa/Johannesburg, Asia/Jerusalem, Asia/Dubai, Europe/Kaliningrad, Europe/Kiev, Europe/Moscow, Europe/Samara, Asia/Yekaterinburg, Asia/Omsk, Asia/Krasnoyarsk, Asia/Irkutsk, Asia/Yakutsk, Asia/Vladivostok, Asia/Magadan, Asia/Kamchatka, Asia/Calcutta, Asia/Bangkok, Asia/Jakarta, Asia/Saigon, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Hong_Kong, Asia/Makassar, Asia/Manila, Asia/Taipei, Asia/Shanghai, Asia/Seoul, Asia/Tokyo, Asia/Jayapura, Australia/Perth, Australia/Darwin, Australia/Adelaide, Australia/Hobart, Australia/Sydney, Australia/Brisbane, Australia/Lord_Howe, Pacific/Auckland, Pacific/Chatham, Pacific/Niue, Pacific/Fakaofo, Pacific/Rarotonga, Europe/Bucharest, GMT.

  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account allows the merchant to log in.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
  • signup_options

    object

    The options, preferences, and agreements for the account.
  • financial_instruments

    array

    An array of financial instruments.

create_account_response

  • payer_id

    string

    The payer ID. If the account was not created, this value is blank.

    Maximum length: 127.

  • partner_merchant_external_id

    string

    The partner-specified ID for the account, which was passed in the partner_merchant_external_id request parameter.

    Maximum length: 127.

  • merchant_authorization_code

    string

    The merchant authorization code.
  • custom_data

    array (contains the keyvalue object)

    An array of key-and-value pairs that contain custom data. For example, aa_token: token.
  • errors

    array (contains the error object)

    An array of errors, if any, that occurred during account creation.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

currency_code

currency_code

customer_service

customer_service_message

  • type

    enum

    required

    The type of customer service message.

    Possible values: ONLINE, RETAIL.

  • headline

    string

    The headline.

    Maximum length: 50.

  • logo_image_url

    string

    The logo image URL.

    Maximum length: 255.

  • service_image_url

    string

    The service image URL.

    Maximum length: 255.

  • seller_message

    string

    required

    The seller message.

    Maximum length: 2000.

date_no_time

  • date_no_time

    string

    The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

    Minimum length: 10.

    Maximum length: 10.

    Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

designation

  • title

    string

    The business owner title.
  • business_area

    string

    The organizational unit that corresponds to the specific business segment or area of responsibility in a company.

email_address

  • email_address

    string

    The internationalized email address.
    Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

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. Used for correlation purposes.
  • information_link

    string

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

    Read only.

  • 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.

    Read only.

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. Used for correlation purposes.
  • information_link

    string

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

    Read only.

  • 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.

    Read only.

error_details

  • field

    string

    The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. 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. Value is body, path, or query.

    Default: body.

  • issue

    string

    required

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

    string

    The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

error_details

  • field

    string

    The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. 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. Value is body, path, or query.

    Default: body.

  • issue

    string

    required

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

    string

    The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

financial_instrument

  • type

    enum

    The financial instrument type. Currently supports BANK only. The possible values are:
    • . The financial instrument type. Currently supports BANK only.
  • id

    string

    The PayPal-generated financial instrument ID.
  • account_type

    enum

    required

    The bank account type. The possible values are:
    • . The bank account type.
    • . The bank account type.
  • id

    string

    The PayPal-generated ID for the bank account.

    Read only.

  • last_4_digits

    string

    The last four digits of bank account number.

    Read only.

    Pattern: [0-9]{4}.

  • account_number

    string

    required

    The account number in either:

    Maximum length: 34.

  • account_number_type

    enum

    required

    The type of bank account number. The possible values are:
  • account_type

    enum

    The type of bank account. The possible values are:
    • SAVINGS. A savings account.
    • CHECKING. A checking account.

    Default: CHECKING.

  • routing_number

    string

    The routing transit number, or bank code, of the bank. Typically used for domestic accounts only. For international accounts, the IBAN includes the bank code.

    Maximum length: 34.

  • bic

    string

    The bank identification code (BIC) for countries that support BIC.

    Maximum length: 16.

  • currency_code

    string

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

    Minimum length: 3.

    Maximum length: 3.

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region.
    Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

  • account_holder_details

    object

    The details for the account holder who owns the bank account.
  • branch_code

    string

    The branch code of the bank account.

    Maximum length: 16.

  • bank_name

    string

    The name of the bank.

    Maximum length: 34.

  • branch_location

    string

    The branch location of the bank.

    Maximum length: 34.

financial_instruments

  • financial_instruments

    array (contains the financial_instrument object)

    An array of financial instruments.

get_merchant_account_balance_response

  • payer_id

    string

    An immutable account identifier which identifies the PayPal account.

    Minimum length: 13.

    Maximum length: 13.

    Pattern: ^[2-9A-HJ-NP-Z]{13}$.

  • available_balances

    array (contains the money object)

    This field contains the total available balances based on currency.
  • pending_balances

    array (contains the money object)

    This field contains the total pending reversal balances based on currency.

get_merchant_account_response

  • owner_info

    object

    The account holder's information.
  • business_info

    object

    The business information for the merchant.
  • account_status

    string

    The account status.
  • account_currency

    string

    The currency code for the account.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies. In addition to the account currency, the managed account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relationship object)

    An array of account relationships between the parent and this account.
  • account_permissions

    array (contains the account_permission object)

    An array of permissions to assign to the account.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the managed account.
    Note: You cannot fetch this information.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether the account enables the merchant to log in. You cannot log in to accounts that are only managed by their parent.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes for the account.
    Note: You cannot fetch this information.
  • signup_options

    object

    The partner options to assign to the managed account.
  • errors

    array (contains the error object)

    An array of errors for adding bundles to a given customer account.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

government_body

  • name

    string

    The name of enabling legislation.

identification

  • type

    enum

    required

    The type of document to use for identification.

    Possible values: ASSOCIATION_NUMBER, BUSINESS_NUMBER, BUSINESS_REGISTRATION_NUMBER, CNPJ, COMPANY_NUMBER, COOPERATIVE_NUMBER, CPF, DRIVERS_LICENSE, EMPLOYMENT_IDENTIFICATION_NUMBER, IMMIGRANT_ID, INDIVIDUAL_TAX_IDENTIFICATION_NUMBER, MEDICAL_INSURANCE_ID, NATIONAL_ID, PASSPORT_NUMBER, PENSION_FUND_ID, SOCIAL_INSURANCE_NUMBER, SOCIAL_SECURITY_NUMBER, VALUE_ADDED_TAX_ID.

  • value

    string

    required

    The document number.
  • masked

    boolean

    Indicates whether the value is a partial value. Use when the identifier type supports a partial value, such as a four-digit SSN number, instead of the full nine digits. This flag may not always be honored based on the context in which it is used.
  • issuer_country_code

    string

    required

    The two-character IS0-3166-1 country code of the country that issued the identity document.

    Pattern: ^[A-Z]([A-Z]|\d)$.

  • issuer_state

    string

    The state or province code for the state or province that issued the identity document.
  • issuer_city

    string

    The city that issued the identity document. Applies only to certain types of documents, such as trade_registration_number documents.
  • place_of_issue

    string

    The name of the place that issued the identity document. Applies only to some types, such as TAX_ID for Turkey (TR).
  • issuer_description

    string

    A description of the entity that issued the identity document. For example, registration authority.

keyvalue

  • key

    string

    A key. For example aa_token.
  • value

    string

    The value of the key.

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.

    Maximum length: 32.

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

money_range

  • minimum_amount

    object

    required

    The minimum inclusive value of the range.
  • maximum_amount

    object

    required

    The maximum inclusive value for the range.

name

  • type

    enum

    required

    The legal category of the business. The possible values are:
    • LEGAL. Legal business.
    • DOING_BUSINESS_AS. Doing business as.
    • STOCK_TRADING_NAME. Stock-trading name.
  • name

    string

    required

    The name of the business.

    Maximum length: 300.

name

  • prefix

    string

    The prefix, or title, to the party's name.

    Maximum length: 140.

  • given_name

    string

    When the party is a person, the party's given, or first, name.

    Maximum length: 140.

  • surname

    string

    When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

    Maximum length: 140.

  • middle_name

    string

    When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

    Maximum length: 140.

  • suffix

    string

    The suffix for the party's name.

    Maximum length: 140.

  • alternate_full_name

    string

    DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

    Maximum length: 300.

  • full_name

    string

    When the party is a person, the party's full name.

    Maximum length: 300.

name_validation

  • name_validation

notification_options

  • suppress_welcome_email

    boolean

    Indicates whether to suppress the welcome email. By default, a welcome email is sent. To suppress the welcome email, set to TRUE.
  • ipn_notify_url

    string

    The URL to post an IPN notification.
  • reminder_email_frequency

    enum

    The frequency with which the reminder email is sent to the PayPal user after he or she creates an account. Value is:
    • DEFAULT. All reminder emails are sent.
    • NONE. No reminder emails are sent.

    Possible values: DEFAULT, NONE.

partner_options

  • partner_fields

    array (contains the keyvalue object)

    An array of key-and-value pairs that contain custom partner information.

patch

  • op

    enum

    required

    The operation. The possible values are:
    • add. Depending on the target location reference, completes one of these functions:
      • The target location is an array index. Inserts a new value into the array at the specified index.
      • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
      • The target location is an object parameter that does exist. Replaces that parameter's value.
      The value parameter defines the value to add. For more information, see 4.1. add.
    • remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
    • replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
    • move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
    • copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.
    • test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
      TypeConsidered equal if both values
      stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
      numbersAre numerically equal.
      arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
      objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
      literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
      For more information, see 4.6. test.
  • path

    string

    The JSON Pointer to the target document location at which to complete the operation.
  • value

    number,integer,string,boolean,null,array,object

    The value to apply. The remove operation does not require a value.
  • from

    string

    The JSON Pointer to the target document location from which to move the value. Required for the move operation.

patch_request

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

payer_id

  • payer_id

    string

    The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.

    Minimum length: 13.

    Maximum length: 13.

    Pattern: ^[2-9A-HJ-NP-Z]{13}$.

payment_receiving_preferences

  • block_unconfirmed_us_address_payments

    boolean

    Indicates whether to block payments to this account from US buyers who do not provide a confirmed shipping address. To block, set to TRUE.
  • block_non_us_payments

    boolean

    Indicates whether to block payments to this account from buyers who reside outside of the United States. To block, set to TRUE.
  • block_echeck_payments

    boolean

    Indicates whether to block eCheck payments. To block, set to TRUE.
  • block_cross_currency_payments

    boolean

    Indicates whether to block payments made in currencies that are not held by this account. To block, set to TRUE.
  • block_send_money_payments

    boolean

    Indicates whether to block payments to this account from the PayPal Send Money page. To block, set to TRUE.
  • alternate_payment_url

    string

    The alternative payments URL to use in place of the PayPal Send Money page. If you enable block_send_money_payments, specify an alternative payments URL to redirect a user who clicks Send Money.
  • display_instructions_text_input

    boolean

    Indicates whether to show the Special instructions to merchant field during checkout, unless the field is suppressed through other means. To display special instructions, set to TRUE.
  • cc_soft_descriptor

    string

    The name of the campaign that appears on the buyer’s bank or credit card statement. Supports only capital letters, numbers, spaces, and the ., -, and * special characters. Include one alphanumeric character with special characters.

    Minimum length: 2.

    Maximum length: 11.

  • cc_soft_descriptor_extended

    string

    The name of the business that appears on the buyer’s bank or credit card statement. Supports only capital letters, numbers, spaces, and the ., -, and * special characters. Include one alphanumeric character with special characters.

    Minimum length: 2.

    Maximum length: 19.

percent_range

  • minimum_percent

    number

    required

    The minimum inclusive value of the range.

    Minimum value: 0.

    Maximum value: 99.

  • maximum_percent

    number

    required

    The maximum inclusive value of the range.

    Minimum value: 1.

    Maximum value: 100.

permissions

  • permissions

    enum

    A permission type to assign to the account.

    Possible values: DIRECT_PAYMENT, EXPRESS_CHECKOUT, RECURRING_PAYMENT, EXTENDED_PRO_PROCESSING, EXCEPTION_PROCESSING, SETTLEMENT_CONSOLIDATION, SETTLEMENT_REPORTING, MASS_PAY, ENCRYPTED_WEBSITE_PAYMENTS, DISPUTE_RESOLUTION, SHARED_REFUND, SHARED_AUTHORIZATION, INHERIT_ACCOUNT_SETTINGS, WITHDRAW_FUNDS, VIEW_BALANCE, VIEW_PROFILE, ACCOUNT_MGMT, EDIT_PROFILE.

phone

  • country_code

    string

    required

    The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

    Minimum length: 1.

    Maximum length: 3.

    Pattern: ^[0-9]{1,3}?$.

  • national_number

    string

    required

    The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

    Minimum length: 1.

    Maximum length: 14.

    Pattern: ^[0-9]{1,14}?$.

  • extension_number

    string

    The extension number.

    Minimum length: 1.

    Maximum length: 15.

    Pattern: ^[0-9]{1,15}?$.

phone_with_type

  • type

    enum

    required

    The type of phone.

    Possible values: HOME, MOBILE, BUSINESS, WORK, CUSTOMER_SERVICE, FAX, OTHER, PAGER.

  • country_code

    string

    required

    The country calling code (CC), as defined by the E.164 numbering plan. The combined length of the country code and the national number cannot exceed 15 digits.

    Minimum length: 1.

    Maximum length: 3.

    Pattern: ^[0-9]{1,3}?$.

  • national_number

    string

    required

    The national number, as defined by the E.164 numbering plan. The combined length of of the country code and the national number cannot exceed 15 digits. The national number consists of national destination code (NDC) and subscriber number (SN).

    Minimum length: 1.

    Maximum length: 14.

    Pattern: ^[0-9]{1,14}?$.

  • extension_number

    string

    The extension number.

    Minimum length: 1.

    Maximum length: 15.

    Pattern: ^[0-9]{1,15}?$.

place_of_birth

place_of_establishment

sales_venue

  • type

    enum

    The type of sales venue for the business.

    Possible values: EBAY, ANOTHER_MARKET_PLACE, OWN_WEB_SITE, OTHER.

  • ebay_id

    string

    The eBay ID.
  • description

    string

    The description of the business sales venue.

signup_options

  • partner_options

    object

    The partner-specific options for the account.
  • legal_agreements

    array (contains the legal_agreement object)

    An array of legal agreements.
  • web_experience_preference

    object

    The web experience preferences for the customer.
  • notification_options

    object

    The notification options.

stakeholder

  • ownership_percentage

    string

    The percentage ownership for a stakeholder. Pertains only to the BENEFICIAL_OWNER type.
  • type

    enum

    The type of stakeholder in the business.

    Possible values: CHAIRMAN, PARTNER, PARTNER_BUSINESS, SECRETARY, TREASURER, DIRECTOR, BENEFICIAL_OWNER, BENEFICIAL_OWNER_BUSINESS.

  • country_code_of_nationality

    string

    The two-character IS0-3166-1 country code of the country of residence.
  • date_of_birth

    string

    The date of birth, in Internet date and time full-date format. Supports the YYYY-MM-DD format.
  • name

    object

    The name of the stakeholder.
  • addresses

    array (contains the address object)

    An array of stakeholder addresses.
  • phones

    array (contains the phone_with_type object)

    An array of stakeholder phone numbers. Includes phone type.
  • identifications

    array (contains the identification object)

    An array of stakeholder identification documents.
  • place_of_birth

    object

    The place of birth.

timezone

  • timezone

    enum

    The time zone.

    Possible values: Pacific/Honolulu, America/Anchorage, America/Los_Angeles, America/Phoenix, America/Denver, America/Chicago, America/Indianapolis, America/New_York, America/Puerto_Rico, America/Vancouver, America/Dawson_Creek, America/Edmonton, America/Regina, America/Winnipeg, America/Atikokan, America/Toronto, America/Halifax, America/Goose_Bay, America/Blanc-Sablon, America/St_Johns, America/Tijuana, America/Hermosillo, America/Chihuahua, America/Mexico_City, America/Rio_Branco, America/Manaus, America/Campo_Grande, America/Argentina/Buenos_Aires, America/Sao_Paulo, America/Fortaleza, America/Noronha, America/Thule, America/Godthab, America/Scoresbysund, America/Danmarkshavn, Atlantic/Azores, Europe/Lisbon, Europe/Dublin, Europe/London, Europe/Luxembourg, Europe/Berlin, Atlantic/Faroe, Europe/Oslo, Europe/Copenhagen, Europe/Stockholm, Europe/Helsinki, Europe/Prague, Europe/Bratislava, Europe/Athens, Europe/Istanbul, Africa/Johannesburg, Asia/Jerusalem, Asia/Dubai, Europe/Kaliningrad, Europe/Kiev, Europe/Moscow, Europe/Samara, Asia/Yekaterinburg, Asia/Omsk, Asia/Krasnoyarsk, Asia/Irkutsk, Asia/Yakutsk, Asia/Vladivostok, Asia/Magadan, Asia/Kamchatka, Asia/Calcutta, Asia/Bangkok, Asia/Jakarta, Asia/Saigon, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Hong_Kong, Asia/Makassar, Asia/Manila, Asia/Taipei, Asia/Shanghai, Asia/Seoul, Asia/Tokyo, Asia/Jayapura, Australia/Perth, Australia/Darwin, Australia/Adelaide, Australia/Hobart, Australia/Sydney, Australia/Brisbane, Australia/Lord_Howe, Pacific/Auckland, Pacific/Chatham, Pacific/Niue, Pacific/Fakaofo, Pacific/Rarotonga, Europe/Bucharest, GMT.

web_experience_preference

  • partner_logo_url

    string

    The partner logo URL to show in the seller onboarding flow.
  • return_url

    string

    The URL to which to redirect the customer upon completion of the onboarding process.
  • return_url_description

    string

    The description of the return URL.
  • action_renewal_url

    string

    If renew_action_url expires, redirect the customer to this URL.
  • show_add_credit_card

    boolean

    Indicates whether to show an add credit card page.
  • show_mobile_confirm

    boolean

    Indicates whether to ask the customer to initiate confirmation of their mobile phone. This phone is the one that the partner defined as MOBILE in the customer data. Default is false.
  • use_mini_browser

    boolean

    Indicates whether to provide a single page signup flow in a mini browser. Default is false, which provides a full-size, multi-page flow.
  • use_hua_email_confirmation

    boolean

    Indicates whether to use the hosted_user_agreement_url to confirm the customer's email address. If TRUE, PayPal appends the email confirmation code to hosted_user_agreement_url. When a customer successfully accesses the hosted user agreement URL, PayPal confirms the customer's email address. If false, PayPal does not append the confirmation code to the URL and does not confirm the email address.

Additional API information

Error messages

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

  • INTERNAL_ERROR

    INTERNAL_ERROR. The process failed due to internal error.

  • PARTNER_BUSINESS_ERROR

    BUSINESS_ERROR. The caller is not a business account or the account is closed or locked.

  • PARTNER_BUSINESS_ERROR_FAILED_TO_SET_OAUTH_INTEGRATION

    FAILED_TO_SET_OAUTH_INTEGRATION. Failed to set OAuth integrations for partner and merchant.

  • PARTNER_BUSINESS_ERROR_FAILED_WHILE_GETTING_OAUTH_INTEGRATION

    FAILED_WHILE_GETTING_OAUTH_INTEGRATION. Failed to get OAuth integrations for partner and merchant.

  • PARTNER_BUSINESS_ERROR_MERCHANT_ID_SAME_AS_PARTNER_ID

    MERCHANT_ID_SAME_AS_PARTNER_ID. The merchant ID is same as the partner ID.

  • PARTNER_BUSINESS_ERROR_PARTNER_MERCHANT_CLIENT_ASSOC_ALREADY_PRESENT

    PARTNER_MERCHANT_CLIENT_ASSOC_ALREADY_PRESENT. Merchant client ID already exists for this PartnerId-MerchantId-PatrnerClientId combination.

  • PARTNER_BUSINESS_ERROR_PARTNER_MERCHANT_CLIENT_ID_COMBINATION_INCORRECT

    PARTNER_MERCHANT_CLIENT_ID_COMBINATION_INCORRECT. The combination of partnerClientId-merchantClientId is incorrect for this partnerId-merchantId.

  • PARTNER_BUSINESS_ERROR_PREFERENCES_ALREADY_EXIST

    PREFERENCES_ALREADY_EXIST. Preferences already exist for this partner account. Note: Use PATCH to update the content.

  • UNAUTHORIZED

    AUTHORIZATION_ERROR. This API call is not authorized.

  • UNAUTHORIZED_INVALID_PARTNER_RELATIONSHIP

    INVALID_PARTNER_RELATIONSHIP. The partner cannot use another partner for this API.

  • UNPROCESSABLE_ENTITY

    SUCCESS_WITH_WARNING. The request is not valid.

  • USER_BUSINESS_ERROR.

    USER_NOT_FOUND. This account ID is not associated with an account.

Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community