Tag Archives: api

Webhooks for REST APIs launched

By

(By Joe Nash & Alberto López)


PayPal’s latest addition to the roster of products taking advantage of PayPal REST API technology gives developers easier access to notifications of payment activities, such as payment status updates. PayPal webhooks are now available, and not only do they enable similar functionality to that of the IPN available in the Classic APIs, but they provide additional functionality to ease development and create innovative new products.

What is a webhook?

When we discuss webhooks, we refer to three key actors:

  • Webhooks: A webhook takes the form of a POST request to a URL that you set via your PayPal account. When a payment is made, or the status of a payment changes, the POST request is triggered, sending an event. This allows you to see and work with payment updates in real time. Webhooks can be created, updated, listed and deleted all through your PayPal account.
  • Events: An event contains the details about the payment update, including: the time of payment authorization or the amount of a payment or refund. Past events are searchable, and can also be resent in a webhook. There are multiple event types.
  • Event types: Event types can be selected to only cause the triggering of webhooks for specific payment updates and information, allowing you to choose to receive POST requests about the information that is important to you and your product.

Through these three actors, developers can manage operations that happen during the transaction lifecycle. Developers can list all of the event types subscribed to by a given webhook, perform more focused searches such as searching for webhooks by event type, and the API itself can be used to retrieve webhook events.

What operations are available using webhooks?

Webhooks provide some interesting functions for developers:

What are the differences between Webhooks and IPN?

At first glance, the differences between Webhooks and IPN used in the Classic API are subtle. What makes webhooks desirable over IPN is their sheer customisability versus IPN:

  • Whilst IPN did allow for the configuration of different IPN listener’s for different transactions, the IPN listener had to be predefined in the PayPal account. Further, it could only be modified through the PayPal account, and by default all refunds notify to this listener. With Webhooks you will be able to create different webhooks via the API for managing different event types (an authorization created, or voided or refunded), and modify each of them using an API REST call.
  • Webhooks enable the retrieval via API of any webhook event that was unable to be collected in the initial triggering of the webhook. In contrast, IPN events were only accessible via the PayPal account.
  • Webhooks have the important property of real time event notification, whilst with IPN, some delays could be experienced.

It is clear that webhooks give distinct advantages versus IPN; they are more flexible, versatile and can be used in real time. Let’s see how they work.

How do Webhooks work?

To use the webhook API in the Sandbox, first do the following:

  1. Go to the My REST apps page.
  2. Create an application, if you haven’t done so already.
  3. Add a webhook URL (the maximum number of webhooks is 10).
  4. Subscribe to the event types of interest. As we said before, you can also choose to manage webhooks, events, and event types through the Webhooks API.

Getting the bearer token:

Request

curl https://api.sandbox.paypal.com/v1/oauth2/token
\ -H "Accept: application/json" 
\ -H "Accept-Language: en_US" 
\ -u "<Client-Id>:<Secret>" 
\ -d "grant_type=client_credentials”

Response

{ "scope": "https://api.paypal.com/v1/payments/.*
https://api.paypal.com/v1/vault/credit-card/
https://api.paypal.com/v1/vault/credit-card/.*",
"access_token": "EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBVTTTWxVvgmsG",
"token_type": "Bearer",
"app_id": "APP-6XR95014BA15863X",
"expires_in": 28800
}

Creating the webhook via API

Request

curl -v POST https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H 'Content-Type:application/json' \
-H 'Authorization: 
        Bearer EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBVTTTWxVvgmsG' \
-d '{
   "url": "http://www.yeowza.com/paypal_webhook",
   "event_types": [
       {
           "name": "PAYMENT.SALE.REFUNDED"
       },
       {
           "name": "PAYMENT.CAPTURE.REFUNDED"
       }
   ]
}'

Response

{
"id":"0E842532SB505363J",
"url":"https://www.mysite.com/paypal_webhook",
"event_types":[
    {
        "name":"PAYMENT.SALE.REFUNDED",
        "description":"A sale payment was refunded"
    },
    {
        "name":"PAYMENT.CAPTURE.REFUNDED",
        "description":"A capture payment was refunded"}
    ],
"links":[
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"SELF",
     "method":"GET"
    },
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"UPDATE",
     "method":"PATCH"
    },
    {
     "href": "https://api.sandbox.paypal.com/v1/notifications/
             webhooks/0E842532SB505363J",
     "rel":"DELETE",
     "method":"DELETE"
     }
]
}

