marketplaces

Marketplaces Update Reference Accounts

For any number of reasons, you may need to update or completely replace information in or the configuration of a reference account.

Update an account

Using your access token, pass the seller's payer_id for the value of merchant_payer_id to /v1/customer/partners/merchant-accounts/{merchant_payer_id} to update reference account information or change configuration settings.

Parameter Type Description
op enum Required. The operation to complete. Possible values: add, remove, replace, move, copy, test
path string The JSON pointer to target document location at which to complete the operation. Possible pointers.
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 documentation location from which to move the value. Required for the move operation.

Note: For value, send an string or an object with an array containing the needed KVP to update. KVP may be of any type.

Examples

Update account permissions

Request

{
  "op": "add",
  "path": "/account_permissions",
  "value": [
    {
      "account_permissions": [{
        "permissions": [
          "SETTLEMENT_REPORTING"
          ]
        }]
    }]
}

Response

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

Update account limitations

Request

{
  "op": "add",
  "path": "/payment_receiving_preferences/block_unconfirmed_us_address_payments",
  "value": [
    {
      "block_unconfirmed_us_address_payments": true
    }
  }]
}

Response

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

Replace entire account

To replace the entirety of an account, pass the seller's merchant_id for the value of merchant_payer_id in:

POST /v1/customer/partners/merchant-accounts/{merchant_payer_id}
Parameter Type Description
owner_info object The account holder's information.
Important:Provide a unique email address as PayPal does not allow multiple accounts to share the same email address
business_info object The business information for the seller.
account_status enum The account status. Set to A for active. Other allowed values.
account_currency string The three-character ISO-4217 currency code for the account.
secondary_currency array, contains the currency_code object An array of the three-character ISO-4217 currency code for the secondary currencies.
financial_instruments array An array of financial instrument information.
payment_receiving_preferences object Available preferences.
account_relations array, contains the account_relations object An array of account relationships.
account_permissions array, contains the account_permissions object Available permissions.
timezone enum The time zone. Possible values
partner_merchant_external_id
loginable Boolean Indicates whether the account allows the seller to log in. Set to FALSE.
partner_tax_reporting Boolean Indicates whether you report taxes for the account.
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.
signup_options object The options, preferences, and agreements for the account.

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"
  ],
  "financial_info": {
    "bank_accounts": [
      {
        "transfer_type": "NORMAL",
        "account_number": "11111113",
        "account_type": "CHECKING",
        "currency_code": "AUD",
        "identifiers": [
          {
            "type": "ROUTING_NUMBER_1",
            "value": "645"
          },
          {
            "type": "ROUTING_NUMBER_2",
            "value": "000"
          }
        ],
        "bank_name": "Bank of Australia",
        "branch_location": {
          "city": "Sydney",
          "country_code": "AU"
        }
      }
    ]
  },
  "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": "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"
    }
  ]
}
Feedback

Have feedback?

Let us know.