Managed Accounts API

Important: PayPal for Marketplaces 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 or contact us.

The Managed Accounts API enables a marketplace to add PayPal merchant accounts. It supports the Connected path and Managed path marketplace 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.

You can call the create merchant account, repopulate merchant account, and update merchant account API methods for the Managed path.

Partner merchant (resource group)

Enables you to create, partially update, update, and repopulate merchant accounts.

Create merchant account

POST /v1/customer/partners/merchant-accounts
Creates a merchant account. Submit the merchant 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_relations object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permissions 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 merchant 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": "sydney@example.com",
    "name": {
      "prefix": "Mr",
      "given_name": "Victoria",
      "surname": "Asmania",
      "middle_name": "T.",
      "suffix": ""
    },
    "country_code_of_nationality": "AU",
    "addresses": [
      {
        "type": "HOME",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      }
    ],
    "date_of_birth": "1990-01-01",
    "phones": [
      {
        "type": "HOME",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      },
      {
        "type": "MOBILE",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      }
    ],
    "identifications": [
      {
        "value": "LICENSE_ABCD123",
        "type": "DRIVERS_LICENSE",
        "issuer_country_code": "AU",
        "masked": false
      }
    ]
  },
  "business_info": {
    "type": "ASSOCIATION",
    "sub_type": "ASSO_TYPE_INCORPORATED",
    "names": [
      {
        "type": "LEGAL",
        "name": "AU Business"
      },
      {
        "type": "DOING_BUSINESS_AS",
        "name": "Doing Business As Name"
      }
    ],
    "identifications": [
      {
        "value": "123423456723",
        "type": "ASSOCIATION_NUMBER",
        "issuer_country_code": "AU",
        "masked": false
      }
    ],
    "addresses": [
      {
        "type": "REGISTERED_OFFICE",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      },
      {
        "type": "MAILING_ADDRESS",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      },
      {
        "type": "WORK",
        "line1": "200 Broadway Av",
        "line2": "",
        "city": "West Beach",
        "state": "South Australia",
        "country_code": "AU",
        "postal_code": "5024"
      }
    ],
    "phones": [
      {
        "type": "WORK",
        "country_code": "61",
        "national_number": "0491570156",
        "extension_number": "123"
      },
      {
        "type": "BUSINESS",
        "country_code": "61",
        "national_number": "0491570156"
      }
    ],
    "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": "AUD",
          "value": "10"
        },
        "maximum_amount": {
          "currency_code": "AUD",
          "value": "100"
        }
      },
      "average_monthly_volume": {
        "minimum_amount": {
          "currency_code": "AUD",
          "value": "1000"
        },
        "maximum_amount": {
          "currency_code": "AUD",
          "value": "2000"
        }
      },
      "sales_venues": [
        {
          "type": "EBAY",
          "ebay_id": "ebayid123",
          "description": "ebay venue"
        },
        {
          "type": "ANOTHER_MARKET_PLACE",
          "description": "description"
        }
      ],
      "website": "https://www.example.AU.com",
      "revenue_from_online_sales": {
        "minimum_percent": 0,
        "maximum_percent": 25
      }
    },
    "customer_service": {
      "email": "customer-service@example.com",
      "phone": {
        "country_code": "61",
        "national_number": "0491570156",
        "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"
        }
      ]
    },
    "country_code_of_incorporation": "AU",
    "stakeholders": [
      {
        "type": "CHAIRMAN",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "Victoria",
          "surname": "Asmania",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      },
      {
        "type": "SECRETARY",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "John",
          "surname": "Snow",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123JS",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      },
      {
        "type": "TREASURER",
        "country_code_of_nationality": "AU",
        "date_of_birth": "1992-01-01",
        "name": {
          "prefix": "Mr",
          "given_name": "Josh",
          "surname": "Snow",
          "middle_name": "T.",
          "suffix": "Jr."
        },
        "addresses": [
          {
            "type": "WORK",
            "line1": "200 Broadway Av",
            "line2": "",
            "city": "West Beach",
            "state": "South Australia",
            "country_code": "AU",
            "postal_code": "5024"
          }
        ],
        "phones": [
          {
            "type": "WORK",
            "country_code": "61",
            "national_number": "0491570156",
            "extension_number": "123"
          }
        ],
        "place_of_birth": {
          "city": "West Beach",
          "country_code": "AU"
        },
        "identifications": [
          {
            "value": "LICENSE_ABCD123JSY",
            "type": "DRIVERS_LICENSE",
            "issuer_country_code": "AU",
            "masked": false
          }
        ]
      }
    ]
  },
  "account_status": "A",
  "account_currency": "AUD",
  "secondary_currency": [
    "USD"
  ],
  "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": "Australia/Adelaide",
  "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 merchant 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.
  • 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": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "replace",
      "method": "POST"
    }
  ]
}

Repopulate merchant account

POST /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Repopulates information for a merchant 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_relations object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permissions 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 merchant 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": "demo-201@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 merchant 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.
  • 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": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
      "rel": "edit",
      "method": "POST"
    }
  ]
}

Partially update merchant account

