Update merchant information

CurrentDocs

Last updated: Oct 23rd, 3:36am

As you manage your merchant account, you may need to update the merchant information to:

Rectify or add information during initial onboarding and verification.

Update critical business information when it changes, such as addresses and owners.

According to your agreement with PayPal, inform PayPal whenever you update your merchant's information. In some cases, you need to verify the merchant's account again after updates.

In such cases, PayPal verifies the new information electronically. If PayPal cannot verify the merchant account, you have a 30-day grace period to provide additional information or documentation.

Note: During the grace period, the merchant account's capabilities remain the same. For example, if payment capabilities such as receive and withdraw are active, they remain active until this period ends. At the end of the grace period, all capabilities, including transaction and withdrawal, are disabled. Resolve all requirements before this deadline.

Use PATCH to update merchant information

Use the PATCH method to edit or update the merchant account.

Use this method for a single or multiple field update, as shown in the following examples.

Single field update

Request
Request body

1curl --location --request PATCH 'https://<Host>/v3/customer/managed-accounts/<Account-ID>’

Multiple field update

Request
Request body

1curl --location --request PATCH 'https://<Host>/v3/customer/managed-accounts/<Account-ID>’

Sample request and response

In the following example, the request returns a 422 Unprocessable Entity status code.

Request
Response

1[
2  {
3    "op": "replace",
4    "path": "/financial_instruments/ban",
5    "value": [
6      {
7        "country_code": "US",
8        "currency_code": "USD",
9        "routing_number": "081500875",
10        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
11        "account_number": "90932977",
12        "account_type": "checking",
13        "bank_name": "BANK OF AMERICA"
14      }
15    ]
16  }
17]

Multiple field updates with one failure

In the following example, the PATCH method updates multiple data points, but only one operation succeeds.

Request
Response

1[
2  {
3    "op": "replace",
4    "path": "/financial_instruments/banks",
5    "value": [
6      {
7        "mandate": {
8          "consent_to_debit": true
9        },
10        "account_number": "66910563",
11        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
12        "account_type": "CHECKING",
13        "routing_number": "082900429",
14        "branch_code": "08501",
15        "currency_code": "USD",
16        "country_code": "US",
17        "bank_name": "Key Bank National Association"
18      }
19    ]
20  },
21  {
22    "op": "add",
23    "path": "/individual_owners/@id=='{{account_id}}'",
24    "value": {
25      "date_of_birth": "1997-05-20"
26    }
27  },
28  {
29    "op": "add",
30    "path": "/individual_owners/@id=='{{account_id}}'",
31    "value": {
32      "email": "add_email5@provider.com"
33    }
34  }
35]

PATCH request error messages

The following table describes the different types of PATCH request error messages and their descriptions.

