Payment Experience Web Profiles API

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 Web experience profiles.

Web profiles (resource group)

Use the /payment-experience/web-profiles resource to create, show details for, list, update, partially update, and delete web experience profiles.

Create web experience profile

POST /v1/payment-experience/web-profiles

Creates a web experience profile. In the JSON request body, specify the profile name and details.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

PayPal-Request-Id

string

The server stores keys for three hours. For more information about PayPal-Request-Id, see PayPal-Request-Id.

Request body

name

string

required

The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary

boolean

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

object

The flow configuration parameters.
input_fields

object

The input field customization parameters.
presentation

object

The style and presentation parameters.

SDK samples: C#, Node, PHP, Python

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: abcdefgh123" \
-d '{
  "name": "exampleProfile",
  "presentation": {
    "logo_image": "https://example.com/logo_image/"
  },
  "input_fields": {
    "no_shipping": 1,
    "address_override": 1
  },
  "flow_config": {
    "landing_page_type": "billing",
    "bank_txn_pending_url": "https://example.com/flow_config/"
  }
}'

Response

A successful request, with or without the optional PayPal-Request-Id request header, returns the HTTP 201 Created status code and a JSON response body that shows the profile details and the ID of the profile. Any subsequent calls with the same PayPal-Request-Id request header value within a three-hour window returns the HTTP 200 OK status code and a JSON response body that shows the profile details and the ID of the profile.

id

string

The ID of the web experience profile.

Read only.
name

string

The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary

boolean

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

object

The flow configuration parameters.
input_fields

object

The input field customization parameters.
presentation

object

The style and presentation parameters.

Sample Response

{
  "id": "XP-RFV4-PVD8-AGHJ-8E5J",
  "name": "exampleProfile",
  "temporary": false,
  "presentation": {
    "logo_image": "https://example.com/logo_image/"
  },
  "input_fields": {
    "no_shipping": 1,
    "address_override": 1
  },
  "flow_config": {
    "landing_page_type": "billing",
    "bank_txn_pending_url": "https://example.com/flow_config/",
    "user_action": "commit"
  }
}

List web experience profiles

GET /v1/payment-experience/web-profiles

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.

Response

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.

web_profile_list

array (contains the web_profile object)

An array of web profiles.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payment-experience/web-profiles \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Sample Response

[
  {
    "id": "XP-GCUV-X35G-HNEY-5MJY",
    "name": "exampleProfile",
    "flow_config": {
      "landing_page_type": "billing",
      "bank_txn_pending_url": "https://example.com/flow_config/"
    },
    "input_fields": {
      "no_shipping": 1,
      "address_override": 1
    },
    "presentation": {
      "logo_image": "https://example.com/logo_image/"
    }
  },
  {
    "id": "XP-A88A-LYLW-8Y3X-E5ER",
    "name": "exampleProfile",
    "flow_config": {
      "landing_page_type": "billing",
      "bank_txn_pending_url": "https://example.com/flow_config/"
    },
    "input_fields": {
      "no_shipping": 1,
      "address_override": 1
    },
    "presentation": {
      "logo_image": "https://example.com/logo_image/"
    }
  },
  {
    "id": "XP-RFV4-PVD8-AGHJ-8E5J",
    "name": "exampleProfile",
    "flow_config": {
      "bank_txn_pending_url": "https://example.com/flow_config/"
    },
    "input_fields": {
      "no_shipping": 1,
      "address_override": 1
    },
    "presentation": {
      "logo_image": "https://example.com/logo_image/"
    }
  }
]

Delete web experience profile

DELETE /v1/payment-experience/web-profiles/{profile_id}

Deletes a web experience profile, by ID.

Path parameters

profile_id

string

required

The ID of the profile to delete.

SDK samples: C#, PHP, Python

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-A88A-LYLW-8Y3X-E5ER \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

Sample Response

204 No Content

Show web experience profile details by ID

