Merchant Onboarding API

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

This API enables a marketplace to add PayPal merchant accounts. It supports the Connected path and Managed path marketplace models.

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

Call these methods for the Connected path:

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

Call these methods for the Managed path:

Partner Referrals (resource group)

Enables you to create and get information about shared customer data.

Create partner referral

POST /v1/customer/partner-referrals
Creates a partner referrals resource that was previously shared by the API caller. The resource contains the client's personal, business, and financial data.
A successful request returns the HTTP 201 Created status code and a JSON response body that contains a HATEOAS link that enables you to get the referral and an action_url that you use to redirect the customer in a browser to complete the signup process. The partner_referral_id token is appended to the URL.

Request

  • customer_data

    object

    The customer's data. Required for account creation.
  • requested_capabilities

    array (contains the customer_capabilities object)

    The capabilities to enable for the customer so that he or she can share data.
  • web_experience_preference

    object

    The preferences to customize the customer's web experience. Default is partner's preferences.
  • collected_consents

    array (contains the legal_consent object)

    The collected consents that the partner has received from this customer. If SHARE_DATA_CONSENT is not granted, the API does not store customer_data.
  • products

    array (contains the products_for_which_clients_can_be_onboarded object)

    An array of products to which to onboard the customer.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partner-referrals \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "customer_data": {
  "customer_type": "MERCHANT",
  "person_details": {
    "email_address": "swankhede@paypal.com",
    "name": {
    "prefix": "Mr.",
    "given_name": "Shashank",
    "surname": "Wankhede",
    "middle_name": "Govind"
    },
    "phone_contacts": [
    {
      "phone_number_details": {
      "country_code": "91",
      "national_number": "9740216087"
      },
      "phone_type": "HOME"
    }
    ],
    "home_address": {
    "line1": "11, outer ring road",
    "state": "Karnataka",
    "city": "Bangalore",
    "country_code": "IN",
    "postal_code": "560103"
    },
    "date_of_birth": {
    "event_type": "BIRTH",
    "event_date": "1987-12-29T23:59:59.999Z"
    },
    "nationality_country_code": "IN",
    "identity_documents": [
    {
      "type": "SOCIAL_SECURITY_NUMBER",
      "value": "ABCDEF34646",
      "partial_value": false,
      "issuer_country_code": "US"
    }
    ]
  },
  "business_details": {
    "phone_contacts": [
    {
      "phone_number_details": {
      "country_code": "91",
      "national_number": "9740216087"
      },
      "phone_type": "FAX"
    }
    ],
    "business_address": {
    "line1": "11, outer ring road",
    "state": "Karnataka",
    "city": "Bangalore",
    "country_code": "IN",
    "postal_code": "560103"
    },
    "business_type": "PROPRIETORSHIP",
    "category": "1004",
    "sub_category": "2025",
    "names": [
    {
      "type": "LEGAL",
      "name": "SHAWSHANKSPAYPALSTORE"
    }
    ],
    "business_description": "Arts and handicrafts",
    "event_dates": [
    {
      "event_type": "ESTABLISHED",
      "event_date": "2009-01-31T13:59:45Z"
    }
    ],
    "website_urls": [
    "mystore.paypal.com"
    ],
    "annual_sales_volume_range": {
    "minimum_amount": {
      "currency": "USD",
      "value": "2000"
    },
    "maximum_amount": {
      "currency": "USD",
      "value": "3000"
    }
    },
    "average_monthly_volume_range": {},
    "identity_documents": [
    {
      "type": "TAX_IDENTIFICATION_NUMBER",
      "value": "ABCDEF34646",
      "partial_value": false,
      "issuer_country_code": "US"
    }
    ],
    "email_contacts": [
    {
      "email_address": "customercare@shashank.com",
      "role": "CUSTOMER_SERVICE"
    }
    ]
  },
  "financial_instrument_data": {
    "bank_details": [
    {
      "nick_name": "Bank of America",
      "account_number": "123405668293",
      "account_type": "CHECKING",
      "currency_code": "USD",
      "identifiers": [
      {
        "type": "ROUTING_NUMBER_1",
        "value": "123456789"
      }
      ]
    }
    ]
  },
  "preferred_language_code": "en_US",
  "primary_currency_code": "USD",
  "referral_user_payer_id": {
    "type": "PAYER_ID",
    "value": "RFYUH2QQDGUQU"
  },
  "partner_specific_identifiers": [
    {
    "type": "TRACKING_ID",
    "value": "ABJSDFO343SD"
    }
  ]
  },
  "requested_capabilities": [
  {
    "capability": "BANK_ADDITION"
  }
  ],
  "web_experience_preference": {
  "partner_logo_url": "http://leiphone.qiniudn.com/uploads/2014/05/Paypal.jpg",
  "return_url": "http://example.com/return-from-prefill-flow",
  "action_renewal_url": "http://example.com/renew-prefill-url"
  },
  "collected_consents": [
  {
    "type": "SHARE_DATA_CONSENT",
    "granted": true
  }
  ],
  "products": [
  "EXPRESS_CHECKOUT"
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that contains:

  • A HATEOAS links to get the referral.
  • An action_url to which you redirect the customer in a browser to complete the signup process. The partner_referral_id token is appended to the URL.
  • referral_data-create_referral_data_response

    object

    The share referral data response.

Sample Response

{
  "links": [
    {
      "href": "https://uri.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "self",
      "method": "GET",
      "description": "Read referral data shared by the partner."
    },
    {
      "href": "https://www.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "action_url",
      "method": "GET",
      "description": "The target web redirect URL for the next action. Redirect the customer to this URL in the browser."
    }
  ]
}

Show partner referral data

GET /v1/customer/partner-referrals/partner_referral_id
Shows details for partner referral data, by ID, that is shared by the API caller.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the specified partner referral data.

Parameters

Pass the ID for the partner referral data. Find this ID in the self relation link in the POST /v1/customer/partner-referrals call.

  • partner_referral_id

    path string

    The ID of the partner referral data for which to show details.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0= \
-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 shared referral data, the ID to access the data, and the payer ID of the partner who shared the data.

  • partner_referral_id

    string

    The partner referral ID.

    Read only.

  • submitter_payer_id

    string

    The payer ID of the API caller who shared the referral data.

    Read only.

  • referral_data

    object

    The referral data that was shared with PayPal.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

{
  "partner_referral_id": "ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
  "submitter_payer_id": "RFYUH2QQDGUQU",
  "referral_data": {
    "customer_data": {
      "customer_type": "MERCHANT",
      "person_details": {
        "email_address": "swankhede@paypal.com",
        "name": {
          "prefix": "Mr.",
          "given_name": "Shashank",
          "surname": "Wankhede",
          "middle_name": "Govind"
        },
        "phone_contacts": [
          {
            "phone_number_details": {
              "country_code": "91",
              "national_number": "9740216087"
            },
            "phone_type": "HOME"
          }
        ],
        "home_address": {
          "line1": "11, outer ring road",
          "state": "Karnataka",
          "city": "Bangalore",
          "country_code": "IN",
          "postal_code": "560103"
        },
        "date_of_birth": {
          "event_type": "BIRTH",
          "event_date": "1987-12-29T23:59:59.999Z"
        },
        "nationality_country_code": "IN",
        "identity_documents": [
          {
            "type": "SOCIAL_SECURITY_NUMBER",
            "value": "ABCDEF34646",
            "partial_value": false,
            "issuer_country_code": "US"
          }
        ]
      },
      "business_details": {
        "phone_contacts": [
          {
            "phone_number_details": {
              "country_code": "91",
              "national_number": "9740216087"
            },
            "phone_type": "FAX"
          }
        ],
        "business_address": {
          "line1": "11, outer ring road",
          "state": "Karnataka",
          "city": "Bangalore",
          "country_code": "IN",
          "postal_code": "560103"
        },
        "business_type": "PROPRIETORSHIP",
        "category": "1004",
        "sub_category": "2025",
        "names": [
          {
            "type": "LEGAL",
            "name": "SHAWSHANKSPAYPALSTORE"
          }
        ],
        "business_description": "Arts and handicrafts.",
        "event_dates": [
          {
            "event_type": "ESTABLISHED",
            "event_date": "2009-01-31T13:59:45Z"
          }
        ],
        "website_urls": [
          "mystore.paypal.com"
        ],
        "annual_sales_volume_range": {
          "minimum_amount": {
            "currency": "USD",
            "value": "2000"
          },
          "maximum_amount": {
            "currency": "USD",
            "value": "3000"
          }
        },
        "average_monthly_volume_range": {},
        "identity_documents": [
          {
            "type": "TAX_IDENTIFICATION_NUMBER",
            "value": "ABCDEF34646",
            "partial_value": false,
            "issuer_country_code": "US"
          }
        ],
        "email_contacts": [
          {
            "email_address": "customercare@shashank.com",
            "role": "CUSTOMER_SERVICE"
          }
        ]
      },
      "financial_instrument_data": {},
      "preferred_language_code": "en_US",
      "primary_currency_code": "USD",
      "referral_user_payer_id": {
        "type": "PAYER_ID",
        "value": "RFYUH2QQDGUQU"
      },
      "partner_specific_identifiers": [
        {
          "type": "TRACKING_ID",
          "value": "ABJSDFO343SD"
        }
      ]
    },
    "requested_capabilities": [
      {
        "capability": "API_INTEGRATION",
        "api_integration_preference": {
          "partner_id": "RFYUH2QQDGUQU",
          "classic_api_integration_type": "FIRST_PARTY_INTEGRATED",
          "classic_first_party_details": "SIGNATURE"
        }
      },
      {
        "capability": "BANK_ADDITION"
      }
    ],
    "web_experience_preference": {
      "partner_logo_url": "http://leiphone.qiniudn.com/uploads/2014/05/Paypal.jpg",
      "return_url": "http://example.com/return-from-prefill-flow",
      "action_renewal_url": "http://example.com/renew-prefill-url"
    },
    "collected_consents": [
      {
        "type": "SHARE_DATA_CONSENT",
        "granted": true
      }
    ],
    "products": [
      "EXPRESS_CHECKOUT"
    ]
  },
  "links": [
    {
      "href": "https://uri.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "self",
      "method": "GET",
      "description": "Read client data shared by the partner."
    },
    {
      "href": "https://www.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "action_url",
      "method": "GET",
      "description": "The target web redirect URL for the next action. Redirect the customer to this URL in the browser."
    }
  ]
}

Merchant Integration (resource group)

Enables you to get information about a merchant-partner integration.

Show account tracking details

GET /v1/customer/partners/partner_id/merchant-integrations
Shows tracking information for the merchant integration that the partner onboarded. Specify the partner ID in the URI.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows tracking information.

Parameters

  • partner_id

    path string

    The ID of the partner who onboarded the merchant.
  • tracking_id

    query_string string

    Filters the merchant integrations in the response by a partner-provided merchant tracking ID.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations?tracking_id=merchantref1 \
-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 tracking details.

  • tracking_id

    string

    The partner-provided tracking ID.
  • merchant_id

    string

    The merchant ID.
  • products

    array (contains the product object)

    An array of statuses for all products that the merchant integrated with the partner.
  • payments_receivable

    boolean

    Indicates whether the merchant account can receive payments.
  • primary_email_confirmed

    boolean

    Indicates whether the primary email of the merchant is confirmed.
  • primary_email

    string

    The account's primary email.
  • date_created

    string

    The date and time when the account was created.
  • granted_permissions

    array

    The permissions that the merchant granted to the partner.
  • api_credentials

    object

    The merchant's API credentials.
  • oauth_integrations

    array (contains the oauth-integration object)

    The OAuth integration information between a partner and merchant.
  • limitations

    array (contains the limitation object)

    The merchant account's limitations.

Sample Response

{
  "merchant_id": "8LQLM2ML4ZTYU",
  "tracking_id": "merchantref1",
  "links": [
    {
      "href": "v1/customer/partners/6LKMD2ML4NJYU",
      "rel": "read",
      "method": "GET",
      "description": "Main partner resource."
    }
  ]
}

Show merchant status

GET /v1/customer/partners/partner_id/merchant-integrations/merchant_id
Shows the status for a merchant, by ID, who was onboarded by a partner, by ID.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows status details.

Parameters

  • partner_id

    path string

    The ID of the partner who onboarded the merchant.
  • merchant_id

    path string

    The ID of the merchant for which to show status.
  • fields

    query_string string

    Limits the fields that appear in the response to those in a comma-separated list of fields.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations/8LQLM2ML4ZTYU \
-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 status details.

  • tracking_id

    string

    The partner-provided tracking ID.
  • merchant_id

    string

    The merchant ID.
  • products

    array (contains the product object)

    An array of statuses for all products that the merchant integrated with the partner.
  • payments_receivable

    boolean

    Indicates whether the merchant account can receive payments.
  • primary_email_confirmed

    boolean

    Indicates whether the primary email of the merchant is confirmed.
  • primary_email

    string

    The account's primary email.
  • date_created

    string

    The date and time when the account was created.
  • granted_permissions

    array

    The permissions that the merchant granted to the partner.
  • api_credentials

    object

    The merchant's API credentials.
  • oauth_integrations

    array (contains the oauth-integration object)

    The OAuth integration information between a partner and merchant.
  • limitations

    array (contains the limitation object)

    The merchant account's limitations.

Sample Response

{
  "merchant_id": "8LQLM2ML4ZTYU",
  "products": [
    {
      "name": "EXPRESS_CHECKOUT"
    }
  ],
  "payments_receivable": true,
  "primary_email_confirmed": true,
  "oauth_integrations": [
    {
      "integration_type": "OAUTH_THIRD_PARTY",
      "integration_method": "BRAINTREE",
      "oauth_third_party": [
        {
          "partner_client_id": "AZqTbhAo7fUgX2BQW5l-yYEHYY_C8FDUkiPP_6Cw7P35cQID26rsWVWXzgRQ",
          "merchant_client_id": "ARj22pLzUWaTt_RFAlFvn_dC6OpETq1HK_n49nyuDf4i5dqPBZmDk6X1u9JytrtMGaDExCvKSGCOwRbO",
          "scopes": [
            "https://uri.paypal.com/services/payments/payment/authcapture",
            "https://uri.paypal.com/services/payments/realtimepayment"
          ],
          "access_token": "access_token$sandbox$s4dw8tjsz88cg7mh$45bdde2cfa55c1b060a409824b48b8d3",
          "refresh_token": "refresh_token$sandbox$s4dw8tjsz88cg7mh$b1dfdbbdbaa7b9165b696f916738ce2c"
        }
      ]
    }
  ]
}

Merchant Accounts (resource group)

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

Create merchant account

POST /v1/customer/partners/merchant-accounts
Creates a merchant account.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows merchant account details.

Request

  • owner_info

    object

    required

    The business owner information.
  • business_info

    object

    required

    The business information.
  • account_status

    string

    The account status.
  • account_currency

    string

    required

    Three-letter ISO 4217 alphabetical currency code.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies.

    Minimum length: 3.

    Maximum length: 3.

  • payment_receiving_preferences

    object

    The payment receiving preferences.
  • account_relations

    array (contains the account_relations object)

    Account relationships.
  • account_permissions

    array (contains the account_permissions object)

    The account permissions.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    The external merchant ID.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether you can log in to the account.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes.
  • signup_options

    object

    The options that are applied after sign up.
  • financial_info

    object

    The financial information.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "owner_info": {
  "email": "sydney@paypal.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": "qa195-AUispute@payapl.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": "http://www.AU.com",
    "revenue_from_online_sales": {
    "minimum_percent": 0,
    "maximum_percent": 25
    }
  },
  "customer_service": {
    "email": "qa195-uscs@paypal.com",
    "phone": {
    "country_code": "61",
    "national_number": "0491570156",
    "extension_number": "123"
    },
    "message": [
    {
      "type": "ONLINE",
      "headline": "headline1",
      "logo_image_url": "www.logoimageurl1.com",
      "service_image_url": "www.serviceimageurl1.com",
      "seller_message": "seller message"
    },
    {
      "type": "RETAIL",
      "headline": "headline2",
      "logo_image_url": "www.logoimageurl2.com",
      "service_image_url": "www.serviceimageurl2.com",
      "seller_message": "seller message"
    }
    ]
  },
  "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": "Snowy",
      "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": "www.original.com",
  "display_instructions_text_input": true,
  "cc_soft_descriptor": "USCCSOFTDES",
  "cc_soft_descriptor_extended": "USCCSOFTDESEXT"
  },
  "account_relations": [
  {
    "type": "PARTNER"
  }
  ],
  "account_permissions": [
  {
    "permissions": [
    "EXPRESS_CHECKOUT",
    "RECURRING_PAYMENT",
    "EXTENDED_PRO_PROCESSING",
    "EXCEPTION_PROCESSING",
    "MASS_PAY",
    "ENCRYPTED_WEBSITE_PAYMENTS"
    ]
  }
  ],
  "timezone": "Australia/Adelaide",
  "partner_merchant_external_id": "abc123",
  "loginable": false,
  "partner_tax_reporting": true
}'

