Building a Custom Payment Provider Integration

Introduction

This guide explains how to build a custom payment provider integration that connects to the CRM's payment system. Once integrated, your payment solution can process one-time payments, subscriptions, store payment methods for future use, and handle refunds across all locations in your CRM account.

Key Concepts

Before beginning, understand these essential components:

• Marketplace App: The container for your integration that defines authentication, permissions, and configuration pages.
• Custom Payment Provider: The configuration that identifies your app as a payment processor and specifies supported payment types.
• Query URL: Your server endpoint that handles backend payment operations like verification, charging saved methods, and managing subscriptions.
• Payments URL: A public URL loaded in an iframe where customers enter payment details through your provider.
• Custom Page: A configuration interface where users set up API keys, merchant IDs, and test/live mode settings.

Prerequisites

You will need:

• A CRM account with access to the Marketplace dashboard
• A backend service (using any programming language) hosted on a cloud provider
• A public domain for OAuth redirects, configuration pages, webhooks, and payment iframes
• Familiarity with OAuth 2.0, JSON/HTTP APIs, and webhook handling

Integration Steps

Step 1: Create Your Marketplace App

Navigate to the Marketplace dashboard and create a new app. Configure the following sections:

• Settings: Define required OAuth scopes for payment and product access, set redirect URLs, and secure client keys.
• Payment Provider Configuration: Specify that your app is a payment provider and what payment types it supports.
• Profile: Set up your app's public branding and description.
• Custom Pages: Provide URLs for your configuration interface and payment collection iframe.

Step 2: Implement Authentication & Installation

Set up OAuth authentication to handle app installation at CRM locations. When users install your app, the CRM redirects to your specified URL with an authorization code that you exchange for an access token. Store this token securely for making API calls on behalf of the location.

Step 3: Configure Test and Live Modes

Each location can have separate test and live configurations for your payment provider. Test mode allows you to simulate payments without processing real transactions, while live mode processes actual payments.

Step 4: Implement Checkout Integration

Create the payments URL that will load in an iframe during checkout. Your implementation must handle several events:

• Ready Event: Signal when your payment iframe is loaded and prepared.
• Payment Initiation: Receive payment details and begin processing.
• Outcome Events: Communicate payment success, failure, or cancellation back to the CRM.
• Verification: Confirm payment status when requested by the CRM.

Step 5: Support Saved Payment Methods & Subscriptions

Implement functionality for storing payment methods (like credit cards on file) and managing subscriptions:

• Add Payment Method: Securely store customer payment information for future use.
• List Payment Methods: Return stored payment methods when requested.
• Charge Payment Method: Process payments using previously stored methods.
• Manual Subscriptions: Create, manage, and cancel recurring subscription plans using saved payment methods.

Step 6: Handle Refunds and Other Actions

Implement refund processing capability. When a refund is requested, your system should process it and confirm completion back to the CRM.

Step 7: Process Webhooks

Set up a webhook endpoint to receive notifications from the CRM about payment-related events. Your endpoint should handle various event types and process them according to your business logic.

Testing and Deployment

Thoroughly test your integration in both test and live modes before making it available to users. Ensure all payment scenarios work correctly, including successful payments, failures, refunds, and subscription management. Once testing is complete, your custom payment provider will be available in the Marketplace for CRM users to install and configure.