Merchant Setup Integration Guide

1. Ensure the instance exists via the capabilities API, this will also let you know if you're ready to process payments
2. Create a deep link via the deep link creation API, this will return you an ID
3. Embed the deep link into your platform, using our Web SDK
4. (optionally) Handle events via our browser events API
5. (serverside) Handle webhooks, so you know when a merchant becomes able to take payments

Instance Capabilities

Please see: Validate Capabilities API

If the instance does not exist, you can create it via the Instance Creation API

Deep Link Creation

Please see: Deep Link Creation API

Page Embedding

Please see: Page Embedding

Handling Events

Please see: Browser Events

Handling Webhooks

The browser events tell you what is happening on the screen. The webhooks tell you what the merchant has actually done, and they arrive whether or not anybody still has the page open — which matters here, because a merchant can walk away mid-connection, finish an OAuth login in another window, or come back to it days later.

The one most platforms act on is a merchant becoming able to take payments:

• GATEWAY.CREATED: a processor has been connected. This is the signal that a merchant who could not previously be charged now can.
• GATEWAY.UPDATE: a connected processor's settings changed — which currencies and payment methods it is enabled for, or a reconnection. Note a save that changes nothing raises nothing.
• GATEWAY.ARCHIVE: a processor has been disconnected. Sent with GATEWAY.UPDATE.

Routing changes alongside them, when a merchant directs a payment method to a particular processor or sets an amount rule:

• LEGAL_ENTITY_ROUTE.CREATED, LEGAL_ENTITY_ROUTE.UPDATE and LEGAL_ENTITY_ROUTE.ARCHIVE. Connecting a processor raises a CREATED for each route it creates; disconnecting one archives its routes.

And the instance itself:

• INSTANCE.UPDATE: raised when a merchant accepts the terms, and on any other instance change. It fires on every successful call, including one that re-sends values already stored, so treat it as "something was saved" rather than "something changed".

One thing not to wait for: a fraud workflow raises no webhook at all — not when connected, updated, archived or restored. There is no WORKFLOW.* event to subscribe to; a workflow is stored on the same route as a gateway but the events are raised for gateways only. If you need to know a merchant has connected a fraud tool, read it rather than listening for it.

Please see the Webhooks reference for the payload of each, and Business Rules for exactly what raises them.