Payment Experience 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 Payment Experience web 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.

Request

Pass a web_profile object in the JSON request body.

  • name

    string

    required

    The web experience profile name. Unique for a set of profiles for a merchant.
  • temporary

    boolean

    Indicates whether the profile persists for three hours or permanently. Set to false to persist the profile permanently. Set to true to persist the profile for three hours.
  • flow_config

    object

    The flow configuration parameters.
  • input_fields

    object

    The input field customization parameters.
  • presentation

    object

    Style and presentation parameters.
SDK samples: C#, Node.js, 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" \
-d '{
  "name": "ebayProfile",
  "presentation": {
  "logo_image": "http://www.ebay.com"
  },
  "input_fields": {
  "no_shipping": 1,
  "address_override": 1
  },
  "flow_config": {
  "landing_page_type": "billing",
  "bank_txn_pending_url": "http://www.ebay.com"
  }
}'

Response

A successful request returns a create_profile_response object that contains the unique ID of the new profile.

  • id

    string

    The ID of the web experience profile.

    Read only.

  • name

    string

    The web experience profile name. Unique for a set of profiles for a merchant.
  • temporary

    boolean

    Indicates whether the profile persists for three hours or permanently. Set to false to persist the profile permanently. Set to true to persist the profile for three hours.
  • flow_config

    object

    The flow configuration parameters.
  • input_fields

    object

    The input field customization parameters.
  • presentation

    object

    Style and presentation parameters.

Sample Response

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

Show web experience profile details

GET /v1/payment-experience/web-profiles/profile-id
Shows details for a web experience profile, by ID.

Parameters

Specify the profile ID in the GET URI.

  • profile-id

    path string

    The ID of the profile for which to show details.
SDK samples: C#, Node.js, 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 a web_profile object that contains the profile details.

  • id

    string

    The ID of the web experience profile.

    Read only.

  • name

    string

    The web experience profile name. Unique for a set of profiles for a merchant.
  • temporary

    boolean

    Indicates whether the profile persists for three hours or permanently. Set to false to persist the profile permanently. Set to true to persist the profile for three hours.
  • flow_config

    object

    The flow configuration parameters.
  • input_fields

    object

    The input field customization parameters.
  • presentation

    object

    Style and presentation parameters.

Sample Response

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

List web experience profiles

GET /v1/payment-experience/web-profiles
Lists all web experience profiles for a merchant or subject.

Request

Provide the access token in the Authorization request header.

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"

Response

A successful request returns a web_profile_list object that lists all profiles, with details, that the merchant owns.

  • items

    array (contains the web_profile object)

    A payment web experience profile.

Sample Response

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

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.

Parameters

Pass the profile ID in the PUT URI.

  • profile-id

    path string

    The ID of the profile to update.

Request

Pass a web_profile object in the JSON request body.

  • name

    string

    required

    The web experience profile name. Unique for a set of profiles for a merchant.
  • temporary

    boolean

    Indicates whether the profile persists for three hours or permanently. Set to false to persist the profile permanently. Set to true to persist the profile for three hours.
  • flow_config

    object

    The flow configuration parameters.
  • input_fields

    object

    The input field customization parameters.
  • presentation

    object

    Style and presentation parameters.
SDK samples: C#, Node.js, 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": "ebayProfile",
  "presentation": {
  "logo_image": "http://www.ebay.com"
  },
  "input_fields": {
  "no_shipping": 1,
  "address_override": 1
  },
  "flow_config": {
  "landing_page_type": "billing",
  "bank_txn_pending_url": "http://www.ebay.com"
  }
}'

Response

A successful request returns the HTTP 204 status code.

Sample Response

204 No Content

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, if needed, a new value to complete the operation.

Parameters

Pass the profile ID in the PATCH URI.

  • profile-id

    path string

    The ID of the profile to partially update.

Request

Pass a patch_request object in the JSON request body. The API supports the add, remove, replace and test operations.

  • items

    array (contains the json-patch object)

    A JSON patch object that you can use to apply partial updates to resources.
SDK samples: C#, Node.js, 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" \
-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 status code.

Sample Response

204 No Content

Delete web experience profile

DELETE /v1/payment-experience/web-profiles/profile-id
Deletes a web experience profile, by ID.

Parameters

Pass the profile ID in the DELETE URI.

  • profile-id

    path string

    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 status code.

Sample Response

204 No Content

Common object definitions

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 for only the Giropay payment method or bank transfer payment method.
  • user_action

    string

    Defines whether to present the buyer with a Continue or Pay Now checkout flow. To present buyers with the Pay Now checkout flow, set useraction=commit. Default is the Continue checkout flow.
    Checkout flowChoose whenDescription
    ContinueYou do not know the final payment amount when you initiate the checkout flow.The default flow. Redirects the buyer to the PayPal payment page, which shows the Continue button. When the buyer clicks Continue, the buyer can change the payment amount.
    Pay NowYou know the final payment amount when you initiate the checkout flow.Set user_action=commit. Redirects the buyer to the PayPal payment page, which shows the Pay Now button. When the buyer clicks Pay Now, the payment is processed immediately.
  • return_uri_http_method

    string

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

input_fields

  • allow_note

    boolean

    Indicates whether the buyer can enter a note to the merchant on the PayPal page during checkout.
  • no_shipping

    see description

    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 buyer's account profile.

    Possible types: integer
  • address_override

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

    Possible types: integer

json_patch

  • op

    enum

    The operation to perform.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    A JSON pointer that references a location in the target document where the operation is performed.

    Read only.

  • value

    string

    The value to apply based on the operation. The remove operation does not require a value.

    Read only.

  • from

    string

    A JSON pointer that references the location in the target document from which to move the value.

    Read only.

json_patch_request

  • items

    (contains the json-patch object)

    A JSON patch object that you can use 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

    The web experience profile name. Unique for a set of profiles for a merchant.
  • temporary

    boolean

    Indicates whether the profile persists for three hours or permanently. Set to false to persist the profile permanently. Set to true to persist the profile for three hours.
  • flow_config

    object

    The flow configuration parameters.
  • input_fields

    object

    The input field customization parameters.
  • presentation

    object

    Style and presentation parameters.

web_profile_list

  • items

    (contains the web_profile object)

    A payment web experience profile.

Additional API information

Error messages

In addition to common REST API errors, the Payment Experience API can return the following errors. Corrective action is provided where possible.

  • DUPLICATE_REQUEST_ID

    The value of the PayPal-Request-ID header has already been used.

  • INTERNAL_SERVICE_ERROR

    An internal service error has occurred.

  • INVALID_RESOURCE_ID

    Invalid profile ID passed.

  • MALFORMED_REQUEST

    The JSON request does not map to the expected resource.

  • PERMISSION_DENIED

    No permission for the requested operation.

  • VALIDATION_ERROR

    Invalid data passed.

  • WRONG_PATCH

    The provided patch has errors.