Response

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

  • payer_id

    string

    The payer ID. This property is empty when an error occurs during account creation.

    Maximum length: 127.

  • partner_merchant_external_id

    string

    The external merchant ID.

    Maximum length: 127.

  • merchant_authorization_code

    string

    The merchant authorization code.
  • custom_data

    array (contains the keyvalue object)

    A custom key-and-value pair that is returned to the caller. For example, aa_token.
  • errors

    array

    An array of errors.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

Sample Response

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

Update merchant account

PATCH /v1/customer/partners/merchant-accounts/merchant_payer_id
Updates an account for a merchant, by ID.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

Parameters

Pass the payer ID of the merchant for which to update an account.

  • merchant_payer_id

    path string

    The ID of the merchant

Request

To apply partial updates, pass a JSON patch object in the JSON request body.

  • items

    array (contains the json_patch object)

    Request object used for a JSON patch.

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/customer/partners/merchant-accounts/F9E99K66P3G77 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
  "op": "add",
  "path": "/financial_info/bank_accounts",
  "value": [
    {
    "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"
    }
    }
  ]
  }
]'

Response

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

Sample Response

204 No Content

Replace merchant account

POST /v1/customer/partners/merchant-accounts/merchant_payer_id
Submits merchant information to re-populate an account for a merchant, by ID.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows merchant account details.

