Managed Accounts API

API Version

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 or contact us.

The Managed Accounts API enables a PayPal account holder to manage multiple PayPal accounts. These accounts are non-loginable, and the availability of the following REST API methods to create and manage these accounts is limited to partners who are approved for the Managed path solution.

Managed accounts (resource group)

Show managed account details based on a search criteria.

GET/v2/customer/managed-accounts

Show details for managed accounts, based on search criteria.

Query parameters

external_id
string
Description: The external_id query parameter can be used to request managed accounts with the given external_id.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/customer/managed-accounts?external_id=EXT-NEW \
-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 a list of managed account details.

managed_accounts
array (contains the account object)
Description: The managed accounts search results.

Sample Response

{
  "managed_accounts": []
}

Create managed account

POST/v2/customer/managed-accounts

Creates a managed account. Submit the account information in the JSON request body.

Header parameters

Prefer
string
Description: The preferred server response upon successful processing of the request. Value is:
Content-Type
string
required
Description: The supported media type, for example 'application/json'.
PayPal-Request-Id
string
required
Description: The server stores keys for 24 hours.

Request body

country_code
string
required
Description: The two-character ISO 3166-1 code that identifies the country or region.
email_id
string
required
Description: The ID of the managed account, as an email.
name
object
required
Description: The name of the account holder.
addresses
array (contains the personal_address object)
Description: An array of account holder addresses.
business_info
object
Description: The account's business information.
cc_soft_descriptor
string
Minimum length: 2.
Maximum length: 11.
Description: The name that appears on the buyer’s bank or credit card statement. Supports only capital letters, numbers, spaces, and the ., -, and * special characters. With special characters, you must include one alphanumeric character.
citizenship
string
Description: The two-character IS0-3166-1 country code of the account holder's citizenship.
date_of_birth
string
Description: The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD.
external_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner-provided ID of the managed account.
financial_instruments
object
Description: Array of financial instruments attached to the account.
identifications
array (contains the personal_identification object)
Description: An array of document numbers that verify a person's identity.
organization
string
Maximum length: 127.
Description: Organization this managed account belongs to in the partner’s hierarchy in the form of a path.
phones
array (contains the personal_phone object)
Description: An array of account holder phone numbers.
primary_currency_code
string
Description: The primary currency that this account holds. If you omit this value from the request, value is derived from the primary currency of the account's country.
secondary_currency_codes
array (contains the currency_code object)
Description: An array of additional currencies that this account can hold.
tax_id
object
Description: The account holder's tax ID.
terms_and_conditions_acceptance
object
Description: Indication that the account holder has accepted PayPal's terms and conditions.
user_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner's unique identifier for this user in their system.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/managed-accounts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440000" \
-d '{
  "external_id": "sample-user@example.com",
  "country_code": "US",
  "email_id": "unique@example.com",
  "name": {
    "prefix": "Mr.",
    "given_name": "John",
    "surname": "Collins",
    "middle_name": "Davis",
    "suffix": "Jr"
  },
  "addresses": [
    {
      "type": "HOME",
      "address_line_1": "150 E San Fernando St",
      "address_line_2": "apt #1",
      "admin_area_1": "CA",
      "admin_area_2": "San Jose",
      "postal_code": "95112",
      "country_code": "US"
    }
  ],
  "phones": [
    {
      "type": "MOBILE",
      "country_code": "1",
      "national_number": "4089679174"
    }
  ],
  "identifications": [
    {
      "type": "DRIVERS_LICENSE",
      "identifier": "G1111111",
      "issuer": {
        "country_code": "US",
        "jurisdiction": "CA",
        "authority": "DMV CA"
      }
    }
  ],
  "tax_id": {
    "type": "SOCIAL_SECURITY_NUMBER",
    "identifier": "123456789",
    "issuer": {
      "country_code": "US",
      "authority": "IRS"
    }
  },
  "citizenship": "US",
  "date_of_birth": "1990-01-01",
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "business_name": "Demo 201 Inc."
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "address_line_1": "585 Franklin Str",
        "address_line_2": "apt #1",
        "admin_area_1": "CA",
        "admin_area_2": "Mountain View",
        "postal_code": "94041",
        "country_code": "US"
      }
    ],
    "email_address": "customer-service@example.com",
    "phones": [
      {
        "type": "CUSTOMER_SERVICE",
        "country_code": "1",
        "national_number": "4089673333"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYER_IDENTIFICATION_NUMBER",
        "identifier": "111234501",
        "issuer": {
          "country_code": "US",
          "authority": "IRS"
        }
      }
    ],
    "date_of_incorporation": "2001-01-17",
    "business_category": {
      "merchant_category_code": "3011"
    },
    "website": "https://example.com",
    "stakeholders": [
      {
        "id": "ext_stakeholer_01",
        "ownership_percentage": "100.0",
        "type": "BENEFICIAL_OWNER",
        "name": {
          "prefix": "Mr.",
          "given_name": "John",
          "surname": "Collins",
          "middle_name": "Davis",
          "suffix": "Jr"
        },
        "citizenship": "US",
        "date_of_birth": "1990-01-01",
        "addresses": [
          {
            "address_line_1": "150 E San Fernando St",
            "address_line_2": "apt #1",
            "admin_area_1": "CA",
            "admin_area_2": "San Jose",
            "postal_code": "95112",
            "country_code": "US"
          }
        ],
        "phones": [
          {
            "country_code": "1",
            "national_number": "4089679174"
          }
        ],
        "identifications": [
          {
            "type": "DRIVERS_LICENSE",
            "identifier": "G1111111",
            "issuer": {
              "country_code": "US",
              "jurisdiction": "CA",
              "authority": "DMV CA"
            }
          }
        ],
        "tax_id": {
          "type": "SOCIAL_SECURITY_NUMBER",
          "identifier": "123456789",
          "issuer": {
            "country_code": "US",
            "authority": "IRS"
          }
        }
      }
    ]
  },
  "primary_currency_code": "USD",
  "secondary_currency_codes": [
    "CAD"
  ],
  "financial_instruments": {
    "banks": [
      {
        "mandate": {
          "reference_number": "12345678912345"
        },
        "account_number": "87460937",
        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
        "routing_number": "081500875",
        "bank_name": "Wells Fargo Bank",
        "bic": "WFBIUS6WFFX",
        "account_holder_details": {
          "name": "John Davis Collins",
          "type": "BUSINESS"
        }
      }
    ]
  },
  "cc_soft_descriptor": "sample-user",
  "terms_and_conditions_acceptance": {
    "acceptance_time": "2018-05-12T01:23:45.678Z",
    "accepted": true
  },
  "organization": "us/shops",
  "user_id": "sample-user"
}'