After making a payment, you’ll receive in your webhook (https://www.mysite.com/paypal_webhook) an event type with the information of the event type:

{
 "id": "WH-0AF57170N8121644E-6VF27453LH2982421",
 "create_time": “2014-09-25T21:41:28Z",
 "resource_type": "authorization",
 "trigger_event": "PAYMENT.AUTHORIZATION.CREATED",
 "summary": "A payment authorization was created",
 "resource": {
   "id": "0MW879906U0874649",
   "create_time": "2014-09-25T21:39:15Z",
   "update_time": "2014-09-25T21:39:17Z",
   "state": "authorized",
   "amount": {
     "total": “10.00",
     "currency": "USD",
     "details": {
       "subtotal": “10.00"
     }
   },
   "parent_payment": "PAY-0AB48420EF007493KKQVUMBY",
   "valid_until": "2014-07-24T21:39:15Z",
   "links": [
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649",
       "rel": "self",
       "method": "GET"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649/capture",
       "rel": "capture",
       "method": "POST"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               authorization/0MW879906U0874649/void",
       "rel": "void",
       "method": "POST"
     },
     {
       "href": "https://api.sandbox.paypal.com/v1/payments/
               payment/PAY-0AB48420EF007493KKQVUMBY",
       "rel": "parent_payment",
       "method": "GET"
     }
   ]
 },
 "links": [
   {
     "href": "https://api.sandbox.paypal.com/v1/notfications/
             webhooks-events/WH-0AF57170N8121644E-6VF27453LH2982421",
     "rel": "self",
     "method": "GET"
   },
   {
     "href": "https://api.sandbox.paypal.com/v1/notfications/
             webhooks-events/WH-0AF57170N8121644E-6VF27453LH2982421/
             resend",
     "rel": "resend",
     "method": "POST"
   }
 ]}

In our webhook event, we get all of the information, coupled with useful links, given by the event type. From here, we can perform some operations on the data, update our databases, or launch a process after ensuring the process is done.

PayPal Here Sideloader API

By

ava_tim **Update:** Please check out our [updated documentation][1] for the PayPal Here Sideloader API!

As you might have seen on popular blogs like

TechCrunch we’ve recently launched a PayPal Here device for the UK which is capable of doing Chip & PIN. This allows merchants to accept Credit & Debit cards that can or may not be swiped. In our keynote Mobile Meets Retail at the Mobile World Congress our Director of Developer Network John Lunn and I’ve been introducing an awesome feature which is both supported for the US & UK / EMEA device: our Sideloader API. Basically this API allows developers to accept payments via cash, credit card, debit card, invoices and our checkin feature just by utilizing a very simple url scheme and our PayPal Here application for both Android and iOS.

How it works

Our application can be accessed by providing an encoded invoice & a callback URL which opens up your own application and returns transaction data.

paypalhere://takePayment?
acceped=cash,card,paypal // optional
&returnUrl=your app’s callback
&as=b64 // optional
&step=choosePayment
&payerPhone=the payer’s phone number // optional
&invoice=your invoice as JSON (encoded)

The callback URL has to be setup like this:

yourScheme://yourHost/?{result}
?Type={Type}
&InvoiceId={InvoiceId}
&Tip={Tip}
&Email={Email}
&TxId={TxId}

Finally your invoice has to be declared in this JSON format:

{
merchantEmail: "yourmail@merchant.com",
itemList: {
item: [
{
name: "Name",
description: "An item",
quantity: "2.0",
unitPrice: "10.0",
taxName: "Tax",
taxRate: "8.5"
}
]
},
currencyCode: "USD",
paymentTerms: "DueOnReceipt",
discountPercent: "0.0"
}

Samples

To help you with your integration we’ve developed three very simple samples that show how the integration actually works. While the

Android & iOS samples use native code to interact with our application the third sample presents a way that enables every website to utilize PayPal Here to accept payments on the go.

Engage with us

We’d be happy to see your feedback. If you experience any issues: File an

issue at our GitHub project. Having a great idea that helps to improve the samples? Open a pull request! Looking forward to seeing your integrations!