Error	Error Description
MISSING_REQUEST_BODY	Request body is missing
CLIENT_EXCEPTION	Error Calling downstream API
ACCOUNT_CANNOT_BE_FETCHED	Account_cannot_be_fetched
VALIDATION_ERROR	Data not valid for field
MISSING_FIELD	Missing field
MISSING_REQUIRED_PARAMETER	Missing required field or parameter
INVALID_FORMAT	Data not valid for field
INVALID_PARAMETER_VALUE	The value of a field is invalid.
MALFORMED_REQUEST_ERROR	Malformed request
INTERNAL_SERVER_EXCEPTION	INTERNAL_SERVER_ERROR
PAYMENT_REVIEW_STATUS_ERROR	Error processing Payment review status
INVALID_RESERVE_TYPE	Reserve type is invalid
INVALID_ROLLING_RESERVE_PERCENT	Rolling reserve percentage is invalid
INVALID_ROLLING_RESERVE_PERIOD	Rolling reserve period is invalid
MISSING_ROLLING_RESERVE_PERCENT	Rolling reserve percentage is missing
MISSING_ROLLING_RESERVE_PERIOD	Rolling reserve period is missing
RESERVE_CONFIGURATION_NOT_FOUND	Reserve configuration for this account doesn't exist
RESERVE_RELEASE_IN_PROGRESS	Reserve release is already in-progress
RESERVE_ERROR_EXCEPTION	Reserve operation occurs an internal service error
INVALID_FIXED_RESERVE_EXPIRATION_DATE	Expiration date exceeds 180 days
OUT_DATE_FIXED_RESERVE_EXPIRATION_DATE	Expiration date cannot be less than or equal the current date
MISSING_FIXED_RESERVE_AMOUNT	Amount is missing
ZERO_FIXED_RESERVE_AMOUNT	Amount specified is zero
INVALID_FIXED_RESERVE_AMOUNT	Invalid currency/value for target amount field.
INVALID_FIXED_RESERVE_CURRENCY	Fixed reserve can only be placed on primary currency of the account
UNKNOWN_RESERVE_CONFIG_ERROR	Error processing reserve configuration
RELEASE_PARALLEL_CALLS_ERROR	Previous release is in-progress pls try later
RELEASE_INSUFFICIENT_FUNDS_ERROR	The balance is insufficient
INSTRUMENT_ACCOUNT_NUMBER_MISSING	Account number is missing
INSTRUMENT_CURRENCY_CODE_MISSING	Currency code is missing
INSTRUMENT_COUNTRY_CODE_MISSING	Country code is missing
INSTRUMENT_ACCOUNT_NUMBER_TYPE_MISSING	Account number type is missing
ACCOUNT_CREATION_ERROR	Account Cannot be created
USER_ACCOUNT_CLOSED	Cannot add a bank to a PayPal account that is closed
NOT_SUPPORTED	Bank account country and PP account country combination not allowed
INSTRUMENT_UNAVAILABLE	Not a bank supported by PayPal
MULTIPLE_BANKS	Only one Bank allowed to add
CANNOT_ADD_BANK	Bank account has already been added
CANNOT_ADD_BANK_RISK_DENIAL	Unable to add bank
MULTIPLE_BANKS_NOT_PERMITTED	Only one financial instrument is permitted
MULTIPLE_PATCH_OPERATIONS_WITH_FI	Only add one Financial Instrument for this PATCH operation
CANNOT_REMOVE_BANK	Unable to remove bank. Please try again later.
CANNOT_REMOVE_BANK_HARD_DECLINE	Unable to remove bank. Please check bank account.
CANNOT_REMOVE_BANK_NEGATIVE_BALANCE	Unable to remove bank due to negative account balance.
BANK_OPERATION_NOT_ALLOWED	Bank operation is not currently allowed due to the account limitation.
RESOURCE_NOT_FOUND_EXCEPTION	RESOURCE_NOT_FOUND_ERROR
USER_BUSINESS_EXCEPTION	USER_BUSINESS_ERROR
PARTNER_BUSINESS_EXCEPTION	BUSINESS_ERROR
SECURITY_CONTEXT_EXCEPTION	SECURITY_CONTEXT_ERROR
SECURITY_TENANT_CONTEXT_EXCEPTION	SECURITY_TENANT_CONTEXT_EXCEPTION
SECURITY_CONTEXT_PARTNER_TENANT_NAME_EXCEPTION	SECURITY_CONTEXT_PARTNER_TENANT_NAME_EXCEPTION
SECURITY_CONTEXT_PARENT_ACCOUNT_NUMBER_EXCEPTION	SECURITY_CONTEXT_PARENT_ACCOUNT_NUMBER_EXCEPTION
SECURITY_CONTEXT_TENANT_ID_EXCEPTION	SECURITY_CONTEXT_TENANT_ID_EXCEPTION
SECURITY_CONTEXT_SIGNATURE_EXCEPTION	SECURITY_CONTEXT_SIGNATURE_EXCEPTION
AUTHORIZATION_EXCEPTION	AUTHORIZATION_ERROR
UNKNOWN_EXCEPTION	UNKNOWN_EXCEPTION
FORBIDDEN_NO_API_SCOPE	User doesn't have this API in their scope
FORBIDDEN_NO_ONBOARDING_SCOPE	Partner doesn't have the onboarding scopes
FORBIDDEN_NO_VALID_SCOPE	User doesn't have either this API in their scope or account permissions
FORBIDDEN_FLEXIBLE_PAYOUT_PARTNER	Partner is not enabled for flexible payout
FAILED_ACC_CREATION_TYPE	Fail to check account creation type
FORBIDDEN_NO_ACC_MGG_PERMISSION	Partner account does not have account management permission
FORBIDDEN_UNSUPPORTED_ACC_CREATION_TYPE	Partner account has unsupported account creation type
INTERNAL_ERROR_UNSUPPORTED_ACC_CREATION_TYPE	Fail to check account creation type
ADD_SECONDARY_CURRENCY_INTERNAL_ERROR	Internal Error during add currency call
SECONDARY_CURRENCY_INVALID_PAYER	Invalid Payer Id
SECONDARY_CURRENCY_INVALID_REQUEST	Invalid Payer Id
INVALID_SECONDARY_CURRENCY_CODE	Invalid secondary currency codes
SETTLEMENT_ONBOARDING_NOT_SUCCESSFUL	SETTLEMENT_ONBOARDING_NOT_SUCCESSFUL
EXISTING_EMAIL_HANDLE	Email address already taken
EXISTING_EXTERNAL_ID	External id already associated with another account
MISSING_EMAIL_HANDLE	Email id is required
MISSING_EMAIL_ADDRESS	Email address is required
INVALID_EMAIL_ADDRESS	Email address is not valid please provide valid email address
EXISTING_EMAIL_ADDRESS	Email address already exists
MISSING_COUNTRY_CODE	Country Code is required
MISSING_BUSINESS_DETAILS	Business details are required
DIFFERENT_EMAIL_DOMAIN	Email domain used in different from that of the partner
MISSING_EMAIL_DOMAIN	Partner's email domain is not found
MISSING_TENANT_ACC_NO	Account for this Account ID does not exist
MISSING_ORG_PATH	Missing organization path
INVALID_ORG_PATH	Invalid organization path
ACC_LOAD_FAILURE	Failuer to get account details
ACC_FETCH_FAILUER	Failed to fetch the lookup key for tenant account
INVALID_BANK	Invalid bank account information provided.
ALREADY_EXISTS_BANK	Value already exists
VALUE_NOTFOUND_BANK	Value can not be found
BANK_NOT_FOUND	The bank you are trying to remove is not linked with this account.
INVALID_ISSUER_DETAILS	Invalid branch location details
INVALID_STATUS	Invalid branch location details
MISSING_OR_INVALID_REQUEST_BODY	Invalid bank account details.
ISSUER_DECLINE	Branch location details declined.
ROUTING_NUMBER_NOT_SUPPORTED	Invalid routing number provided.
COUNTRY_NOT_SUPPORTED	Country code unsupported
INVALID_INDIVIDUAL_OWNER_SIZE	Number of individual owners supported is exactly 1.
INDIVIDUAL_OWNER_LENGTH	INDIVIDUAL_OWNER_LENGTH :
BUSINESS_WEBSITE_INFO_INVALID	Invalid Website Info
INDIVIDUAL_OWNER_EMAIL_MISSING	Emails of individual_owner is missing
MISSING_WEBSITE_INFO	missing_website_info
REDUNDANT_WEBSITE_URL	redundant_website_url
MISSING_WEBSITE_URL	missing_website_url
PATCH_WEBSITE	patch_website
DATA_NOT_FOUND	Data not found.
INSTRUMENT_ALREADY_EXISTS	Bank account already exists.
INSTRUMENT_COUNT_LIMIT_EXCEEDED	Maximum number of bank account exceeded.
INSTRUMENT_COUNT_LIMIT_EXCEEDED_VERIFIED	Maximum number of verified bank account exceeded.
INSTRUMENT_SHARING_LIMIT_EXCEEDED	Maximum shared use of bank account exceeded.
EXCEEDING_TOTAL_DUPLICATE_LIMIT	Maximum use of bank account exceeded.
ISSUER_DATA_NOT_FOUND	Branch location data not found.
PATCH_FI_INVALID_ID	Invalid FI ID
UPDATE_FI_INVALID_ID	Invalid FI ID
PATCH_FI_MISSING_VALUE	No Value provided
UPDATE_FI_MISSING_VALUE	No value provided
PATCH_FI_INVALID	Invalid Value
UPDATE_FI_INVALID	Invalid value
PATCH_INVALID_ID	Invalid ID
UPDATE_INVALID_ID	Invalid ID
PATCH_INVALID_REQUEST	Invalid Patch Request
BAD_JSON_FORMAT	Bad Json format
UPDATE_INVALID_REQUEST	Invalid update request
PATCH_FIELD_NOT_SUPPORTED	Patch for path and operation is not currently allowed.
PATCH_INVALID_OPERATION_REQUEST	Invalid Operation on Patch
PATCH_UNPROCESSABLE_OPERATION_REQUEST	Unprocessable request on Patch
OAS_SESSION_EXCEPTION	Session exception occurred
UNSUPPORTED_UPDATE	Unsupported update
UPDATE_FOR_FIELD_NOT_SUPPORTED	Update for field is not permitted
UNPROCESSIBLE_UPDATE	Update for field is not processible
MISSING_MERCHANT_ACCOUNT	Missing account number in security context
MISSING_ENCRYPTED_MERCHANT_ACCOUNT	Missing encrypted account number in security context
MISSING_PARTNER_ACCOUNT	Missing partner account number in security context
OAS_GETACCOUNT_EXCEPTION	Unable to get account details from OAS
OAS_EMPTY_PRODUCT_EXCEPTION	Empty products from OAS
OAS_SECONDARY_USER_NOT_RETURNED	Secondary user not returned in OAS call
OAS_GETBIZ_EXCEPTION	Business user retrieval exception occurred.
OAS_GETPERSON_EXCEPTION	Person user retrieval exception occurred.
MERCHANT_ACC_NOT_ACTIVE	Account is not active
GET_ACCOUNT_FLAGS	Error getting account flags
SET_ACCOUNT_FLAGS	Error setting account flags
MISSING_USER_ID	Missing User Id
GET_SECURITY_CONTEXT_FAILED	Unable to get Security context
INITIATE_SEPA_AUTHORIZATION_FAILED	Error on SEPA Account Authorization
INITIATE_ELECTRONIC_AUTHORIZATION_FAILED	Error on Electronic Mandate Account Authorization
MISSING_PAYPAL_REQUEST_ID	Paypal-Request-Id is required header.
DUPLICATE_PAYPAL_REQUEST_ID	Duplicate request received with different request payload.
MISSING_EXTERNAL_ID	Missing External ID
MISSING_PERSONAL_NAME	Missing Personal Name
MISSING_BUSINESS_ENTITY_NAME	Missing Business_entity Name
MISSING_AGREEMENTS	Missing Agreements
MISSING_BUSINESS_TYPE	Missing Business Type
INVALID_UPDATE_PATH	The path field for this update object is invalid.
INVALID_UPDATE_VALUE	The update value has an invalid field.
MISSING_FIELD_UPDATE_VALUE	The update value has a missing required parameter.
COUNTRY_CODE_DOC_TYPE_MISMATCH	The country code input provided does not match the associated document type.
INVALID_ARRAY_VALUE_UPDATE	The array provided in the value field is invalid.
INVALID_ARRAY_VALUE_PATCH	The array provided in the value field is invalid.
INVALID_UPDATE_MAX_ELEMENTS_REACHED	The update would cause the array to exceed its maximum allowed size.
INVALID_UPDATE_MIN_ELEMENTS_REACHED	The update would cause the array to fall below its minimum allowed size.
INVALID_BUSINESS_ATTRIBUTE_NAME_VALUE_PATCH	The name provided in Business Attribute is invalid.
ACCOUNT_ID_MISMATCH	Account ID in body does not match account ID in update path
INVALID_VIEWS_QUERY_PARAMETER	Query parameter has invalid value.
INVALID_TYPE_PROVIDED	Invalid type provided.
RETRIEVE_CONFIG_FAILED	Error on retrieving config value
INVALID_ENUMERATED_VALUE	Error on enumerated value.
AMQ_PUBLISH_FAILED	Publish Operation failed
BANK_ASSOCIATION_LIMIT_REACHED	This account has reached its association limit. Please use another bank account.
BANK_ACCOUNT_DECLINED	The bank account provided cannot be used. A different bank account must be used.
BANK_VALIDATION_ERROR	The bank account information provided is not valid. Please check all the details provided are accurate.
PPH_BUNDLE_ID_NOT_FOUND	Failed to fetch PPH bundleId
BANK_BAD_INSTRUMENT	The financial instrument has been flagged as risky and cannot be accepted.
BANK_MAXED_CONFIRMATION_TRIES	The verification of the bank failed previously. We recommend you to use another bank.
BANK_INSTRUMENT_RESTRICTED	The account number or routing number provided cannot be accepted.
BANK_REMOVE_DENIED_NEGATIVE_BALANCE	The currently associated bank has unsettled balance and cannot be removed at this time.
BANK_DOES_NOT_BELONG_TO_THE_MERCHANT	The FI bank account provided does not belong to merchant.
ACCOUNT_LINKING_CROSS_COUNTRY_USER_VALIDATION_ERROR	Account linking across countries is not supported.
USER_VALIDATION_ERROR	The account creation was not successful due to the limitation in the provided user information. Please review the provided documentation to pass the needed information to create the account.
CLOSE_ACCOUNT_FAILED	Close account failed
MISSING_HYPERWALLET_API_CREDENTIALS	Hyperwallet credentials setup missing.
INVALID_MAPPING_METADATA	Invalid mapping metadata detected.
DOMAIN_ALREADY_REGISTERED	The domain is already registered.
DOMAIN_NOT_REGISTERED	The domain is not registered.
DOMAIN_REGISTRATION_NOT_ALLOWED	Domain registration is not allowed for this account.
INVALID_DOMAIN_NAME	The domain name is invalid.
INVALID_PROVIDER_TYPE	The provider type is invalid.
DOMAIN_REGISTERED_WITH_ANOTHER_ENTITY	The domain is registered with another entity.
RHINO_PARSING_EXCEPTION_ERROR	Parsing Exception during JSON Logic processing.
AMQ_PUBLISH_ERROR	Fail to publish AMQ message.
AMQ_PUBLISH_EXCEPTION	Exception during AMQ message publishing.
INVALID_BENEFICAL_OWNER_DECLARATION	Invalid Beneficial Owner Declaration
TIMEOUT_EXCEPTION	Timeout Exception
INSTRUMENT_ALREADY_ASSOCIATED	Instrument is already associated with another user
INSTRUMENT_BLOCKED	Instrument is currently blocked
INVALID_ACCOUNT_TYPE	Not a valid business type account

Use PATCH to set verification status

After you update or edit the merchant account, complete a PATCH API call with SELF_CERTIFICATION. Set the SELF_CERTIFICATION value to true to indicate that the merchant account is ready for verification.

Note: Self-certify your merchant information to ensure the account verification succeeds and the account does not get stuck in an intermediary state.

Set SELF_CERTIFICATION

Set the SELF_CERTIFICATION value to true to indicate that the account is ready for re-evaluation as shown in the example.

Request
Request body

1curl --location --request PATCH 'https://<Host>/v3/customer/managed-accounts/<Account-ID>’

Update and set SELF_CERTIFICATION

You can also update the account with the required information and set SELF_CERTIFICATION to true using the same JSON request body as shown in the example.

Request
Request body

1curl --location --request PATCH 'https://<Host>/v3/customer/managed-accounts/<Account-ID>’

Monitor for webhooks

When the PATCH operation succeeds, PayPal sends the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED webhook to notify of a successful update to the merchant account.

If a merchant requires re-verification, PayPal sends the CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED webhook, indicating that the merchant must take action to complete verification.

We recommend you complete a GET call, v3/customer/managed-accounts/ACCOUNT-ID, to complete any additional onboarding requirements.

For more information about verification, see Verify merchants.

PATCH methods by region and business

To understand the scope of the PATCH calls across various regions and business types, see:

PATCH methods in the US

PATCH methods in the EU and the UK