Response

If the Prefer request header is one of these values:

respond-async
respond-async, wait=preferred_wait_time_in_seconds, where the preferred_wait_time_in_seconds value is less than the time, in seconds, when the server can synchronously process the request. For example, respond-async, wait=3.

And, the API successfully queued the request for processing, returns the HTTP 202 Accepted status code and the request is processed asynchronously. If multiple respond-async requests are submitted for the same account, there is no guarantee about which request is processed. The duplicate check does not occur. Additionally:

If the Prefer header is return=representation, the server will return the entire account representation with an HTTP status of 201.
If no Prefer header is specified, then the response is the following elements with an HTTP status of 201:
- payer id
- external id
- links
If the Prefer header is respond-async, then the response body will be a single link with an HTTP status of 202.

links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.

Sample Response

{
  "payer_id": "7G4EPEEPEF74L",
  "external_id": "sample-user@example.com",
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
      "method": "GET"
    },
    {
      "rel": "edit",
      "href": "https://api-m.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
      "method": "PATCH"
    }
  ]
}

Partially update managed account

PATCH/v2/customer/managed-accounts/{id}

Partially updates information for a managed account, by merchant payer ID. For information about the paths where you can replace, add, or delete information, see Possible Pointers in the Managed Onboarding Integration Guide.

Header parameters

Prefer
string
Description: The preferred server response upon successful processing of the request. Value is:
Content-Type
string
required
Description: The supported media type, for example 'application/json'.

Path parameters

id
string
required
Description: The ID of the merchant.

Request body

patch_request
array (contains the patch object)
Description: An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "op": "add",
    "path": "/tax_id",
    "value": {
      "type": "SOCIAL_SECURITY_NUMBER",
      "identifier": "123456789",
      "issuer": {
        "country_code": "US",
        "authority": "IRS"
      }
    }
  }
]'

Response

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