PATCH /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Partially updates information for a merchant account, by merchant payer ID. For information about the paths where you can replace, add, or delete information, see update account in the update account in the Managed Onboarding Integration Guide.

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": "add",
    "path": "/financial_instruments",
    "value": [
      {
        "type": "BANK",
        "account_type": "CHECKING",
        "account_number": "34752318",
        "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"
      }
    ]
  }
]'

Response

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

Sample Response

204 No Content

Update merchant account

PUT /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Updates merchant 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

    object

    The account status.
  • account_currency

    object

    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 merchant account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relations object)

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

    array (contains the account_permissions object)

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

    object

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the merchant account. Note: This information is not available for retrieval.

    Maximum length: 127.

  • loginable

    boolean

    Whether the account allows the merchant to log in. Accounts managed by their parent only are not loginable.
  • partner_tax_reporting

    boolean

    Whether the partner reports taxes for the account. Note: This information is not available for retrieval.
  • signup_options

    object

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

    array (contains the error object)

    An array of errors that can occur when you add bundles to a 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 merchant account details

GET /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Shows details for a merchant 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 merchant account details.
  • owner_info

    object

    The account holder's information.
  • business_info

    object

    The business information for the merchant.
  • account_status

    object

    The account status.
  • account_currency

    object

    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 merchant account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relations object)

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

    array (contains the account_permissions object)

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

    object

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the merchant account. Note: This information is not available for retrieval.

    Maximum length: 127.

  • loginable

    boolean

    Whether the account allows the merchant to log in. Accounts managed by their parent only are not loginable.
  • partner_tax_reporting

    boolean

    Whether the partner reports taxes for the account. Note: This information is not available for retrieval.
  • signup_options

    object

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

    array (contains the error object)

    An array of errors that can occur when you add bundles to a 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"
    }
  ]
}

Partner merchant balance (resource group)

Enables you to get merchant balance based on merchant payer id.

Show merchant account balance

GET /v1/customer/partners/merchant-accounts/{merchant_payer_id}/balances
Shows details for a merchant account balance by merchant payer ID. Balance will include Available/Negative/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 merchant 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"
    }
  ]
}

Partner merchant fi (resource group)

Enables you to get merchant balance based on merchant payer id.

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.

    Possible values: BUSINESS, INDIVIDUAL.

  • identifier

    object

    The details of the account holder's ID.

account_holder_identifier

  • type

    enum

    The account holder's ID type.

    Possible values: NATIONAL_ID, 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_permissions

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

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

    Possible values: HOME, WORK, PRINCIPAL_BUSINESS, REGISTERED_OFFICE, 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, suite, apt number, and so on.

    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

    object

    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.

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. Value is:

    Possible values: BASIC_BANK_ACCOUNT_NUMBER, INTERNATIONAL_BANK_ACCOUNT_NUMBER, WIRE.

  • account_type

    enum

    The type of bank account. Value is CHECKING or SAVINGS.

    Possible values: SAVINGS, CHECKING.

    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 business_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

    object

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

    object

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

    object

    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

    object

    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

    object

    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_name

  • type

    enum

    required

    The legal category of the business.

    Possible values: LEGAL, DOING_BUSINESS_AS, STOCK_TRADING_NAME.

  • name

    string

    required

    The name of the business.

    Maximum length: 300.

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_relations object)

    required

    An array of account relationships.
  • account_permissions

    array (contains the account_permissions 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 merchant 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.
  • 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 that is 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 the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
  • value

    string

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

    string

    The location of the field that caused the error. Value is body, path, or query.

    Default: body.

  • issue

    string

    required

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

    string

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

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. Value is:

    Possible values: BASIC_BANK_ACCOUNT_NUMBER, INTERNATIONAL_BANK_ACCOUNT_NUMBER, WIRE.

  • account_type

    enum

    The type of bank account. Value is CHECKING or SAVINGS.

    Possible values: SAVINGS, CHECKING.

    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

    object

    The account status.
  • account_currency

    object

    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 merchant account can accept transactions in other currencies.
  • payment_receiving_preferences

    object

    The account preferences for receipt of payments.
  • account_relations

    array (contains the account_relations object)

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

    array (contains the account_permissions object)

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

    object

    The time zone.
  • partner_merchant_external_id

    string

    An ID that the partner creates for the merchant account. Note: This information is not available for retrieval.

    Maximum length: 127.

  • loginable

    boolean

    Whether the account allows the merchant to log in. Accounts managed by their parent only are not loginable.
  • partner_tax_reporting

    boolean

    Whether the partner reports taxes for the account. Note: This information is not available for retrieval.
  • signup_options

    object

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

    array (contains the error object)

    An array of errors that can occur when you add bundles to a 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

  • prefix

    string

    The prefix, or title, to the party name.

    Maximum length: 140.

  • given_name

    string

    The person party's given, or first, name.

    Maximum length: 140.

  • surname

    string

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

    Maximum length: 140.

  • middle_name

    string

    The person 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 for a business party name.

    Maximum length: 300.

  • full_name

    string

    The person party's full name.

    Maximum length: 300.

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 to complete.

    Possible values: add, remove, replace, move, copy, 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

    object

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

    object

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

Feedback

Have feedback?

Let us know.