marketplaces

Marketplaces Prerequisites

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.

To get started with PayPal for Marketplaces, you must register your marketplace with PayPal to get an access token. You use this access token for authorization when you make REST API requests.

Important: As a partner, PayPal must vet and approve you before you can use PayPal for Marketplaces. Once approved, additional permissions are attached to your account to allow access to the Marketplaces APIs.

Registration steps

1. Get a PayPal business account.
2. Create a PayPal app.
3. Get an access token.

1. Get a PayPal business account

Partners must have a PayPal business account to use the Marketplaces APIs.

Partners with an existing PayPal business accounts used with other PayPal products must create new business accounts solely for use with Marketplaces. Sign up for a PayPal Business account at paypal.com.

Note: Partners must link a bank account to the new business account.

2. Create a PayPal app

Using the Partner's business account log-on credentials, log into PayPal Developer Dashboard to create a sandbox (test server) account and a PayPal application. In creating this application, you are given a set of sandbox and live (production server) credentials called client ID and secret. These are used by your account manager to add the new Marketplaces permissions to your business account.

Important: If you already have a PayPal application, you must create a new one as the client ID associated with the application directs money movement across PayPal solutions and products. Using an existing client ID breaks existing payment agreements set up in other PayPal products.

Create a sandbox account

  1. Log in to the Developer site at https://developer.paypal.com. On the Dashboard tab, navigate to Sandbox > Accounts.

  2. Click Create Account and populate the following fields:

    Country Select the country of the merchant or buyer test account.
    Account type Select the Business radio button.
    Email address

    The email address doesn't need to be a real email address; the sandbox doesn't send any email outside of the sandbox environment. Email to sandbox accounts, generated as a result of your test API requests, are listed on both the Notifications tab on the Developer site, as well as on the sandbox test site.

    Use the assigned email value to reference this test account in your test API calls, and to log in to the sandbox site when you want to review the details associated with the account.

    Password The password must be 8-20 alphanumeric characters in length. Use the password to log in to the sandbox test site as the test account.
    First and Last names The optional name fields accept only alphabetical characters.
    PayPal balance While this field is optional, it's a good idea to create test accounts with positive bank balances. Enter an integer value between 1 and 10 Million.
    Bank Verified Account You should create Verified test accounts so you can fully test your application.
    Select Payment Card Test payments made with different payment cards by selecting either Discover or PayPal.
    (US Personal accounts only.)
    Credit card type Optionally, you can select a single credit card type for each test account. The sandbox associates a mock credit card number with the account.
    Notes Add details specific to this test account.
  3. Click Create Account.

Create a PayPal app

You need to create a PayPal app to get your credentials set to pass to your account manager. You create an app on the Developer Portal.

  1. Click My Apps & Credentials.
  2. In the REST API apps section, click Create App.
  3. Enter your REST application's name at App Name.
  4. Select the sandbox business account that you added in the sandbox as your developer account
  5. Click Create App.

Send the sandbox client ID1 shown on the resulting page and the email used on your PayPal business account to your PayPal account manager to begin the vetting process.

You will receive confirmation from PayPal when your account has been registered for use with the Marketplaces API, and you can then get an access token.

Note:

1 Credentials, or permission code strings, for PayPal applications come in sets. A set is made up of a client ID (code equivalent to a user ID) and a secret (code equivalent to a password). You are given two different sets of credentials for your PayPal app. One is for sandbox, the other is for the live environment.

3. Get an access token

After your account has been registered, you'll need to get an access token to use in the Marketplaces API. Log into the PayPal Developer Dashboard to get your client ID and secret credentials.

See Get Started for more on REST API and to understand how PayPal uses OAuth 2.0.

The get access token endpoint is /v1/oauth2/token.

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app.

In response, the PayPal authorization server issues an access token.

Re-use the access token until it expires. See our rate limiting guidelines. When it expires, you can get a new token.

cURL example

Tips:

  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.
  1. Download cURL for your environment.

  2. From the command line, run this command:

    curl -v https://api.sandbox.paypal.com/v1/oauth2/token \
      -H "Accept: application/json" \
      -H "Accept-Language: en_US" \
      -u "client_id:secret" \
      -d "grant_type=client_credentials"
    

    Where:

    /v1/oauth2/token The get access token endpoint.
    client_id Your client ID.
    secret Your secret.
    grant_type The grant type. Set to client_credentials.
  3. View the sample response.

Postman example

  1. Download the latest version of Postman for your environment, and open Postman.

  2. Select the POST method.

  3. Enter the https://api.sandbox.paypal.com/v1/oauth2/token request URL.

  4. On the Authorization tab, select the Basic Auth type and enter this information:

    Username Your client ID.
    Password Your secret.
  5. On the Body tab, select x-www-form-urlencoded and enter this information:

    key grant_type
    value client_credentials
  6. Click Send.

  7. View the sample response.

Sample response

{
  "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
  "nonce": "2017-06-08T18:30:28ZCl54Q_OlDqP6-4D03sDT8wRiHjKrYlb5EH7Di0gRrds",
  "access_token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32398
}

Where:

access_token Your access token.
expires_in The number of seconds after which the token expires. Request another token when this one expires.

Next

Onboard your sellers.

Feedback