APIs

Stuff to cover

• What is an API?

• What is HTTP?

• What is REST mean and why is it good?

• How the connect flow works for a simple integration?

• How the connect flow works for a partner integration?

• How do webhooks work?

What is an API• Application Programming Interface

• A set of instructions for communicating with an application

• Normally refer to web based services but all sorts of software can have an API

• startToasting();

• “OK Begun Toasting”

• stopToasting();

• “OK Toasting ended”

• isToasting();

• TRUE

• FALSE

Dualit API v1

What is HTTP?• How we transfer Hypertext (i.e. HTML)

• Unencrypted unless using HTTPS

• Everything on GoCardless is forced over HTTPS by Google Chrome

• Information is transferred with a verb:

• HTTP verbs suggest context of actions

GET PUT

POST DELETE

Get Update Create Delete

HTTP VERBS (What they actually mean)

Demo

What is REST?• Representational state transfer

• Basically, a set of guidelines that together make an API that could be described as “RESTful”

• An API is RESTful if it:

• Uses standard HTTP verbs (PUT, GET, POST)

• Has one base URI (api.gocardless.com)

• Uses standard internet media JSON or XML

• Hypertext links to related resources

• REST v SOAP

• Has one base URI (gocardless.com)

• Uses standard internet media JSON or XML

• Uses standard HTTP methods (PUT, GET, POST)

• Hypertext links to related resources

API endpoint for creating a customer

What is SOAP?

• Simple Object Access Protocol

• XML messages, harder to process (and read) than JSON

• Security built in to SOAP messages, doesn’t rely on HTTPS

Why is REST good?

• Because it’s a standard, predictability of code writing speeds up development time

• Helps you organise a complex system into simple resources (Payment, Customer)

• Security is handled independently by transport layer (HTTPS)

• Simpler, more human readable than SOAP messages

• Something more dynamic than a paylink

• Imagine we’re a charity and want the user to type in the amount they wish to donate on our website

• We want to let them select a one off or recurring payment for an amount they choose

A simple integration

I wish to donate

£500|

Donate

Every month

Partner Connect Flow• Allow a partner to collect payments on behalf of their

merchants

• Examples: FreeAgent, Kashflow, Crowdfunding websites

Merchant

💼Partner

👤

FreeAgent (partner) wants to allow Jim’s Gym (merchant) to take payments through GoCardless

Merchant

💼Partner

👤

The merchant wants to be able to take payments through the partner

Merchant

💼Partner

👤

The partner redirects the merchant to GoCardless

Merchant

👤

The merchant needs to have an existing GoCardless account, or create a new one

GoCardless asks the merchant to authorise the partner access to their account

Merchant

👤

When the merchant authorises, GoCardless gives the partner a unique access token to store for future requests

💼Partner

NX8LSkRUIYVNZ1eFCBnh

It failed

NX8LSkRUIYVNZ1eFCBnh

payment: failed

💼👤

Now, when the partner needs information from GoCardless about the merchant account, they send the access token each time

Whats the payment status?

Partner flow demo

Webhooks• Notification of events pushed from GoCardless to a third

party web service

• Typically this will be payment failures, new customers etc

💼“Payment failed”

Webhooks• Webhooks allow us to instantly notify an API integration of an

event to do with their payments

• Merchants have to configure their app to “listen” to webhooks

Webhook demo

Questions?