Parameters

  • merchant_payer_id

    path string

    The ID of the merchant for which to re-populate an account.

Request

  • owner_info

    object

    required

    The business owner information.
  • business_info

    object

    required

    The business information.
  • account_status

    string

    The account status.
  • account_currency

    string

    required

    Three-letter ISO 4217 alphabetical currency code.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies.

    Minimum length: 3.

    Maximum length: 3.

  • payment_receiving_preferences

    object

    The payment receiving preferences.
  • account_relations

    array (contains the account_relations object)

    Account relationships.
  • account_permissions

    array (contains the account_permissions object)

    The account permissions.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    The external merchant ID.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether you can log in to the account.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes.
  • signup_options

    object

    The options that are applied after sign up.
  • financial_info

    object

    The financial information.

Sample Request

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

Sample Response

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

Common object definitions

account_identifier

  • type

    enum

    The account ID type.

    Possible values: PAYER_ID.

  • value

    string

    The account ID value.

account_permissions

  • third_party

    string

    The payer ID of the third party to whom to grant permissions for the account. The API caller receives the permissions if you omit this parameter.
  • permissions

    array

    An array of permissions to assign to the account.

account_relations

  • subject_payer_id

    string

    The payer ID of the subject.
  • type

    enum

    The relationship type.

    Possible values: PARTNER, SAME_MERCHANT.

account_status

  • account_status

    enum

    The account status.

    Possible values: A, PV, PUA.

address

  • type

    enum

    The address type.

    Possible values: HOME, WORK, PRINCIPAL_BUSINESS, REGISTERED_OFFICE, MAILING_ADDRESS.

  • line1

    string

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

    string

    The second line of the address. For example, suite, apartment number, and so on. Maximum length is 100 characters.
  • line3

    string

    The optional third line of the address, if needed. Examples include street complement for Brazil, direction text such as next to Walmart, or a landmark in an Indian address.

    Maximum length: 300.

  • suburb

    string

    The sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. D (dependent locality) in i18napis, address-level3 in HTML5.1, AddressLine/properties/CountrySpecificLocalityLine[3] in AddressDoctor, and SUBURB in PayPal USER2 database. Can be a suburb or a bairro or neighborhood in Brazil. In India, street name information is often not available but a sublocality/district can be a very small area.

    Maximum length: 300.

  • city

    string

    The city name.
  • state

    string

    The two-letter code for US states or the equivalent for other countries.
  • country_code

    string

    The ISO 3166-1 alpha-2 country code.
    Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
  • postal_code

    string

    The zip code or equivalent. Typically required for countries that have them. For list of countries that do not have postal codes, see postal code.

attribute

  • action_type

    enum

    The action type.

    Possible values: DELETE, MERGE, REPLACE.

  • name

    string

    The attribute name.
  • values

    array

    An array of values.

attributions

  • merchant_id

    string

    The account ID for the merchant.
  • partner_id

    string

    The account ID for the partner.
  • account_attributions

    array

    The account-related attributions for the user.
  • product_attributions

    array

    The product-related attributions for the user.
  • attribution_types

    array

    [DEPRECATED] Maintained for backward compatibility. The account-related attributions for the user.

attributions_list

  • attributions

    array (contains the attributions object)

    The merchant's attributions for all partners.

bank_account

  • account_number

    string

    The bank account number.
  • account_type

    enum

    The bank account type.

    Possible values: BUSINESS_CHECKING, BUSINESS_SAVINGS, CUSTOM, NORMAL, CHECKING, SAVINGS, UNKNOWN.

  • currency_code

    string

    The bank account's primary currency code.
  • identifiers

    array (contains the bank_account_identifiers object)

    An array of IDs. The array must contain the ROUTING_NUMBER_1 ID.
  • branch_location

    object

    The location of the bank branch.
  • bank_name

    string

    The name of the bank. Required for Canada, GB, and AU banks.
  • transfer_type

    enum

    The type of bank transfer method.

    Possible values: NORMAL, WIRE.

  • beneficiary

    object

    The beneficiary of the bank account.

bank_account_identifiers

  • type

    enum

    The identifier type.

    Possible values: BANK_CODE, BI_CODE, BRANCH_CODE, ROUTING_NUMBER_1, ROUTING_NUMBER_2, ROUTING_NUMBER_3, SWIFT_CODE.

  • value

    string

    The identifier value.

bank_branch_location

beneficiary

  • name_as_in_issuer

    string

    The full name of the beneficiary.
  • name

    object

    The name of the beneficiary.

billing_agreement

  • description

    string

    The billing agreement description.
  • billing_experience_preference

    object

    The partner-specific billing experience options.
  • merchant_custom_data

    string

    The custom data that the merchant passes for the billing agreement.
  • approval_url

    string

    The URL to which the merchant is redirected to enter into the billing agreement.
  • ec_token

    string

    The billing agreement token that contains agreement details.

billing_experience_preference

  • experience_id

    string

    The ID of the payment web experience profile.
  • billing_context_set

    boolean

    Indicates whether the partner has already displayed billing context to the merchant.

