Skip to main content

Important: Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made by EU/UK sellers. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signature to be included in the HTTP payload.

Register with eBay

Payment services regulations applicable in the EU and the UK require all regulated Account Servicing Payment Service Providers (ASPSPs) to provide secure APIs that allow regulated Third Party Payment Providers (TPPs) to access account and payment services on behalf of account holders. The regulations further dictate that a TPP should be able to use a qualified certificate issued by any Electronic Identification, Authentication and Trust Services (eIDAS) Qualified Trust Service Provider (QTSP) in order to identify and authenticate themselves to an ASPSP.

This document provides information about how TPPs can register with eBay and obtain all necessary client details and tokens required to make API calls for clients domiciled in the EU or the UK.

NOTE: Each TPP may register up to 15 different applications provided each application has a unique software ID.

Production/Sandbox environments

In addition to its standard Production environment, eBay provides developers access to a Sandbox environment in which developers can test the behavior of their applications throughout development.

Registration process

This process applies to registering clients for both eBay's Production environment as well as eBay's Sandbox (test) environment.

NOTE: There are some minor differences in the procedure that are unique to the Sandbox environment. These will be identified and described where applicable.

Step 1: Register your client with eBay

TPPs in possession of a valid eIDAS Qualified Website Authentication Certificate (QWAC) may register their client with eBay using the Client Registration API which is based on, and conforms with, RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol (except as noted in the List of Deviations from RFC 7591). Requests that conform with RFC 7591 will be accepted, however some fields will be ignored.

NOTE: eBay does not support Qualified Electronic Seal (QSEAL) certificates.

 

Important! When calling the registerClient method, Third-Party Providers (TPPs) are required to pass their valid eIDAS certificate to eBay via Mutual Transport Layer Security (MTLS) handshake Certificate Request messages.

Refer to the Client Registration API reference documentation for complete information about using the API.

NOTE: Make note of the following values as they will be required in upcoming steps:

  • client_id value
  • client_secret value
Using Sandbox for testing

As mentioned above, developers who wish to test their applications may do so using eBay's Sandbox environment. However, in order to do so, the application must first be registered with eBay's Sandbox environment by calling the Register Client API using the following Sandbox Resource URI:

POST https://tppzsb.ebay.com/developer/registration/v1/client/register

Once the application has been successfully registered, login credentials for a Test User (i.e., username and password,) may then be ascertained. This is a fairly straightforward process that uses a portion of the client_ID returned by the API.

The prototype for both username and password is:

TESTUSER_{characters_following_SBX-_in_clientID}

For example, a registered application returns:

"clientId": "SMP01-clientid-SBX-abcde0123-4f56g789"

The corresponding Sandbox credentials would be:

username: TESTUSER_abcde0123-4f56g789

password: TESTUSER_abcde0123-4f56g789

Step 2: Obtain user consent

A TPP application must obtain the user's consent before it can make requests for that user.

Refer to Getting User Consent for complete information.

NOTE: Verify that the appropriate target endpoint is being used based on the environment for which the application is being registered.

 

Sandbox Environment: When obtaining consent within the Sandbox environment, when prompted, use the Sandbox credentials created in Step 1 above to login.

Once the user has granted their consent, the user is redirected per the first redirect_uri in the redirect_uris array returned by the Register Client API call. The single-use authorization code is returned as the code query parameter for the redirect_uri.

For example, the following redirect_uri is returned:

https://client.example.org/callback2?code=v********************D&expires_in=299

The authorization code is:

v********************D

The authorization code is required when creating a user access token in Step 3.

NOTE: This authorization code cannot be used to make API requests. A valid User Access Token is required.

Step 3: Create user access token

Finally, in order to make API calls, a User Access Token must be created/retrieved by issuing an Authorization Code Grant Request. The following previously generated and returned values are required as part of this request:

  • client_id (returned by the Client Registration API)
  • client_secret (returned by the Client Registration API)
  • authorization code (returned by User Consent in Step 2)

Refer to Exchanging the authorization code for a User access token for complete information.

NOTE: Verify that the appropriate target endpoint is being used based on the environment for which the application is being registered.

Step 4: Make API calls

Refer to the following tabs for complete information about making API calls within the Production and Sandbox environments:

Error codes

When issuing Finances, Fulfillment, Post-Order, and/or Trading API calls in either the Production or Sandbox environment, an error code may be returned if information is missing or improperly formatted, a certificate has expired, etc. Refer to the following table for information about these error codes.

Code Meaning
215500 Caller is not registered
215501 Invalid license
215502 Certificate not issued by a valid Qtsp
215503 Certificate expired
215504 Certificate revoked
215506 Not a valid signature
215507 Role not matching
215508 Invalid certificate
215510 Missing certificate
215511 Internal errors as validating client certificate
215512 Internal errors as calling another service