marketplaces

Marketplaces Webhooks

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.

Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook at PayPal, users configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. PayPal signs each notification message that it delivers to your webhook listener.

After you configure a listener, you can use a sample payload to simulate a webhook event. When you simulate an event, the simulator validates that your listener can successfully receive event data without any connectivity issues and generates mock event data to show you how webhook events look. You cannot verify these mock events.

After you validate your listener, you can subscribe your listener to events. When you subscribe your listener to events, you define:

A list of events An event can be a payment authorization, a payment state change, and so on. To determine to which events to subscribe, review the supported webhook event names.
Your webhook listener URL A webhook listener is a server that you configure at a specific web URL to listen for incoming HTTP POST notification messages that are triggered when those events occur. PayPal signs each notification message that it delivers to your web URL.

Finally, verify the notifications that your listener receives when events occur.

Webhooks are asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type.

Note: Webhooks will be sent only after the seller has completed all steps to receive payments. Each country may have the seller complete a series of tasks in order to complete the setup process. If any of the steps are missing, the webhook will not be sent.

Integration steps

To configure your webhook listener to receive notification messages for payment state changes and other events:

Integration steps

1. Optional To make calls on behalf of a third party, you must be a partner in the PayPal Partner Program.
2. Required Make your first call.
3. Required Create sandbox accounts.
4. Required Configure a webhook listener.
5. Optional Simulate mock webhook events to validate your listener configuration.
6. Required Subscribe to events.
7. Required Verify event notifications.

Make your first call

To make REST API calls, create a PayPal REST app and get an access token:

1. Create a PayPal app.
When you create an app, PayPal generates a set of OAuth credentials.
2. Get an access token.
Pass the OAuth credentials in a get access token call.
In response, the PayPal authorization server issues an access token.
3. Make REST API calls.
Use the access token for authentication when you make REST API calls.

Create sandbox accounts

Create sandbox accounts:

  1. From the Developer Portal, click Log into Dashboard and enter your PayPal business account email and password.

    Note: If you do not have a business account, click Sign Up.
  2. Under Sandbox, click Accounts.

    Then, click Create Account.

  3. In the dialog box:

    1. Set Account Type to Business (Merchant Account).

    2. Enter an email address.

      Tip: You can use a fake or valid email address. If you use a valid address, you receive email notifications when you run test transactions.
    3. Enter a simple, easy-to-remember password, such as 12345678.

    4. Under PayPal Balance, enter a high amount. For example, 5000.

    5. Click Create Account.

  4. To create your customer sandbox account, repeat these steps but in step 3a, set Account Type to Personal (Buyer Account).

Configure a webhook listener

A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. After you configure a listener, note the URL for the listener.

Use this URL to:

  • Simulate mock webhook events to validate your listener configuration.
  • Subscribe your webhook listener to events.

Next, simulate mock webhook events to validate your listener configuration.

Simulate mock webhook events to validate your listener configuration

After you configure a listener, you can use a sample payload to simulate a webhook event. When you simulate an event, the simulator:

  • Validates that your listener can successfully receive event data without any connectivity issues.

  • Generates mock event data to show you how webhook events look.

    Note: The simulator generates mock events for demonstration purposes. You can view these events to see how events look. However, because these are mock events:

    • You cannot verify the simulator-generated events.
    • You cannot resend an event notification for a simulator-generated event.
    • You cannot show webhook details for a simulator-generated event.

After the simulator queues one or more mock events, your webhook listener URL can listen for HTTP POST notification messages. Each test event appears in your logs in the order that your listener receives them. The simulator sends mock static event data and event headers, which contain the PayPal-generated asymmetric signature and information that you can use to validate the signature.

To simulate a webhook event, use either:


Next, subscribe your listener to events.

Subscribe to events

To subscribe your webhook listener to events, use either the My Apps & Credentials dashboard or the Webhooks API.

To use the dashboard to subscribe to events

  1. Go to My Apps & Credentials. Click Log In.

  2. If you already have an app, proceed to the next step.

    Otherwise, click Create App to create an app. Note your client ID and secret. You need these values later.

  3. In the REST API apps section, click the link for the app to which you want to subscribe events.

  4. In the WEBHOOKS section, click Add Webhook.

  5. Add the URL for your listener, which is the endpoint URL that listens for incoming HTTP POST notification messages that are triggered when events occur.

  6. From the event types list, select the events to which to subscribe your app. You can select either all events or one or more individual events.

  7. Click Save. The dashboard shows your webhook listener URL, the ID for the webhook, and the events to which you subscribed your app.

    You can use this webhook ID to complete these Webhooks API operations:

Verify event notifications

You can verify webhook event notifications that your listener receives when events occur.

Note: You cannot verify the mock simulator-generated events.

When you verify events, you can list webhook events by app. You can filter this list by date range, resource, and event type. You can also show status and details for an event and resend an event notification.

To verify webhook event notifications, use one of these methods:

To use the dashboard to verify event notifications

  1. Depending on your environment, go to either the Live Webhooks Events dashboard or the Sandbox Webhooks Events dashboard.

  2. Click Log In.

  3. From the drop-down list, select the app for which to view webhook events.

  4. Optionally, you can filter the list of webhook events by:

    • Date range. The range must be in the last 30 days.

    • A resource. Specify the ID for a sale, authorization, or other resource.

    • An event. From the drop-down list, select either all events or one or more individual events.

    The dashboard shows events for the app, date range, resource, and event or events.

  5. You can complete these actions on the Webhooks Events page:

    • View the status for events. Received events show a green check mark and pending events show a yellow exclamation point.

    • Resend a notification. Click Resend next to any webhook event in the list.

    • Navigate the results pages. Click the arrows adjacent to the page number at the bottom of the page.

    • View event details. Click an event. Details include event ID, resource type, and summary.

Webhooks events for Marketplaces

When you send a transaction to PayPal for a seller who has not completed their account setup, the status of the transaction is set to pending. PayPal sends a PAYMENT.CAPTURE.PENDING webhook with the reason code seller_setup_pending.

Once the seller has completed PayPal account setup, PayPal sends these webhooks:

  • PAYMENT.CAPTURE.COMPLETED to indicate that the payment capture has changed from pending to completed.
  • MERCHANT.ONBOARDING.COMPLETED to indicate that the seller has completed account setup. You can subscribe to webhooks to be alerted when a seller's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the seller account is closed, or the account setup consents have been revoked.

For more information about these webhook events, see Webhook event names.

Feedback