business_details

  • phone_contacts

    array (contains the onboarding_common-user-phone object)

    The business contact phone number.
  • business_address

    object

    The business address.
  • business_type

    string (contains the supported_business_types object)

    The busienss type.
  • category

    string

    The customer's business category code. PayPal uses the standard industry merchant category codes. For a list of codes, see Business Categories and Subcategories.

    Pattern: ^\d+$.

  • sub_category

    string

    The customer's business subcategory code. PayPal uses the standard industry merchant category codes. For a list of codes, see Business Categories and Subcategories.

    Pattern: ^\d+$.

  • names

    array (contains the business_name object)

    An array of business names.
  • business_description

    string

    A description of the business goals.
  • event_dates

    array (contains the date_of_event object)

    An array of event dates for the business.
  • website_urls

    array

    An array of website URLs for the business.
  • annual_sales_volume_range

    object

    The total annual sales volume range for the business.
  • average_monthly_volume_range

    object

    The average monthly volume range for the business.
  • identity_documents

    array (contains the identity_document object)

    The various IDs that uniquely identify the user, such as license number, social security number, and so on.
  • email_contacts

    array (contains the onboarding_common-user-email_contact object)

    An array of applicable email addresses to use to contact the business.

business_info

  • type

    enum

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

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

  • sub_type

    string

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

    object

    The information about the government body under which the business was established.
  • place_of_establishment

    object

    Information about the place of establishment for the business.
  • names

    array (contains the business_name object)

    An array of business names.
  • identifications

    array (contains the identification object)

    An array of identification documents. A valid type is BUSINESS_REGISTRATION_NUMBER, CNPJ, EMPLOYMENT_IDENTIFICATION_NUMBER, or VALUE_ADDED_TAX_ID.
  • employer_identification_number

    string

    [DEPRECATED] The employer identification number (EIN) ID. For US only. For non-US accounts, use business_info/identifications.

    Pattern: ^\d+$.

  • phones

    array (contains the phone_with_type object)

    An array of phone types. Valid value is BUSINESS or WORK.
  • category

    string

    The line of business.
  • sub_category

    string

    The business sub-category.
  • merchant_category_code

    string

    The merchant category code.
  • date_business_established

    string

    The date and time when the merchant's business was established.
  • date_of_registration

    string

    The date and time when the merchant was registered.
  • dispute_email

    string

    The dispute email address.
  • vat_id

    string

    [DEPRECATED] Instead, use business_info/identifications.

    Pattern: ^\d+$.

  • vat_country_code

    string

    [DEPRECATED] Instead, use business_info/identifications.
  • business_sales_details

    object

    The business sales details.
  • customer_service

    object

    The customer service information.
  • addresses

    array (contains the address object)

    An array of merchant addresses.
  • country_code_of_incorporation

    string

    The country of business incorporation.
  • stakeholders

    array (contains the business_stakeholders object)

    The business stakeholder information.
  • designation

    object

    The business designation.

business_name

  • type

    enum

    The business title.

    Possible values: LEGAL, DOING_BUSINESS_AS, STOCK_TRADING_NAME.

  • name

    string

    The business name.

business_owner_info

  • email

    string

    The payer's email address.
  • name

    object

    The payer's name.
  • account_owner_relationships

    array (contains the merchant_relation object)

    The familial relationships that are attached to the merchant.
  • country_code_of_nationality

    string

    The two-character IS0-3166-1 country code of the payment sender's country of residence.
  • addresses

    array (contains the address object)

    An array of addresses for the merchant.
  • date_of_birth

    string

    The merchant's date of birth.
  • ssn

    string

    [DEPRECATED] The social security number. For US only. For non-US accounts, use owner_info/identifications.

    Pattern: ^\d+$.

  • language_code

    string

    The preferred language code.
  • phones

    array (contains the phone_with_type object)

    An array of phone types. Value is HOME or MOBILE.
  • identifications

    array (contains the identification object)

    An array of identification document types. Valid type is CPF, DRIVERS_LICENSE, IMMIGRANT_ID, INDIVIDUAL_TAX_IDENTIFICATION_NUMBER, MEDICAL_INSURANCE_ID, NATIONAL_ID, PASSPORT_NUMBER, PENSION_FUND_ID, SOCIAL_SECURITY_NUMBER, and SOCIAL_INSURANCE_NUMBER.
  • occupation

    string

    The owner occupation.

business_sales_details

  • average_price

    object

    Average transaction price
  • average_monthly_volume

    object

    Average monthly sales volume
  • sales_venues

    array (contains the sales_venue object)

    sales venues of the business
  • website

    string

    Primary URL of business

    Maximum length: 2048.

  • revenue_from_online_sales

    object

    Percentage of revenue attributable to online sales

business_stakeholders

  • ownership_percentage

    string

    The stakeholder's percentage of ownership. Valid for only the BENEFICIAL_OWNER type.
  • type

    enum

    The stakeholder type.

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

  • country_code_of_nationality

    string

    The two-character IS0-3166-1 country code for the stakeholder's country of residence.
  • date_of_birth

    string

    The stakeholder's date of birth.
  • name

    object

    The stakeholder's name.
  • addresses

    array (contains the address object)

    An array of addresses for the stakeholder.
  • phones

    array (contains the phone_with_type object)

    An array of phone numbers for the stakeholder.
  • identifications

    array (contains the identification object)

    An array of identification documents for the stakeholder.
  • place_of_birth

    object

    The stakeholder's place of birth.

capabilities

  • capabilities

    array (contains the capability object)

    An array of partner capabilities.

capability

  • name

    enum

    The partner capability.

    Possible values: ONBOARDING, ACCOUNT_MANAGEMENT, CONSOLIDATION.

  • attributes

    array

    The capability properties.

certificate

  • api_user_name

    string

    The API user name for the merchant.
  • api_password

    string

    The API password for the merchant.
  • fingerprint

    string

    The fingerprint.
  • download_link

    string

    The URL of the page from where to download the certificate.

classic_third_party_details

  • permission_list

    array (contains the supported_classic_permissions object)

    An array of permissions that the partner wants the customer to grant.

country_code

  • country_code

    string

    The ISO 3166-1 alpha-2 country code.
    Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.

    Minimum length: 2.

    Maximum length: 2.

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

create_account_response

  • payer_id

    string

    The payer ID. This property is empty when an error occurs during account creation.

    Maximum length: 127.

  • partner_merchant_external_id

    string

    The external merchant ID.

    Maximum length: 127.

  • merchant_authorization_code

    string

    The merchant authorization code.
  • custom_data

    array (contains the keyvalue object)

    A custom key-and-value pair that is returned to the caller. For example, aa_token.
  • errors

    array

    An array of errors.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

create_referral_data_response

  • referral_data-create_referral_data_response

    object

    The share referral data response.

credential

  • signature

    object

    The signature credential.
  • certificate

    object

    The certificate credential.

currency

currency_code

  • currency_code

    string

    Three-letter ISO 4217 alphabetical currency code.

    Minimum length: 3.

    Maximum length: 3.

currency_range

  • minimum_amount

    object

    The minimum value of the range. This value is inclusive.
  • maximum_amount

    object

    The maximum value of the range. This value is inclusive.

customer_capabilities

  • capability

    enum

    The capability to enable for the customer. The API_INTEGRATION capability collects API permissions that are required by the partner for the customer's integration.

    Possible values: API_INTEGRATION, BANK_ADDITION, BILLING_AGREEMENT, CONTEXTUAL_MARKETING_CONSENT.

  • api_integration_preference

    object

    The integration details for the partner-customer API permission. Required if capability_type is API_INTEGRATION.
  • billing_agreement

    object

    The details of the billing agreement between the merchant and partner.

customer_service

  • email

    string

    The business's customer service email address.
  • phone

    object

    The business's customer service phone number.
  • message

    array (contains the customer_service_message object)

    The customer service message.