addresses
array (contains the personal_address object)
Description: An array of addresses for the account holder.
business_info
object
Description: The account holder's business information.
capabilities
array (contains the capability object)
Read only.
Description: The capabilities of the account, and the additional fields and documents required to enable them.
cc_soft_descriptor
string
Minimum length: 2.
Maximum length: 11.
Description: The name 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.
citizenship
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character IS0-3166-1 country code of the account holder's citizenship.
Pattern: ^([A-Z]{2}|C2)$.
country_code
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character ISO 3166-1 code that identifies the country or region.
Pattern: ^([A-Z]{2}|C2)$.
date_of_birth
string
Minimum length: 10.
Maximum length: 10.
Description: The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.
email_id
string
Minimum length: 3.
Maximum length: 254.
Description: The ID of the managed account, as an email.
Pattern: ^.+@[^"\-].+$.
external_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner-provided ID of the managed account.
financial_instruments
object
Description: An array of financial instruments for the account.
identifications
array (contains the personal_identification object)
Description: An array of identification document numbers that verify the identity the account holder.
links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.
name
object
Description: The name of the party.
organization
string
Minimum length: 1.
Maximum length: 127.
Description: The organization to which this managed account belongs in the partner’s hierarchy, as a path.
payer_id
string
Read only.
Minimum length: 1.
Maximum length: 127.
Description: The ID of the managed account.
phones
array (contains the personal_phone object)
Description: An array of phone numbers for the account holder.
primary_currency_code
string
Minimum length: 3.
Maximum length: 3.
Description: The primary currency that this account can hold. If you omit this value from the request, the primary currency code is derived from the primary currency of the country for the account.
regulatory_obligations
array (contains the policy object)
Read only.
Description: The status of compliance and tax obligations for the account.
secondary_currency_codes
array (contains the currency_code object)
Description: Any additional currencies that this account can hold.
tax_id
object
Description: The tax ID of the account holder.
terms_and_conditions_acceptance
object
Description: The seller's consent to PayPal's terms and conditions.
user_id
string
Maximum length: 127.
Description: The partner's unique ID for this user in their system.

Sample Response

204 No Content

Show managed account details

GET/v2/customer/managed-accounts/{id}

Shows details for a managed account, by merchant payer ID.

Path parameters

id
string
required
Description: The payer ID of the merchant for which to show account details.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
-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.

addresses
array (contains the personal_address object)
Description: An array of addresses for the account holder.
business_info
object
Description: The account holder's business information.
capabilities
array (contains the capability object)
Read only.
Description: The capabilities of the account, and the additional fields and documents required to enable them.
cc_soft_descriptor
string
Minimum length: 2.
Maximum length: 11.
Description: The name 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.
citizenship
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character IS0-3166-1 country code of the account holder's citizenship.
Pattern: ^([A-Z]{2}|C2)$.
country_code
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character ISO 3166-1 code that identifies the country or region.
Pattern: ^([A-Z]{2}|C2)$.
date_of_birth
string
Minimum length: 10.
Maximum length: 10.
Description: The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.
email_id
string
Minimum length: 3.
Maximum length: 254.
Description: The ID of the managed account, as an email.
Pattern: ^.+@[^"\-].+$.
external_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner-provided ID of the managed account.
financial_instruments
object
Description: An array of financial instruments for the account.
identifications
array (contains the personal_identification object)
Description: An array of identification document numbers that verify the identity the account holder.
links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.
name
object
Description: The name of the party.
organization
string
Minimum length: 1.
Maximum length: 127.
Description: The organization to which this managed account belongs in the partner’s hierarchy, as a path.
payer_id
string
Read only.
Minimum length: 1.
Maximum length: 127.
Description: The ID of the managed account.
phones
array (contains the personal_phone object)
Description: An array of phone numbers for the account holder.
primary_currency_code
string
Minimum length: 3.
Maximum length: 3.
Description: The primary currency that this account can hold. If you omit this value from the request, the primary currency code is derived from the primary currency of the country for the account.
regulatory_obligations
array (contains the policy object)
Read only.
Description: The status of compliance and tax obligations for the account.
secondary_currency_codes
array (contains the currency_code object)
Description: Any additional currencies that this account can hold.
tax_id
object
Description: The tax ID of the account holder.
terms_and_conditions_acceptance
object
Description: The seller's consent to PayPal's terms and conditions.
user_id
string
Maximum length: 127.
Description: The partner's unique ID for this user in their system.

Sample Response

{
  "payer_id": "7G4EPEEPEF74L",
  "external_id": "sample-user@example.com",
  "country_code": "US",
  "email_id": "unique@example.com",
  "name": {
    "prefix": "Mr.",
    "given_name": "John",
    "surname": "Collins",
    "middle_name": "Davis",
    "suffix": "Jr"
  },
  "addresses": [
    {
      "type": "HOME",
      "address_line_1": "150 E San Fernando St",
      "address_line_2": "apt #1",
      "admin_area_1": "CA",
      "admin_area_2": "San Jose",
      "postal_code": "95112",
      "country_code": "US"
    }
  ],
  "phones": [
    {
      "type": "MOBILE",
      "country_code": "1",
      "national_number": "4089679174"
    }
  ],
  "identifications": [
    {
      "type": "DRIVERS_LICENSE",
      "identifier": "****",
      "issuer": {
        "country_code": "US",
        "jurisdiction": "CA",
        "authority": "DMV CA"
      }
    }
  ],
  "tax_id": {
    "type": "SOCIAL_SECURITY_NUMBER",
    "identifier": "****",
    "issuer": {
      "country_code": "US",
      "authority": "IRS"
    }
  },
  "citizenship": "US",
  "date_of_birth": "1990-01-01",
  "business_info": {
    "type": "INDIVIDUAL",
    "names": [
      {
        "type": "LEGAL",
        "business_name": "Demo 201 Inc."
      }
    ],
    "addresses": [
      {
        "type": "WORK",
        "address_line_1": "585 Franklin Str",
        "address_line_2": "apt #1",
        "admin_area_1": "CA",
        "admin_area_2": "Mountain View",
        "postal_code": "94041",
        "country_code": "US"
      }
    ],
    "email_address": "customer-service@example.com",
    "phones": [
      {
        "type": "CUSTOMER_SERVICE",
        "country_code": "1",
        "national_number": "4089673333"
      }
    ],
    "identifications": [
      {
        "type": "EMPLOYER_IDENTIFICATION_NUMBER",
        "identifier": "****",
        "issuer": {
          "country_code": "US",
          "authority": "IRS"
        }
      }
    ],
    "date_of_incorporation": "2001-01-17",
    "business_category": {
      "merchant_category_code": "3011"
    },
    "website": "https://example.com",
    "stakeholders": [
      {
        "id": "ext_stakeholer_01",
        "ownership_percentage": "100.0",
        "type": "BENEFICIAL_OWNER",
        "name": {
          "prefix": "Mr.",
          "given_name": "John",
          "surname": "Collins",
          "middle_name": "Davis",
          "suffix": "Jr"
        },
        "citizenship": "US",
        "date_of_birth": "1990-01-01",
        "addresses": [
          {
            "address_line_1": "150 E San Fernando St",
            "address_line_2": "apt #1",
            "admin_area_1": "CA",
            "admin_area_2": "San Jose",
            "postal_code": "95112",
            "country_code": "US"
          }
        ],
        "phones": [
          {
            "country_code": "1",
            "national_number": "4089679174"
          }
        ],
        "identifications": [
          {
            "type": "DRIVERS_LICENSE",
            "identifier": "****",
            "issuer": {
              "country_code": "US",
              "jurisdiction": "CA",
              "authority": "DMV CA"
            }
          }
        ],
        "tax_id": {
          "type": "SOCIAL_SECURITY_NUMBER",
          "identifier": "****",
          "issuer": {
            "country_code": "US",
            "authority": "IRS"
          }
        }
      }
    ]
  },
  "primary_currency_code": "USD",
  "secondary_currency_codes": [
    "CAD"
  ],
  "financial_instruments": {
    "banks": [
      {
        "mandate": {
          "reference_number": "12345678912345"
        },
        "id": "BA-KTJ7Z4FBMELZA",
        "last_4_digits": "0937",
        "account_number": "87460937",
        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
        "account_type": "CHECKING",
        "routing_number": "081500875",
        "bank_name": "Wells Fargo Bank",
        "bic": "WFBIUS6WFFX",
        "account_holder_details": {
          "name": "John Davis Collins",
          "type": "BUSINESS"
        }
      }
    ]
  },
  "cc_soft_descriptor": "sample-user",
  "terms_and_conditions_acceptance": {
    "acceptance_time": "2018-05-12T01:23:45.678Z",
    "accepted": true
  },
  "organization": "us/shops",
  "user_id": "sample-user",
  "capabilities": [
    {
      "name": "WITHDRAW_MONEY",
      "status": "SUSPENDED",
      "limits": [
        {
          "type": "AMOUNT",
          "value": "5000.00 USD",
          "remaining_value": "1000.00 USD"
        }
      ],
      "required_fields": [
        {
          "requirement": "ALL_OF",
          "fields": [
            {
              "path": "/identifications",
              "link": {
                "rel": "edit",
                "href": "https://api-m.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                "method": "PATCH"
              }
            },
            {
              "path": "/business_info/identifications",
              "link": {
                "rel": "edit",
                "href": "https://api-m.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
                "method": "PATCH"
              }
            }
          ]
        }
      ],
      "required_documents": [
        {
          "requirement": "ONE_OF",
          "documents": [
            {
              "name": "DRIVERS_LICENSE",
              "entity": "ACCOUNT_HOLDER",
              "link": {
                "rel": "upload",
                "href": "https://api-m.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                "method": "POST"
              }
            },
            {
              "name": "PASSPORT",
              "entity": "STAKEHOLDER",
              "entity_identifier": "ext_stakeholer_01",
              "link": {
                "rel": "upload",
                "href": "https://api-m.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                "method": "POST"
              }
            }
          ]
        },
        {
          "requirement": "ALL_OF",
          "documents": [
            {
              "name": "UTILITY_BILL",
              "entity": "BUSINESS",
              "link": {
                "rel": "upload",
                "href": "https://api-m.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                "method": "POST"
              }
            },
            {
              "name": "PROOF_OF_SHIPPING",
              "entity": "ACCOUNT",
              "additional_information": {
                "type": "TRANSACTION",
                "identifier": "2GG279541U471931P"
              },
              "link": {
                "rel": "upload",
                "href": "https://api-m.paypal.com/v1/customer/supporting-documents/7G4EPEEPEF74LFG/upload",
                "method": "POST"
              }
            }
          ]
        }
      ]
    }
  ],
  "regulatory_obligations": [
    {
      "name": "MARKETPLACES_KYC",
      "status": "NEED_MORE_DATA"
    }
  ],
  "links": [
    {
      "rel": "edit",
      "href": "https://api-m.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L",
      "method": "PATCH"
    }
  ]
}

Managed accounts queues (resource group)

Show asynchronous request status

GET/v2/customer/managed-accounts-queues/{id}

Shows the status of an asynchronous request. If you query this endpoint after the asynchronous request is processed, the response returns either:

The HTTP 303 status with a HATEOAS link to complete a GET on the newly created account.
The response code of the error that caused the account creation to fail. For example, the HTTP 422 or 500 status code.

Path parameters

id
string
required
Description: The ID of the asynchronous request for which to show details.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/customer/managed-accounts-queues/AAG6SDXlnuO8VXqLnXXjqTgF6xRX2qSzIRrlUOEHQ2Snfgf6aTG/Yemdhd73NdgTfi72UvufdMpN6ykJWiJ0p6w= \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful show in-progress asynchronous request status returns the HTTP 200 OK status code and a JSON response body that shows the status of the asynchronous request.

links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.

Sample Response

{
  "links": [
    {
      "rel": "status",
      "href": "https://api-m.paypal.com/v2/customer/managed-accounts-queues/AAG6SDXlnuO8VXqLnXXjqTgF6xRX2qSzIRrlUOEHQ2Snfgf6aTG/Yemdhd73NdgTfi72UvufdMpN6ykJWiJ0p6w=",
      "method": "GET"
    }
  ]
}

Common object definitions

account

addresses
array (contains the personal_address object)
Description: An array of addresses for the account holder.
business_info
object
Description: The account holder's business information.
capabilities
array (contains the capability object)
Read only.
Description: The capabilities of the account, and the additional fields and documents required to enable them.
cc_soft_descriptor
string
Minimum length: 2.
Maximum length: 11.
Description: The name 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.
citizenship
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character IS0-3166-1 country code of the account holder's citizenship.
Pattern: ^([A-Z]{2}|C2)$.
country_code
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character ISO 3166-1 code that identifies the country or region.
Pattern: ^([A-Z]{2}|C2)$.
date_of_birth
string
Minimum length: 10.
Maximum length: 10.
Description: The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.
email_id
string
Minimum length: 3.
Maximum length: 254.
Description: The ID of the managed account, as an email.
Pattern: ^.+@[^"\-].+$.
external_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner-provided ID of the managed account.
financial_instruments
object
Description: An array of financial instruments for the account.
identifications
array (contains the personal_identification object)
Description: An array of identification document numbers that verify the identity the account holder.
links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.
name
object
Description: The name of the party.
organization
string
Minimum length: 1.
Maximum length: 127.
Description: The organization to which this managed account belongs in the partner’s hierarchy, as a path.
payer_id
string
Read only.
Minimum length: 1.
Maximum length: 127.
Description: The ID of the managed account.
phones
array (contains the personal_phone object)
Description: An array of phone numbers for the account holder.
primary_currency_code
string
Minimum length: 3.
Maximum length: 3.
Description: The primary currency that this account can hold. If you omit this value from the request, the primary currency code is derived from the primary currency of the country for the account.
regulatory_obligations
array (contains the policy object)
Read only.
Description: The status of compliance and tax obligations for the account.
secondary_currency_codes
array (contains the currency_code object)
Description: Any additional currencies that this account can hold.
tax_id
object
Description: The tax ID of the account holder.
terms_and_conditions_acceptance
object
Description: The seller's consent to PayPal's terms and conditions.
user_id
string
Maximum length: 127.
Description: The partner's unique ID for this user in their system.

account_holder_details

identifier
object
Description: The details of the account holder's ID.
name
string
Description: The name on the account holder's bank account.
type
enum
The possible values are:
- BUSINESS. A business bank account.
- INDIVIDUAL. An individual bank account
Description: The type of bank account, which is business or individual.

account_holder_identifier

type
enum
The possible values are:
- NATIONAL_ID. The ID type is a national ID.
- TAX_ID. The ID is a tax ID.
Description: The account holder's ID type.
value
string
Description: The account holder's ID value.

additional_information

identifier
string
Description: The ID for the document.
type
enum
The possible values are:
- TRANSACTION. Payment transaction.
- FINANCIAL_INSTRUMENT. Financial instrument.
- ADDRESS. Address.
Description: The document type.

address_details

building_name
string
Maximum length: 100.
Description: A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
delivery_service
string
Maximum length: 100.
Description: The delivery service. Post office box, bag number, or post office name.
street_name
string
Maximum length: 100.
Description: The street name. Just Drury in Drury Lane.
street_number
string
Maximum length: 100.
Description: The street number.
street_type
string
Maximum length: 100.
Description: The street type. For example, avenue, boulevard, road, or expressway.
sub_building
string
Maximum length: 100.
Description: The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.

address_portable

country_code
string
required
Description: The two-character ISO 3166-1 code that identifies the country or region.
address_details
object
Description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and opensource. Redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number and street_name and street_type.
address_line_1
string
Maximum length: 300.
Description: The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.
address_line_2
string
Maximum length: 300.
Description: The second line of the address. For example, suite or apartment number.
address_line_3
string
Maximum length: 100.
Description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_1
string
Maximum length: 300.
Description: The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
admin_area_2
string
Maximum length: 120.
Description: A city, town, or village. Smaller than admin_area_level_1.
admin_area_3
string
Maximum length: 100.
Description: A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
admin_area_4
string
Maximum length: 100.
Description: The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
postal_code
string
Maximum length: 60.
Description: 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

async_response

links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.

bank

account_holder_details
object
Description: The details for the account holder who owns the bank account.
account_number
string
Maximum length: 34.
Description: The account number in either:
account_number_type
string
Description: The type of bank account number.
account_type
string
Description: The type of bank account.
bank_name
string
Maximum length: 34.
Description: The name of the bank.
bic
string
Maximum length: 16.
Description: The bank identification code (BIC) for countries that support BIC.
branch_code
string
Maximum length: 16.
Description: The branch code of the bank account.
branch_location
string
Maximum length: 34.
Description: The branch location of the bank.
country_code
string
Description: The two-character ISO 3166-1 code that identifies the country or region.
currency_code
string
Description: The three-character ISO-4217 currency code that identifies the currency.
id
string
Description: The PayPal-generated ID for the bank account.
last_4_digits
string
Description: The last four digits of bank account number.
Pattern: [0-9]{4}.
routing_number
string
Maximum length: 34.
Description: 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.

mandate
object
Description: The mandate for this bank account.

bank_account

account_number
string
required
Maximum length: 34.
Description: The account number in either:
account_number_type
enum
required
The possible values are:
- BASIC_BANK_ACCOUNT_NUMBER. A Basic Bank Account Number (BBAN).
- INTERNATIONAL_BANK_ACCOUNT_NUMBER. An International Bank Account Number (IBAN).
- WIRE. A wire bank account number.
Description: The type of bank account number.
account_holder_details
object
Description: The details for the account holder who owns the bank account.
account_type
enum
The possible values are:
- SAVINGS. A savings account.
- CHECKING. A checking account.
Description: The type of bank account.
bank_name
string
Maximum length: 34.
Description: The name of the bank.
bic
string
Maximum length: 16.
Description: The bank identification code (BIC) for countries that support BIC.
branch_code
string
Maximum length: 16.
Description: The branch code of the bank account.
branch_location
string
Maximum length: 34.
Description: The branch location of the bank.
country_code
string
Description: The two-character ISO 3166-1 code that identifies the country or region.
currency_code
string
Description: The three-character ISO-4217 currency code that identifies the currency.
id
string
Read only.
Description: The PayPal-generated ID for the bank account.
last_4_digits
string
Read only.
Description: The last four digits of bank account number.
Pattern: [0-9]{4}.
routing_number
string
Maximum length: 34.
Description: 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.

business

names
array (contains the business_name_and_type object)
required
Description: An array of names for the business. For example, the legal name and the doing business as name. You must set at least one type to LEGAL.
addresses
array (contains the business_address object)
Description: An array of addresses for the business.
business_category
object
Description: The category code of the business. Requires either the merchant category code or the category code and sub-category code.
date_of_incorporation
string
Description: The date when the business was incorporated, in Internet date and time full-date format.
email_address
string
Description: The business or customer service email address, in RFC-5321 Simple Mail Transfer Protocol format or RFC-5322 Internet Message Format. Does not support Unicode email addresses.
identifications
array (contains the business_identification object)
Description: An array of identification numbers for the business.
phones
array (contains the business_phone object)
Description: An array of phone numbers for the business.
stakeholders
array (contains the stakeholder object)
Description: An array of business stakeholder information.
type
enum
The possible values are:
- INDIVIDUAL. An individual business.
- PROPRIETORSHIP. A sole proprietorship.
- PARTNERSHIP. A partnership.
- CORPORATION. A corporation.
- NONPROFIT. A nonprofit.
- GOVERNMENT. A government agency.
- PUBLIC_COMPANY. A public company.
- PROPRIETARY_COMPANY. BA proprietary company.
- ASSOCIATION. An association.
- PRIVATE_CORPORATION. A private corporation.
- OTHER_CORPORATE_BODY. Other corporate body.
Description: The type of business, such as corporation or sole proprietorship.
website
string
Maximum length: 255.
Description: The URL of the website for the business.

business_address

address_details
object
Description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and opensource. Redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number and street_name and street_type.
address_line_1
string
Maximum length: 300.
Description: The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.
address_line_2
string
Maximum length: 300.
Description: The second line of the address. For example, suite or apartment number.
address_line_3
string
Maximum length: 100.
Description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_1
string
Maximum length: 300.
Description: The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
admin_area_2
string
Maximum length: 120.
Description: A city, town, or village. Smaller than admin_area_level_1.
admin_area_3
string
Maximum length: 100.
Description: A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
admin_area_4
string
Maximum length: 100.
Description: The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
country_code
string
Description: The two-character ISO 3166-1 code that identifies the country or region.
postal_code
string
Maximum length: 60.
Description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

type
string
Description: The type of address.

business_identification

identifier
string
required
Minimum length: 1.
Maximum length: 127.
Description: The number or value of the identifier.
issuer
object
required
Description: The details of the authority that issued the identification number.
type
enum
required
The possible values are:
- EMPLOYER_IDENTIFICATION_NUMBER. Employer identification number (EIN).
- BUSINESS_REGISTRATION_NUMBER. Business Registration Number.
Description: The type of identification number.

business_name

business_name
string
Maximum length: 300.
Description: Required. The business name of the party.

business_name_and_type

business_name
string
Maximum length: 300.
Description: Required. The business name of the party.

type
string
Description: Required. The type of business name.

business_name_validation

business_name_validation

business_phone

country_code
string
Minimum length: 1.
Maximum length: 3.
Description: 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).
Pattern: ^[0-9]{1,3}?$.
extension_number
string
Minimum length: 1.
Maximum length: 15.
Description: The extension number.
Pattern: ^[0-9]{1,15}?$.
national_number
string
Minimum length: 1.
Maximum length: 14.
Description: 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).
Pattern: ^[0-9]{1,14}?$.

type
string
Description: The type of phone.

capability

limits
array (contains the limit object)
Description: An array of limits on the capability.
name
string
Description: The capability name.
required_documents
array (contains the document_requirement object)
Description: An array of documents that must be collected and verified to lift one or more limits on the capability.
required_fields
array (contains the field_requirement object)
Description: An array of fields that must be collected and verified to lift one or more limits on the capability.
status
enum
The possible values are:
- ACTIVE. This capability is enabled.
- INACTIVE. This capability is disabled and no further action can be taken.
- SUSPENDED. This capability is disabled until required fields and documents are collected and verified.
Description: The capability status.

card

expiry
string
required
Minimum length: 7.
Maximum length: 7.
Description: The card expiration year and month, in Internet date format.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.
number
string
required
Minimum length: 13.
Maximum length: 19.
Description: The primary account number (PAN) for the payment card.
billing_address
object
Description: The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
card_type
enum
The possible values are:
- VISA. Visa card.
- MASTERCARD. MasterCard card.
- DISCOVER. Discover card.
- AMEX. American Express card.
- SOLO. Solo debit card.
- JCB. Japan Credit Bureau card.
- STAR. Military Star card.
- DELTA. Delta Airlines card.
- SWITCH. Switch credit card.
- MAESTRO. Maestro credit card.
- CB_NATIONALE. Carte Bancaire (CB) credit card.
- CONFIGOGA. Configoga credit card.
- CONFIDIS. Confidis credit card.
- ELECTRON. Visa Electron credit card.
- CETELEM. Cetelem credit card.
- CHINA_UNION_PAY. China union pay credit card.
Read only.
Minimum length: 1.
Maximum length: 255.
Description: The card brand or network. Typically used in the response.
Pattern: ^[A-Z_]+$.
id
string
Read only.
Description: The PayPal-generated ID for the card.
last_digits
string
Read only.
Description: The last digits of the payment card.
Pattern: [0-9]{2,}.
name
string
Maximum length: 300.
Description: The card holder's name as it appears on the card.
security_code
string
Description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.
Pattern: [0-9]{3,4}.

card_type

card_type
enum
The possible values are:
- VISA. Visa card.
- MASTERCARD. MasterCard card.
- DISCOVER. Discover card.
- AMEX. American Express card.
- SOLO. Solo debit card.
- JCB. Japan Credit Bureau card.
- STAR. Military Star card.
- DELTA. Delta Airlines card.
- SWITCH. Switch credit card.
- MAESTRO. Maestro credit card.
- CB_NATIONALE. Carte Bancaire (CB) credit card.
- CONFIGOGA. Configoga credit card.
- CONFIDIS. Confidis credit card.
- ELECTRON. Visa Electron credit card.
- CETELEM. Cetelem credit card.
- CHINA_UNION_PAY. China union pay credit card.
Minimum length: 1.
Maximum length: 255.
Description: The card network or brand. Applies to credit, debit, gift, and payment cards.
Pattern: ^[A-Z_]+$.

card_with_mandate

billing_address
object
Description: The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.
card_type
string
Minimum length: 1.
Maximum length: 255.
Description: The card brand or network. Typically used in the response.
Pattern: ^[A-Z_]+$.
expiry
string
Minimum length: 7.
Maximum length: 7.
Description: The card expiration year and month, in Internet date format.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.
id
string
Description: The PayPal-generated ID for the card.
last_digits
string
Description: The last digits of the payment card.
Pattern: [0-9]{2,}.
name
string
Maximum length: 300.
Description: The card holder's name as it appears on the card.
number
string
Minimum length: 13.
Maximum length: 19.
Description: The primary account number (PAN) for the payment card.
security_code
string
Description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.
Pattern: [0-9]{3,4}.

mandate
object
Description: The mandate for this card.

country_code

country_code
string
Minimum length: 2.
Maximum length: 2.
Description: The two-character ISO 3166-1 code that identifies the country or region.
Pattern: ^([A-Z]{2}|C2)$.

create_account_request

country_code
string
required
Description: The two-character ISO 3166-1 code that identifies the country or region.
email_id
string
required
Description: The ID of the managed account, as an email.
name
object
required
Description: The name of the account holder.
addresses
array (contains the personal_address object)
Description: An array of account holder addresses.
business_info
object
Description: The account's business information.
cc_soft_descriptor
string
Minimum length: 2.
Maximum length: 11.
Description: The name that appears on the buyer’s bank or credit card statement. Supports only capital letters, numbers, spaces, and the ., -, and * special characters. With special characters, you must include one alphanumeric character.
citizenship
string
Description: The two-character IS0-3166-1 country code of the account holder's citizenship.
date_of_birth
string
Description: The account holder's date of birth, in Internet date and time full-date format. Supports YYYY-MM-DD.
external_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner-provided ID of the managed account.
financial_instruments
object
Description: Array of financial instruments attached to the account.
identifications
array (contains the personal_identification object)
Description: An array of document numbers that verify a person's identity.
organization
string
Maximum length: 127.
Description: Organization this managed account belongs to in the partner’s hierarchy in the form of a path.
phones
array (contains the personal_phone object)
Description: An array of account holder phone numbers.
primary_currency_code
string
Description: The primary currency that this account holds. If you omit this value from the request, value is derived from the primary currency of the account's country.
secondary_currency_codes
array (contains the currency_code object)
Description: An array of additional currencies that this account can hold.
tax_id
object
Description: The account holder's tax ID.
terms_and_conditions_acceptance
object
Description: Indication that the account holder has accepted PayPal's terms and conditions.
user_id
string
Minimum length: 1.
Maximum length: 127.
Description: The partner's unique identifier for this user in their system.

currency_code

currency_code
string
Minimum length: 3.
Maximum length: 3.
Description: The three-character ISO-4217 currency code that identifies the currency.

date_no_time

date_no_time
string
Minimum length: 10.
Maximum length: 10.
Description: 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.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

date_time

date_time
string
Minimum length: 20.
Maximum length: 64.
Description: The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

date_year_month

date_year_month
string
Minimum length: 7.
Maximum length: 7.
Description: The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

document

additional_information
object
Description: Any additional information about the document. For example, identifies the bank account for which a bank statement must be uploaded.
entity
enum
The possible values are:
- BUSINESS. Business.
- ACCOUNT_HOLDER. Account holder.
- ACCOUNT. Account.
- STAKEHOLDER. Business stakeholder.
Description: The type of entity for which the document is required.
entity_identifier
string
Description: The ID that uniquely identifies the entity for which the document is required. Present only when entity is STAKEHOLDER.
link
object
Description: The request-related HATEOAS link information.
name
string
Description: The document name.

document_requirement

documents
array (contains the document object)
Description: An array of documents that must be collected and verified to lift one or more limits on a capability.
requirement
enum
The possible values are:
- ONE_OF. One of the documents is required.
- ALL_OF. All documents are required.
Description: Indicates whether one or all documents are required.

email_address

email_address
string
Minimum length: 3.
Maximum length: 254.
Description: The internationalized email address.
Pattern: ^.+@[^"\-].+$.

error

debug_id
string
required
Description: The PayPal internal ID that is used for correlation purposes.
message
string
required
Description: The message that describes the error.
name
string
required
Description: The human-readable, unique name of the error.
details
array (contains the error_details object)
Description: An array of additional details about the error.
information_link
string
Read only.
Description: The information link, or URI, that shows detailed information about this error for the developer.
links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.

error

debug_id
string
required
Description: The PayPal internal ID that is used for correlation purposes.
message
string
required
Description: The message that describes the error.
name
string
required
Description: The human-readable, unique name of the error.
details
array (contains the error_details object)
Description: An array of additional details about the error.
information_link
string
Read only.
Description: The information link, or URI, that shows detailed information about this error for the developer.
links
array (contains the link_description object)
Read only.
Description: An array of request-related HATEOAS links.

error_details

issue
string
required
Description: The unique and fine-grained application-level error code.
description
string
Description: 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.
field
string
Description: 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.
location
string
Description: The location of the field that caused the error. Value is body, path, or query.
value
string
Description: The value of the field that caused the error.

error_details

issue
string
required
Description: The unique and fine-grained application-level error code.
description
string
Description: 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.
field
string
Description: 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.
location
string
Description: The location of the field that caused the error. Value is body, path, or query.
value
string
Description: The value of the field that caused the error.

field

link
object
Description: The request-related HATEOAS link information.
path
string
Description: The JSON pointer to the field in the account payload.

field_requirement

fields
array (contains the field object)
Description: An array of fields.
requirement
enum
The possible values are:
- ONE_OF. One of the fields is required.
- ALL_OF. All fields are required.
Description: Indicates whether one or all listed fields are required.

financial_instrument

banks
array (contains the bank object)
Description: An array of banks for this managed account.
cards
array (contains the card_with_mandate object)
Description: An array of cards for this managed account.

get_managed_accounts_response

managed_accounts
array (contains the account object)
Description: The managed accounts search results.

issuer

country_code
string
required
Description: The two-character IS0-3166-1 country code of the country that issued the identity document.
authority
string
Maximum length: 256.
Description: The entity that issued the identity document. For example, registration authority.
jurisdiction
string
Maximum length: 300.
Description: The state, province, or city that issued the identity document.

limit

remaining_value
string
Description: How close the account is to breaching this limit.
type
enum
The possible values are:
- AMOUNT. The dollar, or currency equivalent, amount.
- DAYS. The number of days.
- TRANSACTIONS. The number of transactions.
Description: The type of limit.
value
string
Description: The value of the limit.

link_description

href
string
required
Description: The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
Description: The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.
Description: The HTTP method required to make the related call.

link_description

href
string
required
Description: The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
Description: The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.
Description: The HTTP method required to make the related call.

mandate

reference_number
string
Read only.
Minimum length: 13.
Maximum length: 16.
Description: Mandate reference number.

name

Hide deprecated

alternate_full_name
string
Maximum length: 300.
Description: 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.
full_name
string
Maximum length: 300.
Description: When the party is a person, the party's full name.
given_name
string
Maximum length: 140.
Description: When the party is a person, the party's given, or first, name.
middle_name
string
Maximum length: 140.
Description: 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.
prefix
string
Maximum length: 140.
Description: The prefix, or title, to the party's name.
suffix
string
Maximum length: 140.
Description: The suffix for the party's name.
surname
string
Maximum length: 140.
Description: 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.

name_validation

name_validation

patch

op
enum
required
Possible values: add,remove,replace,move,copy,test.
Description: The operation to complete.
from
string
Description: The JSON pointer to the target document location from which to move the value. Required for the move operation.
path
string
Description: The JSON pointer to the target document location at which to complete the operation.
value
number,integer,string,boolean,null,array,object
Description: The value to apply. The remove operation does not require a value.

patch_request

patch_request
array (contains the patch object)
Description: An array of JSON patch objects to apply partial updates to resources.

percentage

percentage
string
Description: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

personal_address

address_details
object
Description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and opensource. Redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number and street_name and street_type.
address_line_1
string
Maximum length: 300.
Description: The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.
address_line_2
string
Maximum length: 300.
Description: The second line of the address. For example, suite or apartment number.
address_line_3
string
Maximum length: 100.
Description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
admin_area_1
string
Maximum length: 300.
Description: The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:
admin_area_2
string
Maximum length: 120.
Description: A city, town, or village. Smaller than admin_area_level_1.
admin_area_3
string
Maximum length: 100.
Description: A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
admin_area_4
string
Maximum length: 100.
Description: The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
country_code
string
Description: The two-character ISO 3166-1 code that identifies the country or region.
postal_code
string
Maximum length: 60.
Description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

type
string
Description: The type of address.

personal_identification

identifier
string
required
Minimum length: 1.
Maximum length: 127.
Description: The document number or the identifier in the document.
issuer
object
required
Description: The details for the authority that issued the identity document.
type
enum
required
The possible values are:
- DRIVERS_LICENSE. Driver's license.
- PASSPORT_NUMBER. Passport number.
Description: The type of identity document number.

personal_phone

country_code
string
Minimum length: 1.
Maximum length: 3.
Description: 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).
Pattern: ^[0-9]{1,3}?$.
extension_number
string
Minimum length: 1.
Maximum length: 15.
Description: The extension number.
Pattern: ^[0-9]{1,15}?$.
national_number
string
Minimum length: 1.
Maximum length: 14.
Description: 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).
Pattern: ^[0-9]{1,14}?$.

type
string
Description: The type of phone number.

phone

country_code
string
required
Minimum length: 1.
Maximum length: 3.
Description: 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).
Pattern: ^[0-9]{1,3}?$.
national_number
string
required
Minimum length: 1.
Maximum length: 14.
Description: 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).
Pattern: ^[0-9]{1,14}?$.
extension_number
string
Minimum length: 1.
Maximum length: 15.
Description: The extension number.
Pattern: ^[0-9]{1,15}?$.

policy

name
enum
The possible values are:
- MARKETPLACES_KYC. Marketplaces KYC policy.
- MARKETPLACES_TAX. Marketplaces tax policy.
Description: The name of the policy.
status
enum
The possible values are:
- COMPLETED. Completed.
- FAILED. Failed.
- MANUAL_REVIEW. Manual review.
- NEED_MORE_DATA. Need more data.
- NOT_APPLICABLE. Not applicable.
Description: The status of the policy.

stakeholder

id
string
required
Minimum length: 1.
Maximum length: 127.
Description: The partner's unique ID for this stakeholder in their system.
type
enum
required
The possible values are:
- CHAIRMAN. Chairman of the business.
- PARTNER. Partner in the business.
- SECRETARY. Secretary.
- TREASURER. Treasurer of the business.
- BENEFICIAL_OWNER. Beneficial owner of the business.
- DIRECTOR. Director of the business.
Description: The type of stakeholder in the business.
addresses
array (contains the address_portable object)
Description: An array of addresses of the stakeholder.
citizenship
string
Description: The two-character IS0-3166-1 country code of the country of citizenship.
date_of_birth
string
Description: The date of birth, in Internet date and time full-date format. Supports the YYYY-MM-DD format.
identifications
array (contains the personal_identification object)
Description: An array of identification document numbers of the stakeholder.
name
object
Description: The name of the stakeholder.
ownership_percentage
string
Description: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.
phones
array (contains the phone object)
Description: An array of phones of the stakeholder.
tax_id
object
Description: The tax ID of stakeholder.

tax_id

identifier
string
required
Maximum length: 300.
Description: The tax ID or document number.
issuer
object
required
Description: The details about the tax document-issuing authority.
type
enum
required
The possible values are:
- INDIVIDUAL_TAX_IDENTIFICATION_NUMBER. Individual tax ID number.
- SOCIAL_SECURITY_NUMBER. Social security number.
Description: The type of tax ID for the account holder.

terms

acceptance_time
string
required
Minimum length: 20.
Maximum length: 64.
Description: The date and time when the acceptance was captured, in Internet date and time format.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
accepted
boolean
required
Description: Indicates whether the seller accepted the terms and conditions.

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_SERVER_ERROR
INVALID_REQUEST
NOT_AUTHORIZED
RESOURCE_NOT_FOUND
UNPROCCESSABLE_ENTITY