GET /v1/payment-experience/web-profiles/{profile_id}

Shows details for a web experience profile, by ID.

Path parameters

profile_id

string

required

The ID of the profile for which to show details.

SDK samples: C#, Node, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-RFV4-PVD8-AGHJ-8E5J \
-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 the profile details.

id

string

The ID of the web experience profile.

Read only.
name

string

The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary

boolean

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

object

The flow configuration parameters.
input_fields

object

The input field customization parameters.
presentation

object

The style and presentation parameters.

Sample Response

{
  "id": "XP-RFV4-PVD8-AGHJ-8E5J",
  "name": "exampleProfile",
  "temporary": false,
  "flow_config": {
    "landing_page_type": "billing",
    "bank_txn_pending_url": "https://example.com/flow_config/"
  },
  "input_fields": {
    "no_shipping": 1,
    "address_override": 1
  },
  "presentation": {
    "logo_image": "https://example.com/logo_image/"
  }
}

Partially update web experience profile

PATCH /v1/payment-experience/web-profiles/{profile_id}

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.

Path parameters

profile_id

string

required

The ID of the profile to partially update.

Request body

patch_request

array (contains the patch object)

An array of JSON patch objects to apply partial updates to resources.

SDK samples: C#, Node, PHP, Python

Sample Request

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-RFV4-PVD8-AGHJ-8E5J \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: abcdefgh123" \
-d '[
  {
    "op": "add",
    "path": "/presentation/brand_name",
    "value": "new_brand_name"
  },
  {
    "op": "remove",
    "path": "/flow_config/landing_page_type"
  }
]'

Response

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

Sample Response

204 No Content

Update web experience profile

PUT /v1/payment-experience/web-profiles/{profile_id}

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.

Path parameters

profile_id

string

required

The ID of the profile to update.

Request body

name

string

required

The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary

boolean

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

object

The flow configuration parameters.
input_fields

object

The input field customization parameters.
presentation

object

The style and presentation parameters.

SDK samples: C#, Node, PHP, Python

Sample Request

curl -v -X PUT https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-RFV4-PVD8-AGHJ-8E5J \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "exampleProfile",
  "presentation": {
    "logo_image": "https://example.com/logo_image/"
  },
  "input_fields": {
    "no_shipping": 1,
    "address_override": 1
  },
  "flow_config": {
    "landing_page_type": "billing",
    "bank_txn_pending_url": "https://example.com/flow_config/"
  }
}'

Response

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

Sample Response

204 No Content

Common object definitions

error

name

string

required

The human-readable, unique name of the error.

Read only.
debug_id

string

The PayPal internal ID. Used for correlation purposes.

Read only.
message

string

required

The message that describes the error.

Read only.
information_link

string

required

The URI to detailed information related to this error for the developer.

Read only.
details

array (contains the error_details object)

An array of additional details for the error.

Read only.

error_details

field

string

required

The name of the field that caused the error.
issue

string

required

The reason for the error.

flow_config

landing_page_type

string

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.
bank_txn_pending_url

string

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

string

Presents either the Continue or Pay Now checkout flow to the customer.

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.

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.
return_uri_http_method

string

The HTTP method to use to redirect the customer to a return URL. Value is GET or POST.

input_fields

no_shipping

integer
Indicates whether PayPal displays shipping address fields on the experience pages. Value is:
- 0. Displays the shipping address on the PayPal pages.
- 1. Redacts shipping address fields from the PayPal pages. For digital goods, this field is required and must be 1.
- 2. Gets the shipping address from the customer's account profile.
address_override

integer
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:
- 0. Displays the shipping address on file.
- 1. Displays the shipping address specified in this call. the customer cannot edit this shipping address.

patch

`op`

enum

required

The operation. The possible values are:

add.
Depending on the target location reference, completes one of these functions:
- The target location is an array index. Inserts a new value into the array at the specified index.
- The target location is an object parameter that does not already exist. Adds a new parameter to the object.
- The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.
remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objects	Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (`false`, `true`, and `null`)	Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.

For more information, see 4.6. test.

path

string

The JSON Pointer to the target document location at which to complete the operation.
value

number,integer,string,boolean,null,array,object

The value to apply. The remove operation does not require a value.
from

string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

patch_request

patch_request

array (contains the patch object)

An array of JSON patch objects to apply partial updates to resources.

presentation

brand_name

string

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

string

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

string

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

id

string

The ID of the web experience profile.

Read only.
name

string

required

The web experience profile name. Must be unique for a set of profiles for a merchant.
temporary

boolean

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

object

The flow configuration parameters.
input_fields

object

The input field customization parameters.
presentation

object

The style and presentation parameters.

web_profile_list

web_profile_list

array (contains the web_profile object)

An array of web profiles.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Payment Experience Web Profiles API can return the following errors.

DUPLICATE_REQUEST_ID

The value of the PayPal-Request-ID header has already been used. The PayPal-Request-ID header contains a duplicate request ID.
INTERNAL_SERVICE_ERROR

An internal service error has occurred. The request failed due to an internal server error.
INVALID_RESOURCE_ID

Invalid profile ID passed. The profile ID is not valid.
MALFORMED_REQUEST

The JSON request does not map to the expected resource. The resource in the request is not valid.
PERMISSION_DENIED

No permission for the requested operation. The caller does not have permission to complete this request.
VALIDATION_ERROR

Invalid data passed. More details can be found in the details array.
WRONG_PATCH

The provided patch has errors. More details can be found in the details array.

PayPal-Request-Id

name

temporary

flow_config

input_fields

presentation

Sample Request

id

name

temporary

flow_config

input_fields

presentation

Sample Response

web_profile_list

Sample Request

Sample Response

profile_id

Sample Request

Sample Response

profile_id

Sample Request

id

name

temporary

flow_config

input_fields

presentation

Sample Response

profile_id

patch_request

Sample Request

Sample Response

profile_id

name

temporary

flow_config

input_fields

presentation

Sample Request

Sample Response

name

debug_id

message

information_link

details

field

issue

landing_page_type

bank_txn_pending_url

user_action

return_uri_http_method

no_shipping

address_override

op

path

value

from

patch_request

brand_name

logo_image

locale_code

id

name

temporary

flow_config

input_fields

presentation

web_profile_list

Additional API information

Error messages

DUPLICATE_REQUEST_ID

INTERNAL_SERVICE_ERROR

INVALID_RESOURCE_ID

MALFORMED_REQUEST

PERMISSION_DENIED

VALIDATION_ERROR

WRONG_PATCH

`PayPal-Request-Id`

`name`

`temporary`

`flow_config`

`input_fields`

`presentation`

`id`

`name`

`temporary`

`flow_config`

`input_fields`

`presentation`

`web_profile_list`

`profile_id`

`profile_id`

`id`

`name`

`temporary`

`flow_config`

`input_fields`

`presentation`

`profile_id`

`patch_request`

`profile_id`

`name`

`temporary`

`flow_config`

`input_fields`

`presentation`

`name`

`debug_id`

`message`

`information_link`

`details`

`field`

`issue`

`landing_page_type`

`bank_txn_pending_url`

`user_action`

`return_uri_http_method`

`no_shipping`

`address_override`

`op`

`path`

`value`

`from`

`patch_request`

`brand_name`

`logo_image`

`locale_code`

`id`

`name`

`temporary`

`flow_config`

`input_fields`

`presentation`

`web_profile_list`

`DUPLICATE_REQUEST_ID`

`INTERNAL_SERVICE_ERROR`

`INVALID_RESOURCE_ID`

`MALFORMED_REQUEST`

`PERMISSION_DENIED`

`VALIDATION_ERROR`

`WRONG_PATCH`