customer_service_message

  • type

    enum

    The customer service message type.

    Possible values: ONLINE, RETAIL.

  • headline

    string

    The headline.

    Maximum length: 50.

  • logo_image_url

    string

    The URL to the logo image.

    Maximum length: 255.

  • service_image_url

    string

    The URL to the service image.

    Maximum length: 255.

  • seller_message

    string

    The seller message.

    Maximum length: 2000.

date_of_event

  • event_type

    string

    The event type.
  • event_date

    string

    The date and time portion of when the event type occurred. For accuracy, submit this value in UTC time zone if the exact time zone is not known.

designation

  • title

    string

    The business owner title
  • business_area

    string

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

email_address

  • email_address

    string

    A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. To validate an email address, services must send an email to it and not rely on static validation of the address.
    Note: Due to RFC 5321, an email address can be up to 254 characters long even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. It is nearly impossible to define a regular expression that validates email addresses correctly, especially after you take internationalization into account. This pattern verifies only that the string contains an unquoted @ sign.

    Minimum length: 3.

    Maximum length: 254.

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

entity_identifier_type

  • onboarding_common-user-identity_document_type

    enum

    The types of IDs supported within the onboarding domain. To reference these types, more general names are used.
    Note: Use the most specific type. If you cannot find a specific type, use the closest matching value. For example, use SOCIAL_SECURITY_NUMBER instead of TAX_IDENTIFICATION_NUMBER.

    Possible values: SOCIAL_SECURITY_NUMBER, EMPLOYMENT_IDENTIFICATION_NUMBER, TAX_IDENTIFICATION_NUMBER, PASSPORT_NUMBER, PENSION_FUND_ID, MEDICAL_INSURANCE_ID, CNPJ, CPF.

error

  • name

    string

    Human readable, unique name of the error. It is recommended that this value is streamed out in error response from catalog's error_spec.json#name.
  • debug_id

    string

    PayPal internal identifier used for correlation purposes.
  • message

    string

    Message describing the error. It is recommended that this value is streamed out in error response from catalog's error_spec.json#message.
  • information_link

    string

    URI for detailed information related to this error for the developer. It is recommended that this value is streamed out in error response from one of the links from catalog's error_spec.json#links.
  • details

    array (contains the ppaas_error_details object)

    Additional details for the error. Mandatory for client side 4xx errors.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

establishment_location

  • state

    string

    The state or territory of the government body with which the business was established.
  • country_code

    string

    The two-character IS0-3166-1 country code of the country with which the business was established.

experience_preference

  • launch_type

    enum

    The launch type. Indicates whether the onboarding occurs in a full or mini browser.

    Possible values: FULL_BROWSER, MINI_BROWSER.

  • logo_url

    string

    The URL to the partner logo. Overwrites any previously-provided image URL for business accounts.

financial_information

  • bank_accounts

    array (contains the bank_account object)

    An array of bank accounts. Can contain only one bank account.

financial_instrument_data

government_body

  • name

    string

    The name of enabling legislation.

identification

  • type

    enum

    The identification document type.

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

  • value

    string

    The identification document number.
  • masked

    boolean

    Indicates whether the value is a partial value, such as four SSN digits instead of the full nine digits. This flag might not always be honored based on the supplied context.
  • issuer_country_code

    string

    The two-character IS0-3166-1 country code of the issuer country.

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

  • issuer_state

    string

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

    string

    The issuer city. Applies to only some document types, such as trade_registration_number document.
  • place_of_issue

    string

    The place of issue. Applies to only some document types, such as TAX_ID for country Turkey (TR).
  • issuer_description

    string

    The issuer description. For example, Registration Authority.

identifier_attributes

  • list_action

    enum

    The action type.

    Possible values: MERGE, REPLACE.

  • attributes

    array (contains the attribute object)

    Any additional attributes for the identity.

identity

  • platform_type

    enum

    The platform type.

    Possible values: MARKETPLACE, PAYPAL.

  • principal_type

    enum

    The identity type.

    Possible values: USER, APPLICATION, GE_CREDIT, BANK_ACCOUNT, CREDIT_CARD, BUYER_CREDIT, EMAIL, IP_ADDRESS, VISITOR_ID, MACHINE_ID.

  • identifier

    string

    The ID for this identity, such as payer_id.
  • visible_identifiers

    object

    The visible ID for the identity.
  • identifier_attributes

    object

    Additional attributes for the identity.

identity_document

  • type

    string

    The ID type.
  • value

    string

    The ID value.

    Pattern: ^[A-Za-z0-9]+$.

  • partial_value

    boolean

    Indicates whether the value is a partial value, such as four SSN digits instead of the full nine digits. This flag might not always be honored based on the supplied context.
  • issuer_country_code

    string

    The two-character IS0-3166-1 country code of the issuer country.

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

integration_details

  • partner_id

    string

    The payer ID of the partner who needs to complete integration with the client.
  • classic_api_integration_type

    enum

    The classic API integration type information. Required if partner wants the classic API integration. Value is:
    • THIRD_PARTY. Partner has and wants to use their own API credentials to make API calls on the merchant's behalf. The classic_third_party_details are required.
    • FIRST_PARTY_INTEGRATED. The partner wants to call the PayPal API to get and use merchant's API credentials to make API calls. Choose this option if the partner wants the merchant to provide their credentials through the UI. The classic_first_party_details are required.
    • FIRST_PARTY_NON_INTEGRATED. The classic_first_party_details are required.

    Possible values: THIRD_PARTY, FIRST_PARTY_INTEGRATED, FIRST_PARTY_NON_INTEGRATED.

  • rest_api_integration

    object

    REST API integration. Required to integrate with PayPal REST endpoints.
  • classic_third_party_details

    object

    The classic third-party details. Required if the partner has and wants to use their own API credentials to call APIs on the customer's behalf. The flow prompts for the required permission to be granted by the customer to the partner.
  • classic_first_party_details

    enum

    The classic first-party details. Required if the partner wants to use the merchant's API credentials to make calls on his or her behalf.

    Possible values: SIGNATURE, CERTIFICATE.

  • rest_third_party_details

    object

    The REST third-party details. Required if the partner wants to integrate with the PayPal REST endpoints solution.

json_patch

  • op

    enum

    The operation to perform.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    String. Contains a JSON pointer value to a location within the target document where the operation is performed.
  • value

    see description

    New value to apply based on the operation. op=remove does not require a value.
    Possible types: number, integer, string, boolean, null, array, object
  • from

    string

    String. Contains a JSON pointer value to the location in the target document from which to move the value. Required for op=move.

json_patch_request

  • items

    (contains the json_patch object)

    Request object used for a JSON patch.

keyvalue

  • key

    string

    The key. For example, aa_token.
  • value

    string

    The value.

known_major_events_for_a_user_entity

  • onboarding_common-events_type

    enum

    The major events that can occur for an onboarding entity.

    Possible values: BIRTH, ESTABLISHED, INCORPORATION, OPERATION.

limitation

  • name

    string

    The title of the limitation that was applied to the account.
  • restrictions

    array

    An array of individual restriction names.

lookup

  • submitter_payer_id

    string

    The payer ID of the partner account that shared the referral data.

    Read only.

  • partner_referral_id

    string

    The partner referral reference key.

    Read only.

  • lookup_type

    string

    The type of ID linked with this referral ID.
  • lookup_value

    string

    The value of the ID linked with this referral ID.

mam_account_creation_request

  • owner_info

    object

    The business owner information.
  • business_info

    object

    The business information.
  • account_status

    string

    The account status.
  • account_currency

    string

    Three-letter ISO 4217 alphabetical currency code.
  • secondary_currency

    array (contains the currency_code object)

    An array of secondary currencies.

    Minimum length: 3.

    Maximum length: 3.

  • payment_receiving_preferences

    object

    The payment receiving preferences.
  • account_relations

    array (contains the account_relations object)

    Account relationships.
  • account_permissions

    array (contains the account_permissions object)

    The account permissions.
  • timezone

    string

    The time zone.
  • partner_merchant_external_id

    string

    The external merchant ID.

    Maximum length: 127.

  • loginable

    boolean

    Indicates whether you can log in to the account.
  • partner_tax_reporting

    boolean

    Indicates whether the partner reports taxes.
  • signup_options

    object

    The options that are applied after sign up.
  • financial_info

    object

    The financial information.

