The Payments Integration API enables third-party applications to retrieve authentication tokens after marketplace installation. These Auth Tokens can be exchanged for Access Tokens used in payment processing through the Shift4 i4go gateway. Receive real-time webhook notifications when auth tokens are created.

Getting started

The Payments Integration API is used after a merchant completes your marketplace app installation. You'll receive webhook notifications when Auth Tokens are created, then retrieve them via API. Auth Tokens are single-use and must be exchanged for Access Tokens before processing payments. All endpoints require HMAC-SHA256 authentication.

Core concepts

Auth Tokens

Auth Tokens are issued by the Lighthouse Transaction Manager (LTM) for a specific merchant and third-party integration combination after installation completes. Auth Tokens are single-use and have an expiration period. They must be retrieved via API and exchanged for Access Tokens.

Access Tokens

Access Tokens are obtained by exchanging Auth Tokens and are used for payment processing through the i4go gateway. Unlike Auth Tokens, Access Tokens do not expire (but can be revoked). Each Access Token is tied to specific interface versions and merchant-integration combinations.

Exchange Flow

The typical flow: (1) Marketplace installation completes → (2) Webhook notification sent → (3) Retrieve Auth Token via API → (4) Exchange Auth Token for Access Token via Lighthouse API → (5) Use Access Token for payment processing.

Webhook Subscriptions

Subscribe to the payments.AuthToken.created webhook event to receive real-time notifications when Auth Tokens are generated after installation. All webhook payloads require HMAC verification to ensure authenticity and prevent tampering.