PayPal Payment Experience API
The PayPal Payment Experience API lets merchants create web experience profiles to customize the look, feel, and flow of PayPal checkout pages.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Payment Experience Web Profiles
description: Use the Payment Experience API to create seamless payment experience profiles. For information about how to create a PayPal payment with a web experience profile, see <a href="/docs/integration/direct/payment-experience/">Web experience profiles</a>.
version: '1.3'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Web-Profiles
description: Use the `/payment-experience/web-profiles` resource to create, show details for, list, update, partially update, and delete web experience profiles.
externalDocs:
url: https://developer.paypal.com/docs/api/payment-experience/v1/
paths:
"/v1/payment-experience/web-profiles":
post:
summary: Paypal Create web experience profile
description: Creates a web experience profile. In the JSON request body, specify the profile name and details.
operationId: web-profile.create
responses:
'200':
description: A successful request, with or without the optional <code>PayPal-Request-Id</code> request header, returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the profile details and the ID of the profile. Any subsequent calls with the same <code>PayPal-Request-Id</code> request header value within a three-hour window returns the HTTP <code>200 OK</code> status code and a JSON response body that shows the profile details and the ID of the profile.
content:
application/json:
schema:
"$ref": "#/components/schemas/web_profile"
'201':
description: A successful request, with or without the optional <code>PayPal-Request-Id</code> request header, returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the profile details and the ID of the profile. Any subsequent calls with the same <code>PayPal-Request-Id</code> request header value within a three-hour window returns the HTTP <code>200 OK</code> status code and a JSON response body that shows the profile details and the ID of the profile.
content:
application/json:
schema:
"$ref": "#/components/schemas/web_profile"
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/paypal_request_id"
requestBody:
"$ref": "#/components/requestBodies/web_profile"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
get:
summary: Paypal List web experience profiles
description: Lists the latest 20 web experience profiles for a merchant or subject. To show details for these or additional profiles, you can show web experience profile details by ID.
operationId: web-profile.get-list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the latest 20 profiles that the merchant owns, with details. To show details for these or additional profiles, you can show web experience profile details by ID.
content:
application/json:
schema:
"$ref": "#/components/schemas/web_profile_list"
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
"/v1/payment-experience/web-profiles/{id}":
put:
summary: Paypal Update web experience profile
description: Updates a web experience profile, by ID. In the JSON request body, specify the profile details. If your request omits any profile parameters, any previously set values for those parameters are removed.
operationId: web-profile.update
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/id"
requestBody:
"$ref": "#/components/requestBodies/web_profile"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
patch:
summary: Paypal Partially update web experience profile
description: Partially-updates a web experience profile, by ID. In the JSON request body, specify a patch object, the path of the profile location to update, and a new value.
operationId: web-profile.partial-update
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/patch_request"
examples:
patch_request:
value:
- op: add
path: "/presentation/brand_name"
value: new_brand_name
- op: remove
path: "/flow_config/landing_page_type"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
get:
summary: Paypal Show web experience profile details by ID
description: Shows details for a web experience profile, by ID.
operationId: web-profile.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the profile details.
content:
application/json:
schema:
"$ref": "#/components/schemas/web_profile"
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/id"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
delete:
summary: Paypal Delete web experience profile
description: Deletes a web experience profile, by ID.
operationId: web-profile.delete
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'500':
description: An internal server error occurred. The request returns the HTTP `500 Internal Server Error` status code.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/id"
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment
- Oauth2:
- https://uri.paypal.com/services/payments/realtimepayment
tags:
- Web-Profiles
components:
requestBodies:
web_profile:
content:
application/json:
schema:
"$ref": "#/components/schemas/web_profile"
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/payments/payment: New special privileged scope available for payment and manage payment experience profiles. Available to internal clients only.
https://uri.paypal.com/services/payments/realtimepayment: Permission to do any real-time payment and manage-payment experience profiles with support for sale, authorize, and order intents.
schemas:
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
"$ref": "#/components/schemas/error_location"
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
type: string
minLength: 0
maxLength: 20000
pattern: "^.*$"
rel:
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 100
pattern: "^.*$"
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: "^[A-Z]*$"
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
error_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
error_details-2:
type: object
title: Error Details
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The name of the field that caused the error.
issue:
type: string
description: The reason for the error.
required:
- field
- issue
error:
type: object
title: Error
description: The error information.
properties:
name:
type: string
description: The human-readable, unique name of the error.
readOnly: true
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
readOnly: true
message:
type: string
description: The message that describes the error.
readOnly: true
information_link:
type: string
description: The URI to detailed information related to this error for the developer.
readOnly: true
details:
type: array
description: An array of additional details for the error.
readOnly: true
items:
"$ref": "#/components/schemas/error_details-2"
required:
- name
- message
- information_link
web_profile:
type: object
description: A payment web experience profile.
title: Web Profile
required:
- name
properties:
id:
type: string
readOnly: true
minLength: 22
maxLength: 22
description: The ID of the web experience profile.
name:
type: string
minLength: 1
maxLength: 50
description: The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary:
type: boolean
description: Indicates whether the profile persists for three hours or permanently. To persist the profile permanently, set to `false`. To persist the profile for three hours, set to `true`.
flow_config:
type: object
title: Flow Configuration
description: The flow configuration parameters.
properties:
landing_page_type:
type: string
minLength: 1
maxLength: 255
description: The type of landing page to display on the PayPal site for user checkout. To use the non-PayPal account landing page, set to `Billing`. To use the PayPal account login landing page, set to `Login`.
enum:
- login
- billing
bank_txn_pending_url:
type: string
format: uri
minLength: 1
maxLength: 127
description: The merchant site URL to display after a bank transfer payment. In Germany, valid only for the Giropay payment method or bank transfer payment method.
user_action:
type: string
description: Presents either the **Continue** or **Pay Now** checkout flow to the customer.<br/><br/>Default is **Continue**, or `user_action=continue`. When you do not know the final payment amount, accept this default flow, which redirects the customer to the PayPal payment page with the **Continue** button. When the customer clicks **Continue**, the customer can change the payment amount.<br/><br/> When you know the final payment amount, set `user_action=commit` to choose the **Pay Now** flow, which redirects the customer to the PayPal payment page with the **Pay Now** button. When the customer clicks **Pay Now**, the payment is processed immediately.
minLength: 1
maxLength: 255
enum:
- COMMIT
return_uri_http_method:
type: string
description: The HTTP method to use to redirect the customer to a return URL. Value is `GET` or `POST`.
minLength: 1
maxLength: 255
enum:
- GET
- POST
input_fields:
type: object
title: Input Field Customization
description: The input field customization parameters.
properties:
no_shipping:
type: integer
minimum: 0
maximum: 2
description: Indicates whether PayPal displays shipping address fields on the experience pages. Value is:<ul><li><code>0</code>. Displays the shipping address on the PayPal pages.</li><li><code>1</code>. Redacts shipping address fields from the PayPal pages. For digital goods, this field is required and must be <code>1</code>.</li><li><code>2</code>. Gets the shipping address from the customer's account profile.</li></ul>
address_override:
type: integer
minimum: 0
maximum: 1
description: Indicates whether to display the shipping address that is passed to this call rather than the one on file for this buyer on the PayPal experience pages. Value is:<ul><li><code>0</code>. Displays the shipping address on file.</li><li><code>1</code>. Displays the shipping address specified in this call. the customer cannot edit this shipping address.</li></ul>
presentation:
type: object
title: Style and Presentation
description: The style and presentation parameters.
properties:
brand_name:
type: string
minLength: 1
maxLength: 127
description: 'A label that overrides the business name in the PayPal account on the PayPal pages. Character length and limitations: 127 single-byte alphanumeric characters.'
logo_image:
type: string
minLength: 1
maxLength: 127
description: 'A URL to the logo image. A valid media type is `.gif`, `.jpg`, or `.png`. The image''s maximum width is 190 pixels and maximum height is 60 pixels. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area. PayPal recommends that you store the image on a secure (HTTPS) server. Otherwise, web browsers display a message that checkout pages contain non-secure items. Character length and limitations: 127 single-byte alphanumeric characters.'
locale_code:
type: string
minLength: 2
maxLength: 5
description: 'The locale of pages that the PayPal payment experience displays. A valid value is `AU`, `AT`, `BE`, `BR`, `CA`, `CH`, `CN`, `DE`, `ES`, `GB`, `FR`, `IT`, `NL`, `PL`, `PT`, `RU`, or `US`. A 5-character code is also valid for languages in these countries: `da_DK`, `he_IL`, `id_ID`, `ja_JP`, `no_NO`, `pt_BR`, `ru_RU`, `sv_SE`, `th_TH`, `zh_CN`, `zh_HK`, or `zh_TW`.'
web_profile_list:
type: array
title: Web Profile List
description: An array of web profiles.
minItems: 1
maxItems: 20
items:
"$ref": "#/components/schemas/web_profile"
patch:
type: object
title: Patch
description: The JSON patch object to apply partial updates to resources.
properties:
op:
type: string
description: The operation.
enum:
- add
- remove
- replace
- move
- copy
- test
path:
type: string
description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location at which to complete the operation.
value:
title: Patch Value
description: The value to apply. The <code>remove</code> operation does not require a value.
from:
type: string
description: The <a href="https://tools.ietf.org/html/rfc6901">JSON Pointer</a> to the target document location from which to move the value. Required for the <code>move</code> operation.
required:
- op
patch_request:
type: array
title: Patch Request
description: An array of JSON patch objects to apply partial updates to resources.
items:
"$ref": "#/components/schemas/patch"
parameters:
paypal_request_id:
name: PayPal-Request-Id
in: header
description: The server stores keys for three hours.
required: true
schema:
type: string
id:
name: id
in: path
description: The ID of the profile to delete.
required: true
schema:
type: string