merchant_acquisition_partner

  • partner_id

    string

    The account ID of the partner.
  • launch_type

    enum

    Indicates whether the onboarding occurs in a full browser, mini-browser, or a light box. Default is F for full browser.

    Possible values: FULL_BROWSER, LIGHT_BOX, EMBEDDED, MINI_BROWSER.

  • receives_credential

    boolean

    Indicates whether the partner is integrated to receive a merchant credential. Default is false.
  • product_selection

    enum

    The type of product that the merchant who is referred by the partner can choose. Valid value is:
    • Y. The merchant can choose a partner-supported product.
    • P. The merchant can choose any product.
    • N. The merchant cannot change the product.

    Possible values: Y, N, P.

  • logo_url

    string

    The URL to the partner logo. Enables partners to update their logo through preferences. Overwrites any previously provided image URL for the partner business accounts.
  • notification_url

    string

    The partner-provided notification URL.
  • integration_preferences

    array (contains the product-integration object)

    An array of preferences that are required for a partner to integrate this product. Changes based on a product.
  • region_preferences

    array (contains the region-preferences object)

    The preferences that differ by country.
  • agreements_accepted

    array

    An array of agreement types that the partner accepts.
  • display_name

    string

    The display name for the partner.

    Read only.

merchant_integration

  • tracking_id

    string

    The partner-provided tracking ID.
  • merchant_id

    string

    The merchant ID.
  • products

    array (contains the product object)

    An array of statuses for all products that the merchant integrated with the partner.
  • payments_receivable

    boolean

    Indicates whether the merchant account can receive payments.
  • primary_email_confirmed

    boolean

    Indicates whether the primary email of the merchant is confirmed.
  • primary_email

    string

    The account's primary email.
  • date_created

    string

    The date and time when the account was created.
  • granted_permissions

    array

    The permissions that the merchant granted to the partner.
  • api_credentials

    object

    The merchant's API credentials.
  • oauth_integrations

    array (contains the oauth-integration object)

    The OAuth integration information between a partner and merchant.
  • limitations

    array (contains the limitation object)

    The merchant account's limitations.

merchant_relation

  • name

    object

    The familial relationship name.
  • relation

    enum

    The relationship to the merchant account owner.

    Possible values: MOTHER.

  • country_code_of_nationality

    string

    The nationality of the familial relationship.

message

  • message

    string

    The message. Maximum length is 255 alphanumeric characters.
  • language_code

    string

    The locale code of the message. Must be a supported locale code.

money_range

  • minimum_amount

    object

    The minimum amount of the range. This value is inclusive.
  • maximum_amount

    object

    The minimum value of the range. This value is inclusive.

money_type

  • currency_code

    string

    Three-letter ISO 4217 alphabetical currency code.
  • value

    string

    The value, which can be anything from:
    • An integer. For currencies that are not typically fractional, such as JPY.
    • A three-place decimal fraction. For currencies that are subdivided into thousandths, such as TND.
    • An eight-place decimal fraction. For currencies such as Bitcoin.
    • For the required number of decimal places for a currency code, see ISO 4217.

    Maximum length: 32.

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

name_of_a_party

  • prefix

    string

    Prefix to the party name. Also known as title.

    Maximum length: 140.

  • given_name

    string

    The given name of the party. Also known as first name or name. Required when the party name is for a person.

    Maximum length: 140.

  • surname

    string

    The surname or family name of the party. Also known as last name. Required when the party name is for a person. Can also be used to store multiple surnames including matronymic surname, or mother's family name.

    Maximum length: 140.

  • middle_name

    string

    The middle name of the party. Can also be used to store multiple middle names including patronymic name.

    Maximum length: 140.

  • suffix

    string

    The name suffix for the party.

    Maximum length: 140.

  • alternate_full_name

    string

    The alternate name for the party. Can be business name, nick name, or any other name that cannot be parsed into first, last name. Required when the party name is for a business.

    Maximum length: 300.

notification

  • suppress_welcome_email

    boolean

    Indicates whether the welcome email is sent or suppressed.
  • ipn_notify_url

    string

    The URL to the page where the IPN notification is posted.
  • reminder_email_frequency

    enum

    The frequency with which the reminder email is sent to the PayPal user after the account is created. A valid value is:
    • DEFAULT. All reminder emails are sent.
    • NONE. No reminder emails are sent.

      Possible values: DEFAULT, NONE.

    oauth_integration

    • integration_type

      enum

      The integration type between the partner and merchant.

      Possible values: FIRST_PARTY_INTEGRATED, FIRST_PARTY_NON_INTEGRATED, THIRD_PARTY, OAUTH_THIRD_PARTY.

    • integration_method

      enum

      The partner's integration method for PayPal APIs.

      Possible values: PAYPAL, BRAINTREE.

    • status

      enum

      The integration status.

      Possible values: A, I.

    • oauth_third_party_integration

      array (contains the oauth-third-party object)

      An array of partner client ID and merchant client ID values with associated scopes.

    oauth_integration_preferences

    • scope

      string

      The scope URI.
    • mandatory

      boolean

      Indicates whether the scope is required.

    oauth_third_party

    • partner_client_id

      string

      The partner's client ID.
    • merchant_client_id

      string

      The merchant's client ID.
    • scopes

      array

      The scopes for the partner to which the merchant has consented.
    • access_token

      string

      The access token for the partner-selected integration method.
    • refresh_token

      string

      The refresh token for the partner-selected integration method.

    onboarding_common_fin_inst_bank_details

    • nick_name

      string

      Short name for the bank account given by user.
    • account_number

      string

      Bank account number. These only represents the numeric values without any additional formatting

      Pattern: \d+.

    • account_type

      enum

      Checking /savings/current account

      Possible values: CHECKING, SAVINGS.

    • currency_code

      string

      The primary currency code of the account. This should conform to ISO 4217 currency codes

      Pattern: ^([A-Z]){3}$.

    • identifiers

      array

      This list of instrument institute's attributes helps to identify the instrument uniquely. It will be used along with the account number for identification. For banks with IBAN info only, the IBAN number will be filled in in this element. For banks with BBAN info only, the BBAN number will be filled in in this element. For banks with IBAN and BBAN info, the IBAN number will be filled in in this element.
    • branch_location

      object

      branch_location for the bank - if applicable
    • mandate_agreed

      boolean

      denotes whether user has agreed to the Mandate for FI authorization

    onboarding_common_user_email_contact

    • email_address

      string

      The actual email address
    • role

      enum

      The role of the email address

      Possible values: CUSTOMER_SERVICE.

    onboarding_common_user_phone

    • phone_number_details

      object

      The phone number details.
    • phone_type

      string

      The phone type.

    partner_integration_response

    • integration

      object

    • preference_onboarding_status

      enum

      The merchant onboarding status.

      Possible values: PENDING, COMPLETE, NOT_APPLICABLE.

    partner_options

    • partner_fields

      array (contains the keyvalue object)

      The custom partner fields.

    partner_specific_identifier

    • type

      enum

      The type of ID.

      Possible values: TRACKING_ID, ACCOUNT_LINKING_ID.

    • value

      string

      value of the identifier

    payment_receiving_preferences

    • block_unconfirmed_us_address_payments

      boolean

      Indicates whether to block unconfirmed US address payments.
    • block_non_us_payments

      boolean

      Indicates whether to block non-US payments.
    • block_echeck_payments

      boolean

      Indicates whether to block eCheck payments.
    • block_cross_currency_payments

      boolean

      Indicates whether to block cross-currency payments.
    • block_send_money_payments

      boolean

      Indicates whether to block send money payments.
    • alternate_payment_url

      string

      The alternative payments URL.
    • display_instructions_text_input

      boolean

      Indicates whether to display instructions text input.
    • cc_soft_descriptor

      string

      The credit card soft descriptor. Maximum length is seven alphanumeric characters. A valid special character is ., -, or *. If you include a special character, you must include one numeric character.

      Minimum length: 2.

      Maximum length: 11.

    • cc_soft_descriptor_extended

      string

      The extended credit card soft descriptor. Maximum length is seven alphanumeric characters. A valid special character is ., -, or *. If you include a special character, you must include one numeric character.

      Minimum length: 2.

      Maximum length: 19.

    percentage_range

    • minimum_percent

      number

      The minimum percentage value of the range. This value is inclusive.
    • maximum_percent

      number

      The maximum percentage value of the range. This value is inclusive.

    person_details

    • email_address

      string

      The account holder's email address.
    • name

      object

      The customer's legal name.
    • phone_contacts

      array (contains the onboarding_common-user-phone object)

      The personal phone contact of the customer.
    • home_address

      object

      The account holder's home address.
    • date_of_birth

      object

      The primary account holder's date of birth.
    • nationality_country_code

      string

      The two-character IS0-3166-1 country code for the account holder's nationality.
    • identity_documents

      array (contains the identity_document object)

      An array of identity documents that uniquely identify the user. Value is a license number, social security number, and so on.
    • account_owner_relationships

      array (contains the merchant_relation object)

      The familial relationships that are attached to the merchant.

    phone_type

    • country_code

      string

      Country calling code (CC) as defined by E.164. Combined length of CC+national must not be more than 15 digits.

      Minimum length: 1.

      Maximum length: 3.

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

    • national_number

      string

      National number as defined by E.164. Combined length of CC+national must not be more than 15 digits. National number consists of National Destination Code (NDC) and Subscriber Number (SN).

      Minimum length: 1.

      Maximum length: 14.

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

    • extension_number

      string

      Extension number.

      Minimum length: 1.

      Maximum length: 15.

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

    phone_types_for_a_person_or_business_party

    • phone_type

      enum

      List of supported phone types.

      Possible values: FAX, HOME, MOBILE, OTHER, PAGER.

    phone_with_type

    • type

      enum

      The phone type.

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

    • country_code

      string

      The country calling code (CC), as defined by E.164. The combined length of CC and the national number must not be more than 15 digits.

      Minimum length: 1.

      Maximum length: 3.

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

    • national_number

      string

      The national number as defined by E.164. The combined length of CC and the national number must not be more than 15 digits. The national number consists of the National Destination Code (NDC) and Subscriber Number (SN).

      Minimum length: 1.

      Maximum length: 14.

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

    • extension_number

      string

      The extension number.

      Minimum length: 1.

      Maximum length: 15.

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

    place_of_birth

    ppaas_error_details

    • field

      string

      Field that caused the error. If the field is in body, a JSON pointer to that field.
    • value

      string

      Value of the field that caused the error.
    • location

      string

      Location of the field that caused the error. Value is body, path, or query. Default is body.
    • issue

      string

      Reason for the error. Stream this value out in error response from catalog's error_spec_issue.json#issue.

    product

    • name

      enum

      The product name.

      Possible values: EXPRESS_CHECKOUT, WEBSITE_PAYMENTS_STANDARD, MASS_PAYMENT, EMAIL_PAYMENTS, EBAY_CHECKOUT, PAYFLOW_LINK, PAYFLOW_PRO, WEBSITE_PAYMENTS_PRO_3_0, WEBSITE_PAYMENTS_PRO_2_0, VIRTUAL_TERMINAL, HOSTED_SOLE_SOLUTION, BILL_ME_LATER, MOBILE_EXPRESS_CHECKOUT, PAYPAL_HERE, MOBILE_IN_STORE, PAYPAL_STANDARD, MOBILE_PAYPAL_STANDARD, MOBILE_PAYMENT_ACCEPTANCE, PAYPAL_ADVANCED, PAYPAL_PRO, ENHANCED_RECURRING_PAYMENTS.

    • vetting_status

      enum

      The vetting status of the product, if applicable.

      Possible values: APPROVED, PENDING, DECLINED.

    • active

      boolean

      Indicates whether the product is active.

    product_integration

    • product

      enum

      The product.

      Possible values: EXPRESS_CHECKOUT, WEBSITE_PAYMENTS_STANDARD, MASS_PAYMENT, EMAIL_PAYMENTS, EBAY_CHECKOUT, PAYFLOW_LINK, PAYFLOW_PRO, WEBSITE_PAYMENTS_PRO_3_0, WEBSITE_PAYMENTS_PRO_2_0, VIRTUAL_TERMINAL, HOSTED_SOLE_SOLUTION, BILL_ME_LATER, MOBILE_EXPRESS_CHECKOUT, PAYPAL_HERE, MOBILE_IN_STORE, PAYPAL_STANDARD, MOBILE_PAYPAL_STANDARD, MOBILE_PAYMENT_ACCEPTANCE, PAYPAL_ADVANCED, PAYPAL_PRO, ENHANCED_RECURRING_PAYMENTS.

    • integration_type

      enum

      The integration type for the product for merchants referred through this partner. Value is:
      • T. Third-party integration.
      • F. First-party integration.

      Possible values: FIRST_PARTY, THIRD_PARTY.

    • credential_type

      enum

      The credential type for a first-party integration. Value is:
      • C. Certificate.
      • S. Signature.
      • T. OAuth token.

      Required if integration_type is provided.

      Possible values: SIGNATURE, CERTIFICATE, OAuth_TOKEN.

    • permissions

      array

      An array of permissions. The partner expects that these permissions are granted by the merchant for third-party integrations. Different products need different permissions. Therefore, permissions also depend on the product.

    product_preferences

    • product

      enum

      The product.

      Possible values: EXPRESS_CHECKOUT, WEBSITE_PAYMENTS_STANDARD, MASS_PAYMENT, EMAIL_PAYMENTS, EBAY_CHECKOUT, PAYFLOW_LINK, PAYFLOW_PRO, WEBSITE_PAYMENTS_PRO_3_0, WEBSITE_PAYMENTS_PRO_2_0, VIRTUAL_TERMINAL, HOSTED_SOLE_SOLUTION, BILL_ME_LATER, MOBILE_EXPRESS_CHECKOUT, PAYPAL_HERE, MOBILE_IN_STORE, PAYPAL_STANDARD, MOBILE_PAYPAL_STANDARD, MOBILE_PAYMENT_ACCEPTANCE, PAYPAL_ADVANCED, PAYPAL_PRO, ENHANCED_RECURRING_PAYMENTS.

    • url

      string

      The URL to the page to which the merchant is redirected after sign up. Maximum length is 2048 alphanumeric characters.

    products_for_which_clients_can_be_onboarded

    • referral_data-product_name

      enum

      List of supported products

      Possible values: EXPRESS_CHECKOUT.

    referral_data

    • customer_data

      object

      The customer's data. Required for account creation.
    • requested_capabilities

      array (contains the customer_capabilities object)

      The capabilities to enable for the customer so that he or she can share data.
    • web_experience_preference

      object

      The preferences to customize the customer's web experience. Default is partner's preferences.
    • collected_consents

      array (contains the legal_consent object)

      The collected consents that the partner has received from this customer. If SHARE_DATA_CONSENT is not granted, the API does not store customer_data.
    • products

      array (contains the products_for_which_clients_can_be_onboarded object)

      An array of products to which to onboard the customer.

    referral_data_response

    • partner_referral_id

      string

      The partner referral ID.

      Read only.

    • submitter_payer_id

      string

      The payer ID of the API caller who shared the referral data.

      Read only.

    • referral_data

      object

      The referral data that was shared with PayPal.
    • links

      array (contains the link object)

      HATEOAS links related to this call.

      Read only.

    referral_integration_preference

    • payment_method

      enum

      The payment method type of the REST integration.

      Possible values: PAYPAL, BRAINTREE.

    • oauth_third_party

      array (contains the oauth-integration-preferences object)

      The partner-preferred scopes for the REST integration.

    referral_preferences

    • experience_preferences

      array (contains the experience-preference object)

      The visual experience-related preference of the partner.
    • integration_preferences

      array (contains the referral-integration-preference object)

      An array of PayPal integration types that partner prefers to provide to its referred merchant.
    • sweep_preferences

      array (contains the sweep-account-preference object)

      An array of holding fund preferences.
    • links

    region_preferences

    • country_code

      string

      The two-character IS0-3166-1 country code for the country for the preferences. Preferences can change by country and language.
    • product_preferences

      array (contains the product-preferences object)

      An array of product preferences.
    • return_message

      array (contains the message object)

      An array of partner-generated messages to the merchant after signup completion. Messages can change by country and language.

    rest_api_integration

    • integration_method

      enum

      The integration method.

      Possible values: BRAINTREE, PAYPAL.

    • integration_type

      enum

      The integration type. Required if the partner wants REST endpoint integration. Choose REST_THIRD_PARTY_DETAILS if the partner wants to integrate with the Braintree v.zero solution for PayPal REST endpoints.

      Possible values: THIRD_PARTY.

    rest_third_party_details

    • partner_client_id

      string

      partner's clientId in PayPal.
    • feature_list

      array (contains the the_rest_endpoint_feature_enum object)

      An array of features that the partner wants to access in PayPal on behalf of the merchant. The merchant grants permission for these features to the partner.

    sales_venue

    • type

      enum

      The type of business sales venue.

      Possible values: EBAY, ANOTHER_MARKET_PLACE, OWN_WEB_SITE, OTHER.

    • ebay_id

      string

      The eBay ID.
    • description

      string

      The business sales venue description.

    signature

    • api_user_name

      string

      The merchant's API user name.
    • api_password

      string

      The merchant's API password.
    • signature

      string

      The merchant's signature credential.

    signup_options

    • partner_options

      object

      The partner options.
    • legal_agreements

      array (contains the legal_agreement object)

      The legal agreements.
    • web_experience_preference

      object

      The partner-specific web options.
    • notification_options

      object

      The notification options.

    simple_postal_address

    • line1

      string

      The first line of the address. For example, number, street, and so on.
    • line2

      string

      Optional. The second line of the address. For example, suite, apartment number, and so on.
    • city

      string

      The city name.
    • state

      string

      The two-letter code for US states. The equivalent for other countries.
    • country_code

      string

      The ISO 3166-1 alpha-2 country code.
      Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
    • postal_code

      string

      Zip code or equivalent. Typically required for countries that have them. For list of countries that do not have postal codes, see Postal code.

    supported_business_types

    • referral_data-business_type_enum

      enum

      The supported business types.

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

    supported_classic_permissions

    • referral_data-classic_permission_enum

      enum

      The supported classic permission names.

      Possible values: EXPRESS_CHECKOUT, REFUND, DIRECT_PAYMENT, AUTH_CAPTURE, BUTTON_MANAGER, ACCOUNT_BALANCE, TRANSACTION_DETAILS, TRANSACTION_SEARCH, REFERENCE_TRANSACTION, RECURRING_PAYMENTS, MANAGE_PENDING_TRANSACTION_STATUS, NON_REFERENCED_CREDIT, ENCRYPTED_WEBSITE_PAYMENTS, MOBILE_CHECKOUT, AIR_TRAVEL, INVOICING, ACCESS_BASIC_PERSONAL_DATA.

    sweep_account_preference

    • payer_id

      string

      The sweep account payer ID.
    • currency_code

      string

      The currency specific to the sweep account.

    the_rest_endpoint_feature_enum

    • referral_data-rest_endpoint_features_enum

      enum

      The supported REST endpoint. For the OAuth scope for each endpoint, see rest_features_scope_mapping.

      Possible values: PAYMENT, REFUND, FUTURE_PAYMENT, DIRECT_PAYMENT, PARTNER_FEE.

    timezone

    • timezone

      enum

      The time zone.

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

    user

    • customer_type

      enum

      The customer type based on which consumer or merchant account is created in the PayPal system.

      Possible values: CONSUMER, MERCHANT.

    • person_details

      object

      The customer's personal information.
    • business_details

      object

      The customer's business information.
    • financial_instrument_data

      object

      The customer's financial instrument data, which can be used to add a financial instrument to the customer's PayPal account.
    • preferred_language_code

      string

      The locale code for the user's preferred language. Must be a supported locale code.

      Pattern: ^([a-z]){2}_([A-Z]){2}$.

    • primary_currency_code

      string

      The primary three-character currency code of the account.
    • referral_user_payer_id

      object

      The customer's payer ID. Pre-populated when the customer is an existing PayPal account holder.
    • partner_specific_identifiers

      array (contains the partner_specific_identifier object)

      The ID of the customer in partner system.

    visible_identifiers

    • list_action

      enum

      The action type.

      Possible values: MERGE, REPLACE.

    • identifiers

      array

      An array of visible IDs, such as email, for this identity.

    web_experience_preference

    • partner_logo_url

      string

      The URL for the partner logo to display in the web flow.
    • return_url

      string

      The URL to the page to which the client is redirected upon successful action.
    • return_url_description

      string

      The return URL description.
    • action_renewal_url

      string

      The URL to the page to which the client is redirected to renew the action URL after it expires.
    • show_add_credit_card

      boolean

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

      boolean

      Indicates whether to prompt the end user to initiate confirmation of their mobile phone. This number must be supplied by the API caller through mobilePhoneNumber. Default is false.
    • use_mini_browser

      boolean

      If true, presents the user with a single-page signup flow in a mini-browser. If false, presents the user with the multi-page full-size signup flow.
    • use_hua_email_confirmation

      boolean

      Indicates whether to use the hosted_user_agreement_url URL to confirm email. If true, appends the email confirmation code to the hosted_user_agreement_url URL to confirm the email. If false, does not append the email confirmation code to the hosted_user_agreement_url URL and does not confirm the email.

    Additional API information

    Error messages

    In addition to common REST API errors, the Merchant Onboarding API can return the following errors. Corrective action is provided where possible.

    • INTERNAL_ERROR

      The process cannot be processed due to an internal error.

    • PARTNER_BUSINESS_ERROR

      Caller is not a business account or the account is closed or locked.

    • PARTNER_BUSINESS_ERROR

      Consent between this merchant and partner already exists. Note: Use PATCH to update the content.

    • PARTNER_BUSINESS_ERROR

      Setting of OAuthIntegrations failed for partner and merchant.

    • PARTNER_BUSINESS_ERROR

      Getting of OAuthIntegrations failed for partner and merchant.

    • PARTNER_BUSINESS_ERROR

      Merchant ID is the same as the partner ID.

    • PARTNER_BUSINESS_ERROR

      Partner can get the merchant details only if the merchant is referred by the partner.

    • PARTNER_BUSINESS_ERROR

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

    • PARTNER_BUSINESS_ERROR

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

    • PARTNER_BUSINESS_ERROR

      Link between this lookup type and referral_id already exists.

    • PARTNER_BUSINESS_ERROR

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

    • RESOURCE_NOT_FOUND_ERROR

      Agreements not found for this account.

    • RESOURCE_NOT_FOUND_ERROR

      No integration found between partner and merchant.

    • RESOURCE_NOT_FOUND_ERROR

      Consent not found.

    • RESOURCE_NOT_FOUND_ERROR

      Referral ID is invalid.

    • RESOURCE_NOT_FOUND_ERROR

      No referrals are linked with this account.

    • Unprocessable Entity

      Invalid request.

    • USER_BUSINESS_ERROR

      Account for this account ID does not exist.

    • UNAUTHORIZED

      This API call is not authorized.

    • UNAUTHORIZED

      User is not owner of the consent.

    • UNAUTHORIZED

      Partner cannot use another partner for this API.