{ "openapi": "3.1.0", "info": { "title": "Client Registration API", "description": "Note: The Client Registration API is not intended for use by developers who have previously registered for a Developer Account on the eBay platform.

The Client Registration API registers a new regulated third-party financial application 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.", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "1.0.0" }, "servers": [ { "url": "https://tppz.ebay.com{basePath}", "description": "Production server url.", "variables": { "basePath": { "description": "base path.", "default": "/developer/registration/v1" } } }, { "url": "https://tppz.sandbox.ebay.com{basePath}", "description": "Sandbox server url.", "variables": { "basePath": { "description": "base path.", "default": "/developer/registration/v1" } } } ], "security": [ {} ], "paths": { "/client/register": { "post": { "tags": [ "register" ], "description": "Note: The Client Registration API is not intended for use by developers who have previously registered for a Developer Account on the eBay platform.
This call registers a new third party financial application with eBay.

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.


A successful call returns an HTTP status code of 201 Created and the response payload.

Registering multiple applications

A regulated third party provider (identified by a unique organizationIdentifier) may register up to 15 different applications with eBay provided the unique software_id for each application is passed in at the time of registration.

Each registerClient call that passes in a unique software_id will generate new client_id and client_secret keypairs.

If a third party provider calls registerClient using a previously registered software_id, the existing client_id and client_secret keypairs are returned.

Note: For additional information about using an organizationIdentifier, refer to the following sections of ETSI Technical Specification 119 495:", "operationId": "registerClient", "parameters": [ { "name": "Content-Type", "in": "header", "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "This container stores information about the third party provider's financial application that is being registered.", "content": { "application/json": { "schema": { "description": "This container stores information about the third party provider's financial application that is being registered.", "$ref": "#/components/schemas/ClientSettings" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "description": "Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

\"error\": \"invalid_policy_uri\", \"error_description\": \"The policy_uri presented is invalid.\"

Refer to the following table for the list of errors and their descriptions.", "columns": [ "error", "error_description" ], "errors": { "invalid_policy_uri": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_policy_uri", "error_description": "The policy_uri presented is invalid.", "description": "The policy_uri presented is invalid." }, "invalid_contact_email": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_contact_email", "error_description": "The value of one or more of the contact email addresses is invalid.", "description": "The value of one or more of the contact email addresses is invalid." }, "invalid_software_statement": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_software_statement", "error_description": "The software statement presented is invalid.", "description": "The software statement presented is invalid." }, "invalid redirect_uri": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid redirect_uri", "error_description": "The value of one or more redirection URIs is invalid or missing.", "description": "The value of one or more redirection URIs is invalid or missing." }, "internal_server_error": { "domain": "CLIENT_REGISTRATION", "category": "APPLICATION", "error": "internal_server_error", "error_description": "There was a problem with an eBay internal system or process. Please retry.", "description": "There was a problem with an eBay internal system or process. Please retry." }, "invalid_request": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_request", "error_description": "Empty request or some field has error.", "description": "Empty request or some field has error." }, "maximum_limit_keysets_reached": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "maximum_limit_keysets_reached", "error_description": "You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation.", "description": "You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation." }, "caller_not_registered": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "caller_not_registered", "error_description": "Caller is not registered", "description": "Caller is not registered" }, "invalid_license": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_license", "error_description": "Invalid license", "description": "Invalid license" }, "invalid_qtsp": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_qtsp", "error_description": "Certificate not issued by a valid Qtsp", "description": "Certificate not issued by a valid Qtsp" }, "certificate_expired": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "certificate_expired", "error_description": "Certificate expired", "description": "Certificate expired" }, "certificate_revoked": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "certificate_revoked", "error_description": "Certificate revoked", "description": "Certificate revoked" }, "invalid_signature": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_signature", "error_description": "Not a valid signature", "description": "Not a valid signature" }, "role_mismatch": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "role_mismatch", "error_description": "Role not matching", "description": "Role not matching" }, "invalid_certificate": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "invalid_certificate", "error_description": "Invalid certificate", "description": "Invalid certificate" }, "missing_certificate": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "missing_certificate", "error_description": "Missing certificate", "description": "Missing certificate" }, "certificate_validation_error": { "domain": "CLIENT_REGISTRATION", "category": "REQUEST", "error": "certificate_validation_error", "error_description": "Internal errors as validating client certificate", "description": "Internal errors as validating client certificate" }, "internal_service_error": { "domain": "CLIENT_REGISTRATION", "category": "APPLICATION", "error": "internal_service_error", "error_description": "Internal errors as calling another service", "description": "Internal errors as calling another service" } } }, "x-error-codes-introduction": "Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

\"error\": \"invalid_policy_uri\", \"error_description\": \"The policy_uri presented is invalid.\"

Refer to the following table for the list of errors and their descriptions.", "x-error-codes": [ { "error": "invalid_policy_uri", "error_description": "The policy_uri presented is invalid." }, { "error": "invalid_contact_email", "error_description": "The value of one or more of the contact email addresses is invalid." }, { "error": "invalid_software_statement", "error_description": "The software statement presented is invalid." }, { "error": "invalid redirect_uri", "error_description": "The value of one or more redirection URIs is invalid or missing." }, { "error": "internal_server_error", "error_description": "There was a problem with an eBay internal system or process. Please retry." }, { "error": "invalid_request", "error_description": "Empty request or some field has error." }, { "error": "maximum_limit_keysets_reached", "error_description": "You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation." }, { "error": "caller_not_registered", "error_description": "Caller is not registered" }, { "error": "invalid_license", "error_description": "Invalid license" }, { "error": "invalid_qtsp", "error_description": "Certificate not issued by a valid Qtsp" }, { "error": "certificate_expired", "error_description": "Certificate expired" }, { "error": "certificate_revoked", "error_description": "Certificate revoked" }, { "error": "invalid_signature", "error_description": "Not a valid signature" }, { "error": "role_mismatch", "error_description": "Role not matching" }, { "error": "invalid_certificate", "error_description": "Invalid certificate" }, { "error": "missing_certificate", "error_description": "Missing certificate" }, { "error": "certificate_validation_error", "error_description": "Internal errors as validating client certificate" }, { "error": "internal_service_error", "error_description": "Internal errors as calling another service" } ], "x-error-codes-html": "Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

\"error\": \"invalid_policy_uri\", \"error_description\": \"The policy_uri presented is invalid.\"

Refer to the following table for the list of errors and their descriptions.

errorerror_description
invalid_policy_uriThe policy_uri presented is invalid.
invalid_contact_emailThe value of one or more of the contact email addresses is invalid.
invalid_software_statementThe software statement presented is invalid.
invalid redirect_uriThe value of one or more redirection URIs is invalid or missing.
internal_server_errorThere was a problem with an eBay internal system or process. Please retry.
invalid_requestEmpty request or some field has error.
maximum_limit_keysets_reachedYou have exceeded the maximum number of API keysets. For more information, see the API call reference documentation.
caller_not_registeredCaller is not registered
invalid_licenseInvalid license
invalid_qtspCertificate not issued by a valid Qtsp
certificate_expiredCertificate expired
certificate_revokedCertificate revoked
invalid_signatureNot a valid signature
role_mismatchRole not matching
invalid_certificateInvalid certificate
missing_certificateMissing certificate
certificate_validation_errorInternal errors as validating client certificate
internal_service_errorInternal errors as calling another service
" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Registers a new third party financial application with eBay.", "x-text-error-codes": [ { "error": "invalid_policy_uri", "error_description": "The policy_uri presented is invalid." }, { "error": "invalid_contact_email", "error_description": "The value of one or more of the contact email addresses is invalid." }, { "error": "invalid_software_statement", "error_description": "The software statement presented is invalid." }, { "error": "invalid redirect_uri", "error_description": "The value of one or more redirection URIs is invalid or missing." }, { "error": "internal_server_error", "error_description": "There was a problem with an eBay internal system or process. Please retry." }, { "error": "invalid_request", "error_description": "Empty request or some field has error." }, { "error": "maximum_limit_keysets_reached", "error_description": "You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation." }, { "error": "caller_not_registered", "error_description": "Caller is not registered" }, { "error": "invalid_license", "error_description": "Invalid license" }, { "error": "invalid_qtsp", "error_description": "Certificate not issued by a valid Qtsp" }, { "error": "certificate_expired", "error_description": "Certificate expired" }, { "error": "certificate_revoked", "error_description": "Certificate revoked" }, { "error": "invalid_signature", "error_description": "Not a valid signature" }, { "error": "role_mismatch", "error_description": "Role not matching" }, { "error": "invalid_certificate", "error_description": "Invalid certificate" }, { "error": "missing_certificate", "error_description": "Missing certificate" }, { "error": "certificate_validation_error", "error_description": "Internal errors as validating client certificate" }, { "error": "internal_service_error", "error_description": "Internal errors as calling another service" } ], "x-http-request-headers-note": "There is no Authorization Header for this API.", "x-oauth-scope-note": "This API does not use an OAuth scope.", "x-requires-authorization-header": false, "x-uses-oauth-scope": false, "security": [ {} ], "x-http-status-codes": { "201": "Created", "400": "Bad Request", "404": "Not Found", "500": "Internal Server Error" }, "x-error-codes-introduction": "Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

\"error\": \"invalid_policy_uri\", \"error_description\": \"The policy_uri presented is invalid.\"

Refer to the following table for the list of errors and their descriptions.", "x-error-codes": [ { "error": "invalid_policy_uri", "error_description": "The policy_uri presented is invalid." }, { "error": "invalid_contact_email", "error_description": "The value of one or more of the contact email addresses is invalid." }, { "error": "invalid_software_statement", "error_description": "The software statement presented is invalid." }, { "error": "invalid redirect_uri", "error_description": "The value of one or more redirection URIs is invalid or missing." }, { "error": "internal_server_error", "error_description": "There was a problem with an eBay internal system or process. Please retry." }, { "error": "invalid_request", "error_description": "Empty request or some field has error." }, { "error": "maximum_limit_keysets_reached", "error_description": "You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation." }, { "error": "caller_not_registered", "error_description": "Caller is not registered" }, { "error": "invalid_license", "error_description": "Invalid license" }, { "error": "invalid_qtsp", "error_description": "Certificate not issued by a valid Qtsp" }, { "error": "certificate_expired", "error_description": "Certificate expired" }, { "error": "certificate_revoked", "error_description": "Certificate revoked" }, { "error": "invalid_signature", "error_description": "Not a valid signature" }, { "error": "role_mismatch", "error_description": "Role not matching" }, { "error": "invalid_certificate", "error_description": "Invalid certificate" }, { "error": "missing_certificate", "error_description": "Missing certificate" }, { "error": "certificate_validation_error", "error_description": "Internal errors as validating client certificate" }, { "error": "internal_service_error", "error_description": "Internal errors as calling another service" } ], "x-error-codes-html": "Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

\"error\": \"invalid_policy_uri\", \"error_description\": \"The policy_uri presented is invalid.\"

Refer to the following table for the list of errors and their descriptions.

errorerror_description
invalid_policy_uriThe policy_uri presented is invalid.
invalid_contact_emailThe value of one or more of the contact email addresses is invalid.
invalid_software_statementThe software statement presented is invalid.
invalid redirect_uriThe value of one or more redirection URIs is invalid or missing.
internal_server_errorThere was a problem with an eBay internal system or process. Please retry.
invalid_requestEmpty request or some field has error.
maximum_limit_keysets_reachedYou have exceeded the maximum number of API keysets. For more information, see the API call reference documentation.
caller_not_registeredCaller is not registered
invalid_licenseInvalid license
invalid_qtspCertificate not issued by a valid Qtsp
certificate_expiredCertificate expired
certificate_revokedCertificate revoked
invalid_signatureNot a valid signature
role_mismatchRole not matching
invalid_certificateInvalid certificate
missing_certificateMissing certificate
certificate_validation_errorInternal errors as validating client certificate
internal_service_errorInternal errors as calling another service
" } } }, "components": { "schemas": { "ClientDetails": { "type": "object", "properties": { "client_id": { "type": "string", "description": "A unique, eBay-generated id assigned to the third party application at the time it was registered." }, "client_id_issued_at": { "type": "integer", "description": "The UNIX timestamp when the client_id was issued. This time is represented as the number of seconds from \"1970-01-01T00:00:00Z\", as measured in UTC, until the date/time of issuance. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information.", "format": "int32" }, "client_name": { "type": "string", "description": "User-friendly name for the third party financial application.

Note: Language tags are not supported. Therefore, client_name will be specified in English." }, "client_secret": { "type": "string", "description": "A unique OAuth 2.0 secret string assigned by eBay to the third party application at the time it is registered. This value should be unique for multiple instances of a client using the same client_id. This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1.

Note: client_secret is unique to the organization identifier of subject name which contains jurisdiction, NCA Id, and Authorization Number." }, "client_secret_expires_at": { "type": "integer", "description": "The UNIX timestamp when the client_secret expires.

Note: When a client_secret has been provided, this field is REQUIRED.
A returned value of 0 indicates that the client_secret never expires.

This time is represented as the number of seconds from \"1970-01-01T00:00:00Z\", as measured in UTC, until the expiration date and time. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol section 3.2.1 for complete information.", "format": "int32" }, "contacts": { "type": "array", "description": "This container stores an array of email addresses for representatives at the third party provider responsible for the application being registered.", "items": { "type": "string" } }, "grant_types": { "type": "array", "description": "An array of OAuth 2.0 grant type strings that the client software can use at the token endpoint. Supported grant type values are:
If the token endpoint is used in the grant type, the value of this parameter MUST be the same as the value of the grant_type parameter passed to the token endpoint defined in the grant type definition. Authorization servers may allow for other values as defined in the grant type extension process described in OAuth 2.0, Section 4.5. If omitted, the default behavior is that the client will use only the authorization_code Grant Type.", "items": { "type": "string" } }, "policy_uri": { "type": "string", "description": "The URL string pointing to a human-readable privacy policy document that describes how the third party provider collects, uses, retains, and discloses personal data.

Note: Only HTTPS URLs are supported for policy_uri strings.
Note: This URL must not point to the eBay Privacy Policy.
The authorization server should display this secure URL to the end-user if it is provided. The value of this field must point to a valid and secure web page.

Note: Language tags are not supported. Therefore, policy_uri will be displayed in English." }, "redirect_uris": { "type": "array", "description": "An eBay system-generated value assigned to the application. This value represents the redirect uri(s) submitted by the user either in the request payload (i.e., the redirect_uris field,) or the software_statement.", "items": { "type": "string" } }, "scope": { "type": "string", "description": "String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens. The semantics of values in this list are service specific." }, "software_id": { "type": "string", "description": "A unique identifier string provided by the client developer or software publisher at the time of registration that identifies the client software being registered.

Unlike client_id which should change between instances, the software_id should be the same value for all instances of the client software. That is, the software_id should remain unchanged across multiple updates or versions of the same piece of software." }, "software_statement": { "type": "string", "description": "The Software Statement Assertion (SSA), a JSON Web Token (JWT), that has been issued by the OpenBanking identifier. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information." } }, "description": "This container stores information about the third party provider's financial application that has been registered with eBay.", "required": [ "client_id", "client_id_issued_at", "client_secret", "client_secret_expires_at", "grant_types", "redirect_uris", "scope" ] }, "ClientSettings": { "type": "object", "properties": { "client_name": { "type": "string", "description": "User-friendly name for the third party financial application.

Note: Language tags are not supported. Therefore, client_name must be specified in English." }, "contacts": { "type": "array", "description": "This container stores an array of email addresses that can be used to contact the registrant.

Note: When more than one email address is provided, the first email in the array will be used as the developer account's email address. All other email addresses will be used as general contact information.", "items": { "type": "string" } }, "policy_uri": { "type": "string", "description": "The URL string pointing to a human-readable privacy policy document that describes how the third party provider collects, uses, retains, and discloses personal data.

Note: Only HTTPS URLs are supported for policy_uri strings.
Note: This URL must not point to the eBay Privacy Policy.
The value of this field must point to a valid and secure web page.

Note: Language tags are not supported. Therefore, policy_uri will be displayed in English." }, "redirect_uris": { "type": "array", "description": "An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.

Note: Only the first URI string from the list will be used.

Note: Each redirection URI must be an absolute URI as defined by [RFC3986] Section 4.3.", "items": { "type": "string" } }, "software_id": { "type": "string", "description": "A unique identifier string assigned by the client developer or software publisher to identify the client software being registered.

Unlike client_id which should change between instances, the software_id should be the same value for all instances of the client software. That is, the software_id should remain unchanged across multiple updates or versions of the same piece of software. The value of this field is not intended to be human readable and is usually opaque to the client and authorization server." }, "software_statement": { "type": "string", "description": "The Software Statement Assertion (SSA) that has been issued by the OpenBanking identifier.

Note: This value must be Base64 encoded and not plain JSON.

Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information." } }, "description": "This container stores application-specific information that is provided at the time of registration.", "required": [ "redirect_uris" ] }, "Error": { "type": "object", "description": "Unlike other eBay REST APIs, the Client Registration API returns text-based errors instead of numeric eBay error codes.", "properties": { "error": { "type": "string", "description": "A text-based error identifier returned by the Client Registration API.", "enum": [ "invalid_policy_uri", "invalid_contact_email", "invalid_software_statement", "invalid redirect_uri", "internal_server_error", "invalid_request", "maximum_limit_keysets_reached", "caller_not_registered", "invalid_license", "invalid_qtsp", "certificate_expired", "certificate_revoked", "invalid_signature", "role_mismatch", "invalid_certificate", "missing_certificate", "certificate_validation_error", "internal_service_error" ] }, "error_description": { "type": "string", "description": "A description of the error condition." } }, "required": [ "error", "error_description" ] }, "ClientRegistrationErrorEnum": { "type": "string", "description": "This enumerated type lists the text-based errors returned by the Client Registration API. | - **invalid_policy_uri**: The policy_uri presented is invalid. - **invalid_contact_email**: The value of one or more of the contact email addresses is invalid. - **invalid_software_statement**: The software statement presented is invalid. - **invalid redirect_uri**: The value of one or more redirection URIs is invalid or missing. - **internal_server_error**: There was a problem with an eBay internal system or process. Please retry. - **invalid_request**: Empty request or some field has error. - **maximum_limit_keysets_reached**: You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation. - **caller_not_registered**: Caller is not registered - **invalid_license**: Invalid license - **invalid_qtsp**: Certificate not issued by a valid Qtsp - **certificate_expired**: Certificate expired - **certificate_revoked**: Certificate revoked - **invalid_signature**: Not a valid signature - **role_mismatch**: Role not matching - **invalid_certificate**: Invalid certificate - **missing_certificate**: Missing certificate - **certificate_validation_error**: Internal errors as validating client certificate - **internal_service_error**: Internal errors as calling another service", "enum": [ "invalid_policy_uri", "invalid_contact_email", "invalid_software_statement", "invalid redirect_uri", "internal_server_error", "invalid_request", "maximum_limit_keysets_reached", "caller_not_registered", "invalid_license", "invalid_qtsp", "certificate_expired", "certificate_revoked", "invalid_signature", "role_mismatch", "invalid_certificate", "missing_certificate", "certificate_validation_error", "internal_service_error" ] } } } }