Set up webhooks for Orders API

Orders API integration note:
  • PayPal for Marketplaces is available to select partners for approved use cases. It is aimed at marketplaces, crowdfunding, and multi-party commerce platforms.
  • You can also use the Orders API with Express Checkout to give your buyers a simplified checkout experience.

The Marketplace APIs use webhooks for event notification. A webhook is an HTTP callback that receives notification messages for events.

To set up webhooks:

1. Required Configure a webhook listener, which is a server that listens for incoming notifications when events occur.
2. Required Register a listener.
3. Required Simulate mock events.
4. Required Subscribe your listener to specific events.

To configure a webhook listener

You can configure a webhook listener in multiple ways. For example, you can either:

After configuring the listener, make note of the URL. You need the URL to generate webhook events and to subscribe your webhook listener to events. For example, Runscope automatically creates a bucket for you to capture API traffic. You can create additional buckets as needed. A unique key identifies the bucket and comprises part of the URL for the server in the form: https:key.runscope.net, as in this example:

key:  2csibh7npjbu
URL:  https://2csibh7npjbu.runscope.net

The events of interest for these APIs are:

  • CHECKOUT.ORDER.PROCESSED. The order was accepted.
  • PAYMENT.CAPTURE.COMPLETED. Money was moved from buyer's account.
  • PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED. Funds were disbursed to seller and marketplace.
  • PAYMENT.CAPTURE.REFUNDED. Funds were refunded to the customer.
  • PAYMENT.CAPTURE.DENIED. PayPal declined the payment.

To register a listener

  1. In Postman, click the eye icon to open the environment editor, click Edit, and find webhook_url and paste the Runscope URL as its value.

  2. In the sidebar, click Webhooks > Register Webhook.

  3. Click Body and add the event types to listen for:

    {
      "url": "{{webhook_url}}",
      "event_types": [{
          "name": "CHECKOUT.ORDER.PROCESSED"
        },
        {
          "name": "PAYMENT.CAPTURE.COMPLETED"
        },
        {
          "name": "PAYMENT.CAPTURE.REFUNDED"
        },
        {
          "name": "PAYMENT.CAPTURE.DENIED"
        },
        {
          "name": "PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED"
        }
      ]
    }
    
  4. To execute the function, click Send.

    The function creates a webhook object and returns a response similar to the following:

    {
      "id": "5BT82451EH677124B",
      "url": "https://ymbx8b1gkius.runscope.net",
      "event_types": [{
          "name": "CHECKOUT.ORDER.PROCESSED",
          "description": "A checkout order was processed"
        },
        {
          "name": "PAYMENT.CAPTURE.COMPLETED",
          "description": "A capture payment was completed"
        },
        {
          "name": "PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED",
          "description": "Referenced payout amount disbursement completed"
        }
      ],
      "links": [{
          "href": "https://api.paypal.com/v1/notifications/webhooks/5BT82451EH677124B",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/5BT82451EH677124B",
          "rel": "update",
          "method": "PATCH"
        },
        {
          "href": "https://api.paypal.com/v1/notifications/webhooks/5BT82451EH677124B",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    }
    

Next, to verify that the webhook listener is working properly, you can generate a simulated webhook event and check for it on your listener server.

To simulate a webhook event

  1. In the Postman sidebar, click Webhooks > Simulate a webhook event.

  2. Click Send to call /notifications/simulate-event.

    The function sends a simulated webhook event (PAYMENT.CAPTURED.COMPLETED) to the webhook URL that you registered:

    {
      "url": "https://ymbx8b1gkius.runscope.net",
      "event_type": "PAYMENT.CAPTURE.COMPLETED"
    } "https://api.paypal.com/v1/notifications/simulate-event"
    

    Response:

    {
      "id": "WH-7Y7254563A4550640-11V2185806837105M",
      "create_time": "2015-02-17T18:51:33Z",
      "resource_type": "capture",
      "event_type": "PAYMENT.CAPTURE.COMPLETED",
      "summary": "Payment completed for $ 7.47 USD",
      "resource": { 
        "amount": {
          "total": "7.47",
        "currency": "USD"
        },
        "id": "42311647XV020574X",
        "parent_payment": "PAY-3YE025760C441402AKTRY2PQ",
        "update_time": "2015-02-17T18:50:45Z",
        "state": "completed",
        "create_time": "2015-02-17T18:50:44Z",
      .
      .
      .
    }
    
  3. On your listener, you should see a matching event; for example:

    Paypal-Transmission-Time: 2016-11-30T23:54:10Z
    User-Agent: PayPal/AUHD-209.0-26789171
    
    BODY  
      {
        "id": "WH-7Y7254563A4550640-11V2185806837105M",
        "event_version": "1.0",
        "create_time": "2015-02-17T18:51:33Z",
        "resource_type": "capture",
        "event_type": "PAYMENT.CAPTURE.COMPLETED",
        "summary": "Payment completed for $ 7.47 USD",
        "resource": {
          "id": "42311647XV020574X",
          "create_time": "2015-02-17T18:50:44Z",
          "update_time": "2015-02-17T18:50:45Z",
          "amount": {
            "total": "7.47",
            "currency": "USD"
          },
          "state": "completed",
          "parent_payment": "PAY-3YE025760C441402AKTRY2PQ",
        .
        .
        .
      }
    

Note: The WH-7Y7254563A4550640-11V2185806837105M webhook ID in the function response matches the ID in the listener.

To subscribe your listener to events

The events of interest for this API are:

  • CHECKOUT.ORDER.PROCESSED. PayPal accepted the order.
  • PAYMENT.CAPTURE.COMPLETED. Money was moved from the customer's account.
  • PAYMENT.REFERENCED-PAYOUT-ITEM.COMPLETED. Funds were disbursed to the merchant and partner.
  • PAYMENT.CAPTURE.REFUNDED. Funds were disbursed to the merchant and partner.
  • PAYMENT.CAPTURE.DENIED. PayPal declined the payment.

The webhook listener is now ready to use with the Orders API.

Additional information