Only this pageAll pages
Powered by GitBook
Couldn't generate the PDF for 240 pages, generation stopped at 100.
Extend with 50 more pages.
1 of 100

Clearent Dev Center - Prod

Getting Started

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Developer Resources

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Merchant Onboarding

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Payment Processing Solutions

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Dejavoo

We offer Dejavoo terminals designed for seamless and secure payment acceptance. Our Z Line Series features reliable countertop and PIN pad devices for efficient transactions. The QD Line Series, powered by Android, boasts high-definition touchscreens, robust processors, and versatile connectivity options to enhance the payment experience.

Dejavoo Z Line

Dejavoo Z6

The Dejavoo Z6 is a secure and efficient PIN pad terminal in the Dejavoo Z Line, designed for seamless payment processing. Its compact design suits various retail environments, while advanced security, versatile connectivity, and a user-friendly interface make it a reliable choice for businesses.

Features
Integration Type
Communication Options
  • Accepts EMV chip cards, magnetic stripe cards, and contactless payments

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Ethernet

  • USB

Additional Resources:


Dejavoo Z8

The Dejavoo Z8 is a compact, countertop payment terminal designed for small to medium-sized businesses. It combines advanced functionality with user-friendly features to streamline payment processing. Ideal for retail, restaurants, and service industries that need fast, secure, and versatile payment processing.

Features
Integration Type
Communication Options
  • Accepts EMV chip cards, magnetic stripe cards, and contactless payments

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Countertop

  • Ethernet

  • Wi-Fi

Additional Resources:


Dejavoo Z9

The Dejavoo Z9 is a highly adaptable and durable wireless POS terminal, perfect for mobile payments. Its versatility makes it an excellent choice for a wide range of business environments, including restaurants, retail stores, and mobile services.

Features
Integration Type
Communication Options
  • Accepts EMV chip cards, magnetic stripe cards, and contactless payments

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Wireless

  • Ethernet

  • Wi-Fi

  • GPR

Additional Resources:


Dejavoo Z11

The Dejavoo Z11 is a compact and advanced countertop touch-screen POS terminal. It is designed to handle a variety of payment methods and is ideal for businesses looking for a reliable and versatile payment solution.

Features
Integration Type
Communication Options
  • Accepts EMV chip cards, magnetic stripe cards, and contactless payments

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Countertop

  • Ethernet

  • Wi-Fi

Additional Resources:


Dejavoo QD Line

The QD Line offers Android-based terminals with high-definition touchscreens, robust processors, and versatile connectivity options, ensuring efficient and secure payment processing

Dejavoo QD2

The Dejavoo QD2 is a compact, high-performance Android PIN Pad designed to complement POS terminals for businesses that require secure, customer-facing payment options. Perfect for businesses needing an economical, compact, and secure PIN pad for basic transactions.

Features
Integration Type
Communication Options
  • Supports EMV chip cards, magnetic stripe cards, and NFC contactless payments

  • Internal PIN Pad and contactless

  • Large touch screen

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Wireless

  • GPRS

  • Wi-Fi

Additional Resources:


Dejavoo QD4

The Dejavoo QD4 is a countertop Android POS terminal designed to provide secure and efficient payment processing for businesses. The terminal supports multiple connectivity options providing flexibility for various business setups.

Features
Integration Type
Communication Options
  • Supports EMV chip cards, magnetic stripe cards, and NFC contactless payments

  • Large touch screen

  • Supports external PIN Pad (QD3 PIN Pad)

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Ethernet

  • Wi-Fi

Additional Resources:


Dejavoo QD3

The Dejavoo QD3 is a compact Android PIN pad terminal designed for secure and efficient payment processing. It seamlessly integrates with the QD4 terminal via a USB-to-USB (U-U) cable, ensuring a smooth and reliable connection.

Features
Integration Type
Communication Options
  • Accepts EMV chip cards, magnetic stripe cards, and NFC contactless payments

  • Internal PIN Pad and contactless

  • Large touch screen

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with the QD4 terminal via a USB-to-USB (U-U) cable

  • Ethernet

  • Wi-Fi

  • Bluetooth 4.0

Additional Resources:

Essential Technical Specification
Essential Technical Specification
EMV Quick Reference Guide: Retail/Restaurant
Essential Technical Specification
EMV Quick Reference Guide: Retail/Restaurant
Essential Technical Specification
Getting Started with the QD2 & QD4
Essential Technical Specification
Getting Started with the QD2 & QD4
Essential Technical Specification
Essential Technical Specification

Integration Process

Integrating with our platform is a structured, phased journey designed to ensure a seamless experience from planning to production launch. The process is divided into four key phases, each focused on guiding you through specific integration aspects with the support of our dedicated teams.

Integration Journey

By following this structured integration process, you benefit from expert guidance, thorough testing, and comprehensive support at every step. This approach minimizes risks and streamlines your transition, allowing you to quickly go live and start confidently onboarding merchants and processing payments.

Phase 1: Discovery

The Discovery phase is about laying the foundation for a successful integration by understanding your business needs and defining a tailored plan.

  • Requirements Gathering Our Solutions Engineering (SE) team collaborates closely with you to gather critical details about your business, including its size, type, and unique payment processing needs. This consultation helps us recommend the best-suited set of integrated solutions to meet your specific requirements.

  • Payment Processing Design (PPD) Once the scope of the integration project is agreed upon, the SE team will deliver a comprehensive Payment Processing Design (PPD) document. This document outlines your integration profile, covering business details, technology requirements, existing challenges, and overall project goals. Reviewing the PPD serves as a critical checkpoint before moving forward, minimizing risks and ensuring alignment.

Phase 2: Pre-Integration

During the Pre-Integration phase, we set up the necessary tools and complete essential checks to prepare you for the integration.

  • Background Check and Underwriting We conduct a background check and underwriting review to assess your eligibility and compliance. This involves submitting required documents such as a W-9 form and either a voided check or a bank letter (DDA).

  • Project Initiation A dedicated Project Manager is assigned to guide you through the process, acting as your primary point of contact and connecting you with subject-matter experts.

  • Test Kit Setup We provide a Sandbox Environment along with any necessary test equipment (e.g., terminals) and create certification test scripts for you. Our team supports your development and testing efforts, answering any questions throughout this phase.

Phase 3: Integration

The Integration phase focuses on development, testing, and obtaining certification for your payment solution.

  • Integration Support Our integration support team offers hands-on assistance throughout your testing and certification journey. They work closely with you to resolve issues and ensure your integration is on track for a smooth transition to production.

  • Certification Testing Before moving to production, your integration must undergo certification testing. This involves the following steps:

    • Preparation: We provide guidance, documentation, and knowledge base resources to help you understand the certification requirements.

    • Self-Testing: You build your integration and conduct self-testing in the Sandbox environment. You perform various test transactions (e.g., successful payments, authorization declines, refunds, etc.) and document details using Clearent's Certification Guide.

    • Certification Validation: Our team reviews your self-test results and validates the final set of test transactions with you on a shared Teams call. Upon successful validation, you will receive a Certification Letter, granting you access to production credentials and enabling your application to onboard merchants and process payments in the production environment.

Phase 4 - Launch

The final phase is the transition to production. Once your integration is certified and code-complete, you can smoothly migrate from the Sandbox environment to our live production environment. This step enables you to deploy your integration securely and begin processing real-world payments, ensuring reliability and compliance from day one.

Welcome

Welcome to our Developer Center. Explore our products, guides, resources, and references for integrating payments with us.


Our Solutions


Our Layered Approach to Security

PCI Compliance

Our solutions are built to support seamless PCI compliance, protecting cardholder data across online, in-store, and mobile transactions. We help businesses meet regulatory requirements effortlessly while maintaining the highest security standards.

Tokenization

Our tokenization technology enhances security by replacing sensitive cardholder data with unique, non-sensitive tokens. This approach significantly reduces the risk of data breaches and unauthorized exposure while also simplifying compliance with industry security standards.

Encryption

We secure payment data with advanced encryption methods, ensuring protection from the moment a transaction begins to its final storage. Our end-to-end encryption safeguards sensitive information across all payment channels. This includes PCI-Validated Point-to-Point Encryption (P2PE), which creates a secure cryptographic tunnel from the point of interaction to our decryption environment. This approach reduces PCI DSS scope, lowers the risk of data breaches, and provides a high level of independently verified security.

PAX

We offer a range of advanced payment PAX Technology terminals designed to meet diverse business needs. Below is an overview of three notable PAX models of A Series: the A35, A80, and A920Pro.

PAX A Series

PAX A35

The PAX A35 is a high-performance, smart device tailored for various retail scenarios. Its ergonomic design and advanced features make it suitable for high-volume, fast-paced environments.

Features
Integration Type
Communication Options
  • Smart Android PIN Pad Designed for Multilane Implementations Accepts Contactless, Chip, Magstripe

  • Power Over Ethernet (POE)

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Clearent’s Cloud EMV

  • Semi-integration to Clearent’s Quest™ Gateway API

  • Ethernet

  • WiFi

Additional Resources:


PAX A80

The PAX A80 is a reliable countertop device that can also function as an indoor portable terminal. Its robust design and comprehensive features make it a reliable choice for businesses seeking efficiency and security.

Features
Integration Type
Communication Options
  • Smart Android Terminal Accepts Contactless, Chip, Magstripe

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • Ethernet

  • Wi-Fi

Additional Resources:


PAX A920Pro

The PAX A920Pro is a mobile touchscreen Android terminal that combines the features of an Android tablet with a powerful payment terminal. Its sleek and compact design makes it ideal for dynamic retail or hospitality environments.

Features
Integration Type
Communication Options
  • Smart and Wireless Android Terminal Accepts Contactless, Chip, Magstripe

  • Large HD screen

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Compatible with Clearent's Cloud EMV

  • WiFi

  • Wireless

  • GPRS

  • Bluetooth

Additional Resources:

Devices

We offer a range of payment terminals for different business environments. Choose from countertop models, PIN pads, mobile terminals, or compact card readers. Each device supports EMV chip, magnetic stripe, and NFC contactless payments for fast and secure transactions. With end-to-end or point-to-point encryption and EMV certification, they ensure compliance and data protection.

DEJAVOO

Dejavoo Z Line

Device Appearance
Model
Description

Secure and compact PIN pad with advanced security, versatile connectivity, and a user-friendly design for seamless payments.

Countertop terminal providing secure and efficient transactions, ideal for retail, restaurants, and service industries.

Durable wireless terminal for mobile payments, suitable for retail, hospitality, and mobile services.

Compact countertop terminal with a touchscreen interface.

Dejavoo QD Line

Device Appearance
Model
Description

Android-based mobile wireless PIN pad for flexible, on-the-go payments.

Android-based countertop terminal for businesses needing a stationary POS solution.

Compact Android-based mobile PIN pad that integrates with the QD4 terminal via USB.


PAX

PAX A Series

Device Appearance
Model
Description

High-performance Android Smart PIN pad for various retail scenarios.

Countertop device that also functions as a portable indoor terminal.

Mobile touchscreen Android terminal combining an Android tablet with a powerful payment processor.


ID TECH

Device Appearance
Model
Description

Countertop payment reader supporting EMV chip, magnetic stripe, and NFC contactless payments.

Compact, versatile payment reader that accepts multiple payment methods, including Apple Pay and Google Pay.

Our Products

Explore our suite of products designed to meet diverse business needs, from seamless onboarding to powerful payment processing solutions.


Merchant Onboarding

Easily onboard merchants with flexible options.


Payment Processing

Support various business models and payment methods, including card-present, card-not-present, and ACH transactions.


Financial Management

Optimize business finances with tools for transparency, control, and efficiency.


Reporting & Maintenance

Gain data insights and manage issues efficiently.


Partner & Merchant Solutions

Empower partners and merchants with tools to streamline management and track performance.


Security

Our multi-layered security approach helps businesses maintain trust and protect sensitive information at every stage of the payment process.


ID TECH

We offer versatile and secure payment readers designed for businesses that require reliable, multi-interface transaction solutions. Below is an overview of two ID TECH models: VP8300 and VP3300.

ID TECH VP8300 READER

The ID TECH VP8300 is a secure, all-in-one countertop card reader designed for retail, hospitality, and other merchant environments.

Features
Integration Type
Communication Options
  • Accepts Contactless, Chip, Magstripe

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Javascript SDK

  • Quest™ Mobile Payments API

  • Countertop

  • USB

Additional Resources:


ID TECH VP3300 READER

The ID TECH VP3300 is a compact, versatile payment reader designed to accept multiple payment methods, including magnetic stripe (MagStripe), EMV chip cards, and NFC/contactless transactions such as Apple Pay and Google Pay.

Features
Integration Type
Communication Options
  • Accepts EMV Chip, Magstripe, Contactless including Apple Pay and Google Pay

  • Utilizes Quest™ PCI-Validated P2PE for secure transactions

  • Mobile SDK

  • Quest™ Mobile Payments API

  • Audio jack

  • Bluetooth

Additional Resources:

Overview

This section provides key resources to help you connect and test your integration with our platform:

Test your integration in a controlled environment, simulate transactions with test cards and ACH accounts, and review API responses, error messages, and validation results. Explore the API catalog to find the endpoints you need, and configure webhooks to receive notifications about key events.

For more information, refer to the following articles:

Testing Integration

The following articles provide the information to help you with your integration testing in the Sandbox environment:

Explore our designed to help you integrate, grow, and scale your business with ease. Whether you are a software provider or a merchant, our solutions empower you to accept and manage payments seamlessly while maintaining compliance and security.

Securing your business and customer data is our top priority. Our protects transactions from evolving threats while ensuring compliance with industry standards.

suite of cutting-edge solutions
multi-layered security approach
PAX A Series Quick Reference Guide for Integrated Devices (PAX A80, PAX A920, & PAX A35)
Essential Technical Specification
PAX A Series Quick Reference Guide for Integrated Devices (PAX A80, PAX A920, & PAX A35)
PAX A Series Quick Reference Guide (PAX A920 & PAX A80)
SwipeSimple PAX A80 Activation Guide
Essential Technical Specification
PAX A Series Quick Reference Guide for Integrated Devices (PAX A80, PAX A920, & PAX A35)
PAX A Series Quick Reference Guide (PAX A920 & PAX A80)
SwipeSimple PAX A920 Activation Guide
Essential Technical Specification
Quick Reference Guide - ID TECH VP8300
Essential Technical Specification
Quick Reference Guide - ID TECH VP3300
Essential Technical Specification
Sandbox and Production Environments
Testing Your Integration
API Catalog
Webhooks
Test Cards & ACH Accounts
Onboarding API Result Codes
Transaction Error Generation Data
Card Response & Result Codes
ACH Request Validation & Return Codes

Card Error Response Codes

You can test specific response codes with a test transaction when you use the test card and predetermined transaction amounts listed below.

Value
HTTP Status Code
Message
Amount

000

200

Approve

0.49, 0.80, 0.81, 0.82

003

402

Declined by Issuer – Card expired

0.29

004

402

Card Expired

0.05, 0.04

006

402

Allowable Pin Entries Exceeded

0.40

007

402

Declined by Issuer – Referred – Please call Card Issuer

0.01, 0.02

008

402

Declined by Issuer – Invalid Amount

0.11, 0.32

009

400

Invalid Card Number

0.14

010

402

Declined by Issuer – Account not found

0.36, 0.37, 0.38

011

400

Invalid Request

0.31, 0.35, 0.39

012

402

Not Sufficient Funds

0.21

014

402

Declined by Issuer – Exceeds amount limit

0.23, 0.70

015

402

Declined by Issuer – Transaction not permitted

0.43, 0.44

016

402

Declined by Issuer – Frequency limit exceeded

0.22, 0.25, 0.71

018

400

Invalid Pin

0.12, 0.13, 0.47

021

402

Declined by Issuer – Invalid card security code

0.48

022

400

Cashback Amount Exceeded

0.16

023

402

Transaction Declined By Issuer

0.04, 0.09, 0.15, 0.17, 51.00

024

402

Previously Reversed

0.1

027

402

Original Not Found

0.34

030

402

Invalid merchant ID – Please call Customer Support

0.46

031

402

Transaction Did Not Complete Normally, Please Retry

0.03

032

402

Duplicate Transaction

0.54

034

402

Card Lost

0.07

035

402

Card Stolen

0.08

037

200

Advice Accepted, No Action Taken

0.33

041

400

Field Validation

$0.00

000

200

This amount will trigger the sale to take over 60 seconds to process. Used to test timeout scenarios.- Only for Mobile Gateway

$999.00

000

200

This amount will trigger the sale to take over 60 seconds to process. Used to test timeout scenarios.- Only for transaction EMV

$1,000.00

CSC Response Codes

Card Security Code (CSC) is a security feature that protects against fraud. It ensures that credit card transactions can't be made without it being in the cardholder's possession.

Response Code
Message

M

The CSC matches the issuing bank’s records

N

The CSC does not match the issuing bank’s records

P

The CSC was not processed

S

The card should have a CSC, but merchant indicated it was not present

U

Card issuing bank does not participate

X

Unknown / No response

AVS Response Codes

Address Verification Service (AVS) is a fraud-prevention service that determines the match of a cardholder's address. AVS responses help you determine if a transaction is valid in card-not-present environments.

Response Code
Message

X

Match of address and 9-digit zip code

Y

Match of address and 5-digit zip code

W

Match of 9-digit zip code; address does not match

Z

Match of 5-digit zip code; address does not match

A

Address: Address Matches ZIP Does Not Match

N

No: Address and ZIP Do Not Match

G

Address information not verified

S

Service Not Supported: Issuer does not support address verification

U

Address information is unavailable

E

Error: Transaction ineligible for address verification

R

Retry: System Unavailable or Timeout

Card Transaction Result Codes

Transaction result codes help identify a transaction's status. When a transaction is unsuccessful, the result code indicates the problem so you know how to correct it.

Note: Transaction result codes may differ for different API endpoints and may have more than one message available.

Value
HTTP Status Code
Message

000

200

SUCCESS

001

400

Could not communicate with Terminal

001

404

Signature not found

002

500

Failed to process batch

002

402

Force Approval

002

400

Validation error

003

500

Failed to process batch

003

500

Declined by Issuer – Card expired

003

400

transaction-id required

005

402

Card Suspended

013

402

Transaction Not Permitted To Cardholder

017

402

Card Not Active

019

500

PIN Key sync error – Please call Customer Support

020

400

Invalid Currency

025

402

Exceeds Maximum Refundable Amount

026

402

Declined by Issuer – Invalid Card Number

028

402

Invalid Terminal – Please call Customer Support

029

402

Inactive Terminal

033

402

Capture Card, Please Call Processor

036

200

Advice Accepted

038

402

Reconciled, In Balance

039

402

Not Reconciled, Totals Provided

040

402

No Opened Batch

041

400

Field Validation

042

401

Unauthorized

043

400

Amount Minimum

044

400

Amount Maximum

045

402

Duplicate Transaction

046

402

Avs Response Not Accepted

047

402

Csc Response Not Accepted

048

402

Csc Response Not Accepted

049

500

No Response From Server

050

500

Internal Error

051

500

Could Not Connect

052

500

Exception Condition Contact Support

053

500

Exception Condition Contact Support

054

402

Data Element Error

055

500

Acquirer Not Supported By Switch

056

402

Transaction Destination Cannot Be Found

057

402

Card Issuer Timed Out

058

402

Card Issuer Unavailable

059

402

Duplicate Transmission

060

500

System Error, Database

061

402

Aborted, Threshold Exceeded

062

500

System misconfiguration: {MAY INCLUDE ADDITIONAL ERROR TEXT}

063

500

System Error, Transaction

064

500

System Error, Hsm

065

500

Configuration Error, Invalid Terminal

066

500

Configuration Error, Invalid Terminal

067

500

Configuration Error, Configuration Error

067

500

Configuration error, invalid merchant

068

500

Configuration Error, Configuration Error

068

500

Configuration error, inactive merchant

069

500

Configuration Error, Configuration Error

069

500

Configuration error, invalid store

070

500

Configuration error, inactive store

070

500

Configuration Error, System Error

071

500

System Error, Other

072

500

System Error Other

073

500

System Error Other

074

400

HPP Generic Error Message; query transaction for error details.

074

400

Invalid Request

074

400

Merchant-id from request does not match merchant-id of initial transaction

081

400

Create entity failed

081

400

Update entity failed

081

500

Update failed

082

400

Add entity failed

082

500

Add failed

082

404

Device not found

082

404

Entity not found

082

500

Get failed

083

400

Get entity failed

083

500

Get failed

083

400

Resource not found

084

500

Add Token To Customer Failed

084

400

Apikey on device does not belong to the terminal you have authenticated. Please check that the device was configured correctly

085

404

Unable to delete setting

085

400

Valid Content-Type Header Required for PUT or POST

086

400

Missing or Invalid Accept Type Header. Accept Type Header must be of type ‘application/json or ‘application/xml

087

400

Metadata can only have a maximum of ten key/value pairs

088

400

No body in request

089

200

Delete Successful

089

500

Error Deleting resource

089

400

Unable to delete Customer token

090

400

Required request body content is missing

090

400

Required request body content is missing, malformed, or datatype usage (ex- boolean, number) is invalid

091

402

Delete Token Failed. Token Associated With Payment Plan

091

204

No batch found to process

091

404

Object not found

091

404

Transaction not found

092

405

Http Method not supported

092

404

URL Parameter Invalid not found

093

400

Customer Delete Failed – Customer has active plans

093

400

Merchant Opt Out Delete Failed

094

400

Cannot delete Plan that has been used to charge the customer

280

400

Transaction failed

281

400

Void failed. Cannot void ach transactions that are returned or settled.

282

400

Authorization failed

283

400

Validation failed

284

400

ACH Account not found

285

400

Cannot process request. Contact Clearent for assistance

286

400

An error occurred we did not account for with Drools rules or otherwise

287

404

Transaction not found

288

400

Request failed

289

400

Provider failed

290

500

Transaction Failed

291

400

Cannot process request. Contact Clearent for assistance

292

404

Transaction not found

293

404

Transaction not found

294

500

Cannot process request. Contact Clearent for assistance

295

500

Cannot process request. Contact Clearent for assistance

880

400

Error parsing request

880

400

Error while submitting request to pax terminal

880

400

Failed to process hpp request.

880

400

Transaction failed

880

500

Unexpected Error – please contact customer support

881

400

Device communications unsupported

881

400

Manufacturer unsupported

882

400

Transaction type unsupported for this manufacturer

883

500

Terminal not connected

884

400

Terminal cannot be determined. Configure from Virtual Terminal Settings

884

400

Terminal cannot be determined. Confirm terminal is configured for Semi-Integrated mode

885

400

Device disabled

886

400

Failed to connect to Clearent Gateway. Please check device configuration

886

400

Terminal connection error

887

400

Transaction failed

888

400

Failed to serialize request as xml

889

400

Token only request failed

889

400

Transaction failed

890

400

Transaction endpoint does not match transaction type

8801

402

Could not determine if transaction succeeded or failed

8831

500

Terminal is busy. Check terminal and try again

13005

400

Signature not valid for HPP response

Z6
Z8
Z9
Z11
QD2
QD4
QD3
A35
A80
A920Pro
VP8300
VP3300

Product Guides

Learn about our products, features and integration capabilities.

Integration Guides

Review resources to get started building your integration.

API References

Explore APIs to integrate seamlessly into our platforms.

Automated Merchant Onboarding

A prebuilt, white-label solution for quick deployment.

Merchant Onboarding via Partner Portal

A manual submission option for a simplified onboarding process.

Merchant Onboarding via API

Direct integration for a fully customizable onboarding experience.

Online

Enable online transactions with tools such as a JavaScript SDK, a customizable Hosted Payment Page, and Text-to-Pay for SMS-based payments.

In-Person

Accept face-to-face payments while simplifying compliance requirements through Cloud EMV or JavaScript SDK (USB).

On the Go

Use mobile SDKs to embed secure payment processing in iOS and Android applications.

Recurring / Subscription

Set up and manage recurring payment schedules across various payment methods.

Merchant Pricing

Clear fees and cost structures for transaction processing.

Merchant Billing & Funding

Reliable settlements with flexible payout schedules to support cash flow.

Financial Reporting

Access financial statements and tax reports via email, portal, or API. Retrieve annual tax documents seamlessly.

Dispute Management

Reduce chargeback impact with tools that provide visibility, insights, and resolution support.

Reporting

Retrieve reports on transactions, settlements, chargebacks, and more to support informed decision-making.

Support Ticketing

Manage support requests, track progress, and maintain clear communication.

Partner Portal

Manage merchant portfolios, access data insights, track performance, and use intuitive dashboards with detailed reporting.

Merchant Portal

Oversee operations, monitor payments, view transactions, resolve disputes, download statements and tax forms, and track funding.

PCI Compliance

Meet PCI DSS requirements to reduce fraud risks and safeguard businesses and customers from data breaches.

Tokenization

Replace sensitive card and bank data with tokens to secure stored information and reduce unauthorized access risks.

Encryption

Protect card data in transit with Point-to-Point Encryption (P2PE) for secure processing.

Card Response & Result Codes

The following articles explain card responses and result codes used for testing purposes:

Transaction Error Generation Data

The table below helps you simulate various error responses by using specific transaction amounts. This allows you to verify how your integration handles different error scenarios before going live.

Note: Codes may vary depending on the API endpoint. Some response codes may also have more than one associated message, as shown below.

Sandbox & Production Environments

Our integration platform provides separate sandbox and production environments, creating a reliable and secure foundation for testing and deploying your solutions. The sandbox environment is designed to closely replicate production conditions, allowing you to thoroughly test and refine your integrations before transitioning to the live production environment.

Environment URLs

Use the following sandbox and production URLs to connect to their respective services.

Sandbox URLs

The following table provides the sandbox URLs for different services:

Coming Soon: We are developing an enhanced Integration (INT) environment that will replace the current sandbox. This new environment will more precisely mirror production conditions and provide expanded testing capabilities, further improving the developer experience.

Production URLs

The following table provides the production URLs for different services:

Go-Live Checklist

Ensure the following items are completed before transitioning to production:

1

Certification testing completed

2

Sandbox URLs updated to production URLs

Update all API calls to use production URLs by removing -sb from your sandbox endpoints and src in your code.

3

Sandbox API keys replaced with production API keys

Sandbox keys will not work in production. Production API keys will be sent either to:

  • The email address you provided, or

  • A webhook URL you specify for your newly onboarded merchants

Your integration won’t begin hitting the production environment until both the API URLs are updated and the production API keys are being used.

4

Additional operational go-live details reviewed

Confirm all operational readiness steps, including:

  • Terminal deployment settings

  • Support and escalation procedures

  • Internal team availability to support your merchants at launch

Value
HTTP Status Code
HTTP Status Code
Amount
Service
URL
Service
URL

Your integration must pass the required certification process before moving to production. For details, refer to the article.

Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Learn More
Card Error Response Codes
Card Transaction Result Codes
Card security code (CSC)
Address Verification Service (AVS)
Duplicate Transaction Settings

000

200

Approved

0.49, 0.80, 0.81, 0.82

000

200

SUCCESS

0.49, 0.80, 0.81, 0.82

001

400

Could not communicate with Terminal

001

404

Signature not found

002

500

Failed to process batch

002

402

Force Approval

002

400

Validation error

003

402

Declined by Issuer – Card expired

0.29

003

500

Failed to process batch

0.29

003

400

transaction-id required

004

402

Card Expired

0.05, 0.04

005

402

Card Suspended

006

402

Allowable Pin Entries Exceeded

0.40

007

402

Declined by Issuer – Referred – Please call Card Issuer

0.01, 0.02

008

402

Declined by Issuer – Invalid Amount

0.11, 0.32

009

400

Invalid Card Number

0.14

010

402

Declined by Issuer – Account not found

0.36, 0.37, 0.38

011

400

Invalid Request

0.31, 0.35, 0.39

012

402

Not Sufficient Funds

0.21

013

402

Transaction Not Permitted To Cardholder

014

402

Declined by Issuer – Exceeds amount limit

0.23

015

402

Declined by Issuer – Transaction not permitted

0.43, 0.44

016

402

Declined by Issuer – Frequency limit exceeded

0.22, 0.25, 0.71

017

402

Card Not Active

018

400

Invalid Pin

0.12, 0.13, 0.47

019

500

PIN Key sync error – Please call Customer Support

020

400

Invalid Currency

021

402

Declined by Issuer – Invalid card security code

0.48

022

400

Cashback Amount Exceeded

0.16

023

402

Transaction Declined By Issuer

0.04, 0.09, 0.15, 0.17

024

402

Previously Reversed

0.10

025

402

Exceeds Maximum Refundable Amount

026

402

Declined by Issuer – Invalid Card Number

027

402

Original Not Found

0.34

028

402

Invalid Terminal – Please call Customer Support

029

402

Inactive Terminal

030

402

Invalid merchant ID – Please call Customer Support

0.46

031

402

Transaction Did Not Complete Normally, Please Retry

0.03

032

402

Duplicate Transaction

0.54

033

402

Capture Card, Please Call Processor

034

402

Card Lost

0.07

035

402

Card Stolen

0.08

036

200

Advice Accepted

037

200

Advice Accepted, No Action Taken

0.33

038

402

Reconciled, In Balance

039

402

Not Reconciled, Totals Provided

040

402

No Opened Batch

041

400

Field Validation

$0.00

042

401

Unauthorized

043

400

Amount Minimum

044

400

Amount Maximum

045

402

Duplicate Transaction

046

402

Avs Response Not Accepted

047

402

Csc Response Not Accepted

048

402

Csc Response Not Accepted

049

500

No Response From Server

050

500

Internal Error

051

500

Could Not Connect

052

500

Exception Condition Contact Support

053

500

Exception Condition Contact Support

054

402

Data Element Error

055

500

Acquirer Not Supported By Switch

056

402

Transaction Destination Cannot Be Found

057

402

Card Issuer Timed Out

058

402

Card Issuer Unavailable

059

402

Duplicate Transmission

060

500

System Error, Database

061

402

Aborted, Threshold Exceeded

062

500

System misconfiguration: {MAY INCLUDE ADDITIONAL ERROR TEXT}

063

500

System Error, Transaction

064

500

System Error, Hsm

065

500

Configuration Error, Invalid Terminal

066

500

Configuration Error, Invalid Terminal

067

500

Configuration Error, Configuration Error

067

500

Configuration error, invalid merchant

068

500

Configuration Error, Configuration Error

068

500

Configuration error, inactive merchant

069

500

Configuration Error, Configuration Error

069

500

Configuration error, invalid store

070

500

Configuration error, inactive store

070

500

Configuration Error, System Error

071

500

System Error, Other

072

500

System Error Other

073

500

System Error Other

074

400

HPP Generic Error Message; query transaction for error details.

074

400

Invalid Request

074

400

Merchant-id from request does not match merchant-id of initial transaction

081

400

Create entity failed

081

400

Update entity failed

081

500

Update failed

082

400

Add entity failed

082

500

Add failed

082

404

Device not found

082

404

Entity not found

082

500

Get failed

083

400

Get entity failed

083

500

Get failed

083

400

Resource not found

084

500

Add Token To Customer Failed

084

400

Apikey on device does not belong to the terminal you have authenticated. Please check that the device was configured correctly

085

404

Unable to delete setting

085

400

Valid Content-Type Header Required for PUT or POST

086

400

Missing or Invalid Accept Type Header. Accept Type Header must be of type ‘application/json or ‘application/xml

087

400

Metadata can only have a maximum of ten key/value pairs

088

400

No body in request

089

200

Delete Successful

089

500

Error Deleting resource

089

400

Unable to delete Customer token

090

400

Required request body content is missing

090

400

Required request body content is missing, malformed, or datatype usage (ex- boolean, number) is invalid

091

402

Delete Token Failed. Token Associated With Payment Plan

091

204

No batch found to process

091

404

Object not found

091

404

Transaction not found

092

405

Http Method not supported

092

404

URL Parameter Invalid not found

093

400

Customer Delete Failed – Customer has active plans

093

400

Merchant Opt Out Delete Failed

094

400

Cannot delete Plan that has been used to charge the customer

280

400

Transaction failed

281

400

Void failed. Cannot void ach transactions that are returned or settled.

282

400

Authorization failed

283

400

Validation failed

284

400

ACH Account not found

285

400

Cannot process request. Contact Clearent for assistance

286

400

An error occurred we did not account for with Drools rules or otherwise

287

404

Transaction not found

288

400

Request failed

289

400

Provider failed

290

500

Transaction Failed

291

400

Cannot process request. Contact Clearent for assistance

292

404

Transaction not found

293

404

Transaction not found

294

500

Cannot process request. Contact Clearent for assistance

295

500

Cannot process request. Contact Clearent for assistance

880

400

Error parsing request

880

400

Error while submitting request to pax terminal

880

400

Failed to process hpp request.

880

400

Transaction failed

880

500

Unexpected Error – please contact customer support

881

400

Device communications unsupported

881

400

Manufacturer unsupported

882

400

Transaction type unsupported for this manufacturer

883

500

Terminal not connected

884

400

Terminal cannot be determined. Configure from Virtual Terminal Settings

884

400

Terminal cannot be determined. Confirm terminal is configured for Semi-Integrated mode

885

400

Device disabled

886

400

Failed to connect to Clearent Gateway. Please check device configuration

886

400

Terminal connection error

887

400

Transaction failed

888

400

Failed to serialize request as xml.

889

400

Token only request failed

889

400

Transaction failed

890

400

Transaction endpoint does not match transaction type

8801

402

Could not determine if transaction succeeded or failed

8831

500

Terminal is busy. Check terminal and try again

13005

400

Signature not valid for HPP response

Onboarding

https://boarding-sb.clearent.net/

Payments

http://gateway-sb.clearent.net/

Hosted Payment Page

https://hpp-sb.clearent.net/hpp/{MID}/{TID}

Onboarding

https://boarding.clearent.net/

Payments

https://gateway.clearent.net/

Hosted Payment Page

https://hpp.clearent.net/hpp/{MID}/{TID}

ACH Request Validation Codes

We will validate your ACH request utilizing the following rules to help reduce returned ACH payments.

Below are common validations for the incoming request on ACH transactions.

Amount must include two decimal places

Amount must only contain digits and a decimal point

Amount must be 0.00 for validate transaction

Amount required (absolute number with two decimal places)

Routing number required

Account number required

Individual name required

Account type required (Checking or Savings)

Routing number should be 9 digits

10.

Account number should be 1 to 17 digits

11.

Transaction-key should not be provided

12.

Valid values are ‘true’ or ‘false

13.

Type should be ‘Debit’ — Transfer funds from the customer bank account to your (merchant) bank account or ‘Credit’ — Transfer funds from your (merchant) bank account to customer bank account

14.

Software type required. Please provide the name of your software, product, or service

15.

Software type version required. Provide version of software-type

16.

Provider Account Id required

17.

Valid values are ‘Pending’, ‘Settling’, ‘Returned’, or ‘Settled’

18.

Invoice value required if invoice is the check-field

ACH Return Codes

Returned ACH payments will always come with an ACH return code indicating why a customer’s payment was rejected. The most common reasons are insufficient funds, closed accounts, or invalid account information.

The table below lists all of the possible ACH return codes.

Return Code
Message

R02

Account closed A previously open account is now closed

R03

No account or unable to locate account The account number does not correspond to the individual identified in the entry or a valid account.

R04

Invalid account number The account number fails the check digit validation or may contain an incorrect number of digits

R05

Uncollected funds Available balance is sufficient, but the collected balance is not sufficient to cover the entry

R06

Returned per ODFI’s request The ODFI has requested that the RDFI return the entry

R07

Authorization revoked by customer Member who previously authorized an entry has revoked authorization with the Originator

R08

Payment stopped or stop payment on item Member had previously requested a stop payment of a single or recurring entry

R09

Uncollected funds Available balance is sufficient, but collected balance is not sufficient to cover the entry

R10

Customer advises not authorized Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document

R11

Check truncation entry return To be used when returning a check truncation entry

R12

Branch sold to another DFI RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution

R13

Invalid ACH routing number Financial institution does not receive commercial ACH entries

R14

Representment payee deceased or unable to continue in that capacity Representative payee is deceased or unable to continue in that capacity, beneficiary is not deceased

R15

Beneficiary of account holder deceased Beneficiary or Account Holder Deceased

R16

Account frozen Access to account is restricted due to specific action taken by the RDFI or by legal action

R17

File record edit criteria Fields rejected by RDFI processing (identified in return addenda)

R18

Improper effective entry date Entries have been presented prior to the first available processing window for the effective date.

R19

Amount field error Improper formatting of the amount field

R20

Nontransaction account Policies or regulations (such as Regulation D) prohibit or limit activity to the account indicated

R21

Invalid company identification The company ID information not valid (normally CIE entries)

R22

Invalid individual ID number Individual id used by receiver is incorrect (CIE entries)

R23

Credit entry refused by receiver Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account

R24

Duplicate entry RDFI has received a duplicate entry

R25

Addenda error Improper formatting of the addenda record information

R26

Mandatory field error Improper information in one of the mandatory fields

R27

Trace number error Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record

R28

Routing number or check digit error Check digit for the transit routing number is incorrect

R29

Corporate customer advises not authorized RDFI has been notified by business account holder that a specific transaction is unauthorized

R30

RDFI not participant in check truncation program Financial institution not participating in automated check safekeeping application

R31

Permissible return entry RDFI has been notified by business account holder that a specific transaction is unauthorized

R32

RDFI nonsettlement RDFI is not able to settle the entry

R33

Return of XCK entry RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry

R34

Limited participation DFI RDFI participation has been limited by a federal or state supervisor

R35

Return of improper debit entry ACH debit not permitted for use with the CIE standard entry class code (except for reversals)

R36

Return of improper credit entry

R37

Source Document Presented for Payment Check used for an ARC, BOC or POP entry has also been presented for payment

R38

Stop payment on source document Stop payment has been placed on a check used for an ARC entry

R40

Return of ENR entry by federal government agency (ENR only)

R41

Invalid transaction code (ENR only)

R42

Routing number or check digit error (ENR only)

R43

Invalid DFI account number (ENR only)

R44

Invalid individual ID number (ENR only)

R45

Invalid individual name/company name (ENR only)

R46

Invalid representative payee indicator (ENR only)

R47

Duplicate enrollment

R50

State law affecting RCK acceptance

R51

Item is ineligible, notice not provided, signature not genuine

R52

Stop payment on item

R61

Misrouted return Return entry was sent by RDFI to an incorrect ODFI routing/transit number

R62

Incorrect trace number

R63

Incorrect dollar amount

R64

Incorrect individual identification

R65

Incorrect transaction code

R66

Incorrect company identification

R67

Duplicate return ODFI has received more than one return entry for the same original entry

R68

Untimely return Return entry did not meet the return deadline

R69

Multiple errors

R70

Permissible return entry not accepted

R71

Misrouted dishonored return

R72

Untimely dishonored return

R73

Timely original return

R74

Corrected return

R80

Cross-border payment coding error

R81

Nonparticipant in cross-border program

R82

Invalid foreign receiving DFI identification

Duplicate Transaction Settings

Settings to check duplicate credit card transactions through the Quest Gateway.

Note: This is an optional setting.

Time Range in Minutes

(1 – 60)- time the setting will check for duplicates (not applicable with “use invoice instead of card”)

If Duplicate Found, Respond with Error

Payload will either return a 402 if set to true, or return a 200 with the message “Transaction Previously Approved” and previous transaction results if set to false (if using cloud based device, payload will always return a 200 with the message “Transaction Previously Approved”)

Include Invoice

The default is to only use the last four of the card within the time range. Enable this to search with both the last four and the invoice. If the invoice is not provided then only the last four of the card will be used.

Search at Merchant Level

Enable this to check all terminals at a merchant level

Use invoice instead of card

Enable if you want the system to search using an invoice instead of the last 4 of the card. If the invoice is not provided the last four will be used. There is no time limit if this option is enabled.

Transaction Webhook

The Transaction Webhook delivers notifications for all transaction events performed by a merchant account.

Supported Transaction Events

  • Authorization

  • Capture

  • Sale

  • Forced Sale

  • Refund

  • Unmatched Refund

  • Void

  • ACH Credit

  • ACH Debit

Sample Payload

The webhook payload is identical to the response returned for a transactional event, with the addition of a digital signature:

{
    "code": "200",
    "status": "success",
    "exchange-id": "ID-clearent-cgw-1-1710772535480-0-24101130",
    "links": [
        {
            "rel": "transaction",
            "href": "/rest/v2/transactions?id=117834254",
            "id": "117834254"
        }
    ],
    "payload": {
        "transaction": {
            "amount": "100.00",
            "id": "117834254",
            "created": "2024-04-09 14:53:24.148",
            "type": "SALE",
            "result": "APPROVED",
            "billing": {
                "zip": "85284"
            },
…
   "signature": "30650230447b36ebeb3aa57faec5141ea73ee3b6f0110dadb1c16dd7fffc7c0c8815879c67f1914910b81955f8685d669e06abd502310088b0260519094aa000077ced6f9c0ad686ca955c89e19e0b5303247b71c8785b4e561f24cba66b273bfcb28f1b066314"
}

Application Fixes

The Application Fixes webhook events notify about data validation issues detected in merchant applications. These events are triggered by validation checks during the underwriting process in our system.

Note: Applications configured to use Agreement Express do not generate these events.

Event Names

The following webhook event types are used to surface validation errors:

  • BusinessFixes

  • ContactFixes

Each event provides details about the issue, the affected contact, and recommended corrections.

Payload Structure

The webhook payload includes one or more validation messages for specific contacts. Each message contains a human-readable description and a code identifying the type of issue.

Example Payload

The webhook payload includes one or more validation messages for specific contacts. Each message contains a human-readable description and a code identifying the type of issue.

{
  "payload": [
    {
      "contactId": 131047,
      "messages": [
        {
          "message": "Fix Address",
          "code": 101
        }
      ]
    },
    {
      "contactId": 131048,
      "messages": [
        {
          "message": "Fix SSN",
          "code": 100
        }
      ]
    }
  ]
}

Message Codes

Each code corresponds to a specific type of validation issue. Use these codes to programmatically handle or display user-friendly error messages in your application interface.

Code
Description

100

Invalid or missing Social Security Number (SSN).

101

Invalid or incomplete address.

102

Invalid or missing date of birth.

103

Invalid or missing last name.

200

Secretary of State data mismatch.

201

Incorrect state of registration.

202

Invalid or missing tax ID.

203

Legal name mismatch.

204

Invalid physical address.

Handling Validation Events

To improve the merchant experience and avoid pended applications:

  • Monitor for BusinessFixes and ContactFixes events.

  • Display validation messages to the merchant during the application process.

  • Allow merchants to update their information before submission.

Application Status

Each merchant application goes through multiple stages before approval and onboarding. The webhook sends notifications when an application moves into one of the following states:

State
Description

Pended

The application requires manual intervention before proceeding.

Manual Review

The application is undergoing a detailed underwriting review.

Approved

The application has been approved and is ready for onboarding.

Declined

The application has been rejected and will not proceed further.

Boarded

The merchant account has been successfully boarded to the gateway and is ready to begin processing transactions.

Webhook Event Structure

The Application Status Webhook sends structured JSON payloads to the subscribed endpoint when an application’s status changes. The webhook includes:

  • event – The current status of the application.

  • merchantId – The unique merchant account identification number.

  • payload – An empty set for most statuses

Note: Except for Boarded, which contains payload with additional details.

Application Status Webhook Examples

Below are sample webhook payloads for each application status:

Pended

{
  "event": "Pended",
  "merchantId": "6588000000049726",
  "payload": ""
}

Manual Review

{
  "event": "Manual Review",
  "merchantId": "6588000000049726",
  "payload": ""
}

Approved

{
  "event": "Approved",
  "merchantId": "6588000000049726",
  "payload": ""
}

Declined Status

{
  "event": "Declined",
  "merchantId": "6588000000049726",
  "payload": ""
}

Boarded Status

{
  "event": "Boarded",
  "merchantId": "88880000000123456",
  "orderId": "999990000000987654",
  "payload": {
    "terminals": [
      {
        "apiKey": "2P0H1L84133",
        "publicKey": "ABCDEFGHIJK123456789",
        "name": "Merchant Name"
      }
    ]
  }
}

Note: The Boarded status includes additional merchant details, including terminal API keys and encryption keys.

Integration Process

Prerequisites

To begin with Automated Merchant Onboarding, you must complete an account setup and integration with the system. This includes:

  1. Gaining access to the test environment.

  2. Configuring specific settings with the help of a support team.

  3. Providing key URLs to ensure smooth communication and updates throughout the process.

Merchant Onboarding APIs

Boarding Management API

Merchant Application

  • PUT: Update Properties

  • GET: Get Properties

  • POST: Create Application

  • POST: Default Pricing Plan

  • POST: Submit Signatures

  • POST: Submit Application

Merchant Demographics API

Bank Account

  • GET: Get Bank Account

  • POST: Create Bank Account

  • PUT: Update Bank Accounts

  • DELETE: Delete Bank Accounts

  • PUT: Update Bank Account

  • DELETE: Delete Bank Account

Business Contact

  • GET: Get Business Contact

  • PUT: Update Business Contact

  • DELETE: Delete Business Contact

  • GET: Get Business Contacts

  • POST: Create Business Contact

  • POST: Create Ownership Disclosure

  • PUT: Update Ownership Disclosure

  • GET: Get Ownership Disclosure

Documents

  • GET: Get Voided Checks

  • POST: Upload Voided Checks

  • POST: Upload Voided Checks - Base64Format

  • POST: Upload Voided Checks - MultipleDocuments - Base64Format

  • POST: MultipleDocuments

  • POST: Base64Format

  • POST: Upload Document

  • GET: Get Documents By Category

  • POST: Upload Signed Application - Base64Format

  • POST: Upload Signed Application

  • GET: Get Documents By MerchantNumber

  • GET: Get Documents By DocumentId

  • DELETE: Delete Document

  • DELETE: Delete Voided Checks

  • POST: Update VoidedCheck's bank account number

Merchant:

  • GET: Merchants

  • POST: Creates Merchant

  • GET: Gets Merchant

  • PUT: Updates Merchant

  • DELETE: Deletes Merchant

  • GET: Gets Physical Address

  • PUT: Updates Physical Address

  • GET: Gets Mailing Address

  • PUT: Updates Mailing Addres

References

  • GET: Get Country Codes using Address Type

  • GET: Returns a list of state options

  • GET: Get MCC Codes

  • GET: Get Company Types

  • GET: Get Compensation Types

  • GET: Get Previous Processors

  • GET: Get Businesses Under User

  • GET: Search For Businesses Under User

  • GET: Get Phone Types

  • GET: Get Contact Types

  • GET: Get Relationship Origin Types

  • GET: Get Document Categories

  • GET: Get Signature Sections

  • GET: Get Signature Source Types

  • GET: Get Site Types

  • GET: Get Future Delivery Type

Sales Profile

  • GET: Get SalesProfile - v2.0

  • PUT: Update SalesProfile - v2.0

Site Survey

  • GET: Get Site Survey

  • PUT: Update Site Survey

Tax Payer

  • GET: Get Taxpayer - v2.0

  • PUT: Update Taxpayer - v2.0

Merchant Legal Documents API

Signatures

  • GET: Get Signatures - Legal Documents

  • PUT: Update Signatures - Legal Documents

  • DELETE: Delete Signatures - Legal Documents

  • GET: Get Signatures - Demographics

  • PUT: Update Signatures - Demographics

  • DELETE: Delete Signatures - Demographics

Types

  • GET: Returns Types of Terms and Conditions - Demographics

  • GET: Returns Types of Terms and Conditions - Legal Documents

Terms And Conditions

  • GET: Returns Terms and Conditions applicable to merchant identified by MerchantNumber - Demographics

  • GET: Returns Terms and Conditions applicable to merchant identified by MerchantNumber - Legal Documents

  • GET: Returns Terms and Conditions entry for specified Type ID - Demographics

  • GET: Returns Terms and Conditions entry for specified Type ID - Legal Documents

Pricing Plan API

Pricing Plan V2

  • GET: Returns a pricing plan

  • POST: Creates a pricing plan

  • DELETE: Deletes a pricing plan

  • GET: Returns all pricing plans of the merchant

  • PUT: Updates a pricing plan

  • DELETE: Deletes a pricing plan

  • GET: Templates

  • GET: Eligibility

  • GET: EmpowerAttributes

Reference

  • GET: PayInMonth

  • GET: DisplayTypeCode

Equipment Order API

Equipment Order

  • POST: Post Equipment Order

  • GET: Get a merchant's existing order

  • DELETE: Delete a merchant's existing order

  • GET: Get a merchant's existing order by order id

  • GET: Get a merchant's existing order by merchant and status

Equipment Configuration Survey API

Equipment Configuration Survey

  • GET: Get Equipment Configuration Survey

Equipment Terminal Loader API

Equipment Terminal Loader

  • GET: Get All Products (devices) that match search criteria

  • GET: Get One Product (device)

eDocs Reporting API

eDocs Reporting

  • GET: Get Document from eDocs

  • GET: Get Document Types

  • GET: Get Documents By Type

  • GET: Get Statements by Year

  • GET: Get Statements by Year and Month

Launch Integrator Setup API

Launch Integrator Setup

  • GET: Retrieves a merchant

  • POST: Creates a new merchant

API Catalog

For more information, refer to the following articles:

Automated Merchant Onboarding Setup API

Launch For Integrators Setup API

Launch Integrator Setup

  • GET: Retrieves a merchant

  • POST: Creates a new merchant

Reporting API

Reporting

Reporting

  • GET: merchants

  • GET: merchantCurrentPricing

  • GET: merchantDisputes

  • GET: merchantCases

  • GET: merchantBankDeposits

  • GET: merchantTransactions

Onboarding API Result Codes

Value
HTTP Status Code
Message

9001

200

Approved

9002

401

Unauthorized

9003

500

System Error Other

9004

400

Invalid Request

9005

400

Valid Content-Type Header Required for PUT or POST

9006

400

Missing or Invalid Accept Type Header. Accept Type Header must be of type ‘application/json’

9007

400

Required request body content is missing, malformed, or datatype usage (ex- boolean, number) is invalid

9008

405

Http Method not supported

9009

404

Not Found

9010

400

Current merchant status cannot be updated to the requested status

9011

403

Forbidden

9012

400

Merchant is locked for editing

4000

400

Merchant number is required for this Bank Account request

4001

400

No bank account provided

4002

400

Bank account not found

4010

400

Bank name is required

4015

400

Bank Account Type Id is required

4016

400

Bank Account Type Id must be equal to or greater than 1 and less than or equal to 3

4020

400

Bank Account Name Type Id must be greater than 0

4025

400

Bank Account Other Name must be less than 100 characters

4030

400

Bank Account ABA/Routing number is required

4031

400

Bank Account ABA/Routing number must be all digits

4032

400

Bank Account ABA/Routing number is invalid

4040

400

Bank Account – Account Number is required

4041

400

Bank Account – Account Number must be all digits

4050

400

Bank Account name is required. Please provide either the NameOnAccount or the AccountHolderFirstName with the AccountHolderLastName

4051

400

Bank Account Only AccountHolderFirstName and AccountHolderLastName or NameOnAccount can be supplied, but not both

4052

400

When using AccountHolderFirstName on Bank Account, AccountHolderLastName is required

4053

400

When using AccountHolderLastName on Bank Account, AccountHolderFirstName is required

4060

400

Business bank accounts are required to cover fees, funds, and chargebacks.

4090

400

Bank account defaults not found

4091

400

File format must be valid image or pdf

4092

400

File must be smaller than 5MB

4093

400

The name on the bank account listed for deposits must match merchant’s legal name or DBA name.

4100

404

Business Contacts Not Found

4110

400

Merchant number is required for Business Contacts request

4120

400

A business contact must be added for every individual who owns at least 25% of a merchant.

4121

404

A disclosure for this merchant that every individual who owns at least 25% of a merchant has not been found

4200

404

Business Contact Not Found with that MerchantNumber supplied

4201

400

Phone Contact Type is Required

4202

405

Duplicate contact found

4203

400

Contact not found for this merchant number

4204

400

Merchant number was not provided for this request

4205

400

At least one Business Contact must be listed as a signer.

4210

400

Email Address is required for a business contact

4211

400

Email Address is invalid for a business contact

4212

400

Must have either a valid phone or a valid email address

4220

400

Ownership Amount is required for a business owner

4221

400

Business Ownership amount must be greater than 0 and less than 101

4230

400

Date of Birth is Required for a business contact

4231

400

Date of Birth is invalid. Date of Birth must be in the past and less than 200 years ago.

4240

400

First name is required for business contact

4241

400

First name is required for business contact

4250

400

One Phone number is required for business contact

4251

400

Area Code is Required for Business Contact Phone number

4252

400

Area Code Must be Three Digits for Business Contact Phone number

4253

400

Phone number prefix and line number for the Business Contact Phone Number are required

4254

400

Phone Number's prefix and line number must match the format 123-4567 when combined

4255

404

Phone Number not found

4260

400

Business Contact social security number is required

4261

400

Business Contact social security number is invalid

4270

400

Line 1 is required for Business Contact's Address

4275

400

City is required for Business Contact's Address

4280

400

State is required for Business Contact's Address

4285

400

Zip Code is required for Business Contact's Address

4290

400

Country Code is required for Business Contact's Address

4291

404

Business Contact's Address Not Found

4292

400

Contact Not Found

4293

400

One or more Contact Types are required.

4295

400

Country of citizenship is required for Business Contact

4296

400

Title is required for Owners and Signers

4297

400

Total Ownership Amount cannot exceed 100%.

4300

404

Contact Address Not Found

4400

404

Contact Not Found

4401

405

Found a duplicate contact and cannot save

4402

400

The contact Id provided is not associated with the merchant number provided

4403

400

Merchant number is required for this request

4410

400

Date of Birth is Required for a general contact

4411

400

Date of Birth is invalid. Date of Birth must be in the past and less than 200 years ago.

4500

400

Merchant number is required for this request

4501

400

Business information is required

4502

400

Business DBA (Doing Business As) name is required

4503

400

Business Hierarchy Node Key is required

4504

400

Business information is required

4505

400

Merchant Business’ was not found

4520

400

Merchant Business’ email address is invalid

4525

400

Merchant Business’ website is invalid

4530

400

Merchant Business’ phone number is required

4531

400

Merchant Business’ phone number phone contact type is required

4532

400

Merchant Business’ phone number area code is required

4533

400

Merchant Business’ phone number area code must be 3 digits

4534

400

Merchant Business’ phone number must have a line number and prefix. They are required

4535

400

Merchant Business’ phone number must match the format 123-4567

4540

400

Merchant Business’ Company Type is required

4545

400

Merchant Business’ Sales Information is required

4600

400

PageSize is required for this request

4601

400

PageSize must have a value no less than 1

4605

400

PageNumber is required for this request

4606

400

PageNumber must have a value no less than 1

4800

400

Merchant number is required for this request

4801

404

Merchant business mailing address not found

4802

400

Merchant business mailing address information is required

4803

400

Merchant business mailing address Line 1 is required

4804

400

Merchant business mailing address City is required

4805

400

Merchant business mailing address State Code is required

4806

400

Merchant business mailing address Zip is required

4807

400

Merchant business mailing address Country Code is required

4900

400

Merchant number is required for this request

4901

400

Merchant business physical address information is required for this request

4902

404

Merchant business physical address not found

4903

400

Merchant business physical address Line 1 is required

4904

400

Merchant business physical address City is required

4905

400

Merchant business physical address State Code is required

4906

400

Merchant business physical address Zip is required

4907

400

Merchant business physical address Country Code is required

5000

404

Sales information not found

5001

400

Merchant number is required for this request

5010

400

Sales Information has an invalid Business Id

5100

404

Sales profile not found

5101

400

Sales Profile’s Merchant Category Code (MCC) was not found

5102

400

Sales Profile’s Merchant Category Code (MCC) is required

5103

400

Sales Profile’s Merchant Category Code (MCC) must be all digits

5104

400

Sales Profile’s Category Code (MCC) must be 4 digits

5105

400

Merchant Number is required for this request

5106

400

Sales Profile’s Moto Keyed Percentage and E-Commerce Percentage do not total 100

5107

400

Sales Profile’s Card Present Percentage is required

5108

400

Sales Profile’s Card Present Percentage must be either 0, 100, or between 0 and 100

5110

400

Sales Profile’s eCommerce Percentage is required

5111

400

Sales Profile’s eCommerce Percentage is must be either 0, 100, or between 0 and 100

5115

400

Sales Profile’s Moto Keyed Percentage is required

5116

400

Sales Profile’s Moto Keyed Percentage must be either 0, 100, or between 0 and 100

5120

400

Sales Profile’s Refund/Return Policy is required

5125

400

Sales Profile’s Products Sold is required

5130

400

Sales Profile’s Previously Accepted Payment Cards is required

5135

400

Sales Profile’s CompetitorId is required

5136

400

Sales Profile’s CompetitorId is invalid

5140

400

Sales Profile’s Previously Terminated Or Identified By Risk Monitoring is required

5145

400

Sales Profile’s Reason Previously Terminated Or Identified By Risk is required

5150

400

Sales Profile’s Currently Open For Business is required

5155

400

Sales Profile’s annual volume is required

5160

400

Sales Profile’s average ticket is required

5161

400

Sales Profile’s high ticket is required

5165

400

Sales Profile’s Owns Product is required

5170

400

Sales Profile’s Orders Product is required

5175

400

Sales Profile’s Sells Firearms is required

5176

400

Sales Profile Fire Arms License Must be no more than 15 characters

5180

400

Sales Profile’s Sells Firearm Accessories is required

5181

400

Sales Profile’s Sells Firearm License is required

5185

400

Sales Profile’s Future Delivery Type Id is required when Future Delivery Percentage is greater than 0.

5186

400

Sales Profile’s Future Delivery Percentage must be either 0, 100, or between 0 and 100

5187

400

Sales Profile’s Amex MID is required when American Express ESA Direct is selected

5188

400

Sales Profile’s EBT Number is required when EBT is selected

5190

400

Sales Profile: At Least One Card Brand Is Required

5191

400

Sales Profile: Cannot Have American Express Opt Blue Card Brand along with American Express ESA, please choose one or the other

5192

400

Sales Profile: Cannot have more than one American Express ESA Card Brand

5193

400

Sales Profile: Cannot have more than one American Express Opt Blue Card Brand

5194

400

Sales Profile: Cannot have more than one Debit Network Card Brand

5195

400

Sales Profile: Cannot have more than one Discover Card Brand

5196

400

Sales Profile: Cannot have more than one EBT Card Brand

5197

400

Sales Profile: Cannot have more than one MasterCard Card-Brand

5198

400

Sales Profile: Cannot have more than one Visa Card Brand

5199

400

Sales Profile: Future Delivery Percentage is required.

5200

400

Sales Profile: If Future Delivery Type ID is ‘Other’ the Other Delivery Type field should be used to indicate the time period in which deliveries will be fulfilled.

5201

400

Sales Profile: Invalid Future Delivery Type ID.

5202

400

Sales Profile’s AmexMid must be a numeric value containing less than 10 digits.

5203

400

Sales Profile’s EBTNumber must be a numeric value containing less than 20 digits.

5300

404

Site survey not found

5301

400

Merchant Number is required for this request

5310

400

Site survey Site Type ID must be 1, 2, 3, or 4

5311

400

Site survey Site Type ID is required

5312

400

Site survey Agreement Accepted must be true

5313

400

Site survey Site Survey Conducted in Person is required

5314

400

Site survey Merchant Acquisition Type ID is required when Site Survey Conducted in Person is false

5315

400

Site survey Merchant Acquisition Type ID must be between 1 and 3

5317

400

Site survey Inventory Matches Product Sold is required

5318

400

Site survey Inventory Matches Product Sold comments are required when Inventory Matches Product Sold is False

5320

400

Site survey valid verified id is required

5330

400

Site survey’s Other Site Type Description valid verified id is required

5400

404

Tax payer not found

5401

400

Merchant number is required for this request

5405

400

TIN is required for this request

5410

400

TIN must be 9 digits and must be a valid sequence of numbers

5415

400

TINTypeID is required for this request

5420

400

TINTypeID must be between 1 and 3

5425

400

Business Legal Name is required for this request

5500

404

Electronic Document not found

5501

404

Electronic Document content not found

5510

400

Electronic Document category is invalid

5600

400

Merchant number is required

5601

404

Application Progress Section Not Found

5700

400

Required signature missing. Signature information is required for each section of the application: MerchantAgreement, PersonalGuarantee, BankDisclosure, and W-9. For signatures provided electronically, AgreementToSignElectronically and ElectronicConfirmation are also required.

5701

400

Duplicate signature. Only a single signature can be provided for each section of the application.

5702

400

All signatures must be linked to a BusinessContactID.

5703

400

Selected BusinessContactID does not exist in system.

5704

400

IPAddress and TimeStamp are required for signatures collected via an online form.

5705

400

DocumentID is required for signatures collected via document upload.

6000

400

Fee is required for selected template.

6001

400

Fee MasterCard Qualified CheckCard is required for selected template.

6002

400

Fee Visa Qualified CheckCard is required for selected template.

6003

400

Fee MasterCard Qualified Credit is required for selected template.

6004

400

Fee Visa Qualified Credit is required for selected template.

6005

400

Fee American Express is required for selected template.

6006

400

Fee Discover is required for selected template.

6007

400

Fee IC Plus: Interchange, Dues, Fees and Assessments is required for selected template.

6008

400

Fee PIN-Debit Conveyance is required for selected template.

6009

400

Fee EBT is required for selected template.

6010

400

Fee Mid Qualified Surcharge is required for selected template.

6011

400

Fee Non Qualified Surcharge is required for selected template.

6012

400

Fee Interchange Passthrough is required for selected template.

6013

400

Fee Authorization Fee is required for selected template.

6014

400

Fee AVS Transactions (Surcharge) is required for selected template.

6015

400

Fee Voice Authorization is required for selected template.

6016

400

Fee Chargeback Item Processing is required for selected template.

6017

400

Fee Retrieval Item Processing is required for selected template.

6018

400

Fee Monthly Account Fee is required for selected template.

6019

400

Fee Monthly Minimum Discount is required for selected template.

6020

400

Fee Gross Settlement Fee is required for selected template.

6021

400

Fee Debit Access Fee is required for selected template.

6022

400

Fee Monthly Compass Online Reporting is required for selected template.

6023

400

Fee Monthly Supply Club Membership is required for selected template.

6024

400

Fee Application Processing Fee is required for selected template.

6029

400

Fee IVR Authorization is required for selected template.

6031

400

Fee Annual Fee is required for selected template.

6032

400

Fee Semi-Annual Fee is required for selected template.

6033

400

Fee Interchange Adjustment is required for selected template.

6034

400

Fee Discount Adjustment is required for selected template.

6035

400

Fee Authorization Adjustment is required for selected template.

6036

400

Fee Chargeback is required for selected template.

6038

400

Fee Equipment Sale is required for selected template.

6039

400

Fee Other Adjustment is required for selected template.

6040

400

Fee Association Per Item Surcharge is required for selected template.

6041

400

Fee Association Foreign IC Surcharge is required for selected template.

6042

400

Fee Batch Processing is required for selected template.

6043

400

Fee Funds Transfer Processing is required for selected template.

6044

400

Fee Monthly Paper Statement is required for selected template.

6045

400

Fee Software Transaction Surcharge is required for selected template.

6046

400

Fee Software Installation is required for selected template.

6047

400

Fee Monthly Software is required for selected template.

6048

400

Fee Wireless/Cellular Transaction Surcharge is required for selected template.

6049

400

Fee Wireless/Cellular Installation is required for selected template.

6050

400

Fee Monthly Wireless/Cellular Access is required for selected template.

6051

400

Fee Wireless/Cellular Update is required for selected template.

6052

400

Fee Terminal Purchase is required for selected template.

6053

400

Fee Hardware Purchase is required for selected template.

6054

400

Fee Software Purchase is required for selected template.

6055

400

Fee Download Programming is required for selected template.

6056

400

Fee Non Supported Help Desk Call is required for selected template.

6057

400

Fee Monthly Warranty/Insurance is required for selected template.

6058

400

Fee Authorization Fee is required for selected template.

6059

400

Fee Settlement and Capture Fee is required for selected template.

6060

400

Fee Monthly Compass Fee is required for selected template.

6062

400

Fee American Express Auth, Capture Fee is required for selected template.

6063

400

Fee PIN Based Debit Transaction Fee is required for selected template.

6064

400

Fee EBT Transaction Fee is required for selected template.

6065

400

Fee Batch Fee is required for selected template.

6066

400

Fee Voice Authorization is required for selected template.

6067

400

Fee Monthly Statement Fee (per MID) is required for selected template.

6068

400

Fee Monthly Account (Residency) Fee is required for selected template.

6069

400

Fee Monthly Help Desk Fee (per MID) is required for selected template.

6070

400

Fee Chargeback Fee is required for selected template.

6071

400

Fee Retrieval Fee is required for selected template.

6072

400

Fee Keyed Application Fee is required for selected template.

6073

400

Fee Inactivity Fee is required for selected template.

6074

400

Fee Discover Qualified CheckCard is required for selected template.

6075

400

Fee Discover Qualified Credit is required for selected template.

6076

400

Fee Wright Express (Capture) is required for selected template.

6077

400

Fee Voyager (Capture) is required for selected template.

6078

400

Fee Minimum Monthly Discount Billed to Merchant is required for selected template.

6080

400

Fee Help Desk Calls for non-supported (Class B) terminals and stage-only builds is required for selected template.

6083

400

Fee PIN-Based Debit is required for selected template.

6084

400

Fee Other Expense Adjustment is required for selected template.

6085

400

Fee Retrieval Adjustment is required for selected template.

6086

400

Fee Other Expense Adjustment is required for selected template.

6087

400

Fee Other Passthrough Adjustment is required for selected template.

6088

400

Fee Equipment Sale is required for selected template.

6089

400

Fee Monthly Account Fee Adjustment is required for selected template.

6090

400

Fee Monthly Compass Online Reporting Adjustment is required for selected template.

6091

400

Fee Monthly Compass Fee Adjustment is required for selected template.

6092

400

Fee Batch Fee Adjustment is required for selected template.

6093

400

Fee Monthly Statement Fee (per MID) Adjustment is required for selected template.

6094

400

Fee Monthly Account (Residency) Fee Adjustment is required for selected template.

6095

400

Fee Monthly Help Desk Fee (per MID) Adjustment is required for selected template.

6096

400

Fee Partner Interchange Adjustment is required for selected template.

6097

400

Fee Non-Complete PCI Questionnaire Fee is required for selected template.

6100

400

Fee Host Capture Administrative Transaction Fee is required for selected template.

6101

400

Fee Host Capture Monthly Fee is required for selected template.

6102

400

Fee Host Capture Auth Transaction Fee is required for selected template.

6103

400

Fee Host Capture Administrative Transaction Fee is required for selected template.

6104

400

Fee Visa ZFL Fee is required for selected template.

6105

400

Fee Visa ZFL Fee is required for selected template.

6106

400

Fee Visa Misuse Fee is required for selected template.

6107

400

Fee Visa Misuse Fee is required for selected template.

6108

400

Fee Non-Complete PCI Questionnaire Fee is required for selected template.

6109

400

Fee Interchange is required for selected template.

6110

400

Fee Fees is required for selected template.

6111

400

Fee Assessment is required for selected template.

6112

400

Fee Foreign Fee is required for selected template.

6113

400

Fee PinDebit Network Fee is required for selected template.

6114

400

Fee PinDebit Switch Fee is required for selected template.

6115

400

Fee Wireless Terminal Fee is required for selected template.

6117

400

Fee EMF Expense is required for selected template.

6118

400

Fee EMF Revenue is required for selected template.

6119

400

Fee IVR Authorization is required for selected template.

6120

400

Fee Merchant Regulatory Reporting Fee Without Revenue Share is required for selected template.

6121

400

Fee Merchant Regulatory Reporting Fee With Revenue Share is required for selected template.

6122

400

Fee Partner Regulatory Reporting Fee is required for selected template.

6141

400

Fee VisaTransactionIntegrityFee is required for selected template.

6142

400

Fee VisaFixedAcquirerNetworkFee is required for selected template.

6143

400

Fee VisaTransactionIntegrityRevenue is required for selected template.

6144

400

Fee VisaFixedAcquirerNetworkRevenue is required for selected template.

6145

400

Fee VisaZFLPartnerExpense is required for selected template.

6146

400

Fee VisaAuthMisusePartnerExpense is required for selected template.

6148

400

Fee MembershipNet is required for selected template.

6149

400

Fee Amex Qualified Credit is required for selected template.

6150

400

Fee Amex Qualified Prepaid is required for selected template.

6173

400

Fee Monthly DataGuardian Fee is required for selected template.

6174

400

Fee Monthly DataGuardian Fee is required for selected template.

6175

400

Fee Partner PCI Scan Fee is required for selected template.

6176

400

Fee Merchant PCI Scan Fee is required for selected template.

6177

400

Fee Membership Fee Expense is required for selected template.

6178

400

Fee MasterCardMerchantLocationFeeExpense is required for selected template.

6179

400

Fee MasterCardMerchantLocationFeeRevenue is required for selected template.

6180

400

Fee Partner 3rd Party Setup Fee is required for selected template.

6181

400

Fee Merchant 3rd Party Setup Fee is required for selected template.

6182

400

Fee Partner 3rd Party Monthly Fee is required for selected template.

6183

400

Fee Merchant 3rd Party Monthly Fee is required for selected template.

6184

400

Fee Partner 3rd Party Per Transaction Fee is required for selected template.

6185

400

Fee Merchant 3rd Party Per Transaction Fee is required for selected template.

6186

400

Fee Partner 3rd Party Annual Fee is required for selected template.

6187

400

Fee Merchant 3rd Party Annual Fee is required for selected template.

6188

400

Fee Authorization Fee (IP) is required for selected template.

6189

400

Fee Authorization Fee (Non-IP) is required for selected template.

6190

400

Fee Non-Complete PCI Questionnaire Fee – Partner is required for selected template.

6191

400

Fee RAF Expense is required for selected template.

6192

400

Fee RAF Revenue is required for selected template.

6193

400

Fee MEBO Expense is required for selected template.

6194

400

Fee MEBO Revenue is required for selected template.

6195

400

Fee Card Present Processing Fee is required for selected template.

6197

400

Fee Card Not Present Processing Fee is required for selected template.

6199

400

Fee Deal Manager Platform Fee is required for selected template.

6201

400

Fee Fill My Book Platform Fee is required for selected template.

6297

400

Fee Amex OptBlue Discount is invalid for selected template.

6298

400

Fee Cash Discount Rate is invalid for selected template.

6299

400

Fee Base Rate Surcharge (Qualified) is invalid for selected template.

6300

400

Fee is invalid for selected template.

6301

400

Fee MasterCard Qualified CheckCard is invalid for selected template.

6302

400

Fee Visa Qualified CheckCard is invalid for selected template.

6303

400

Fee MasterCard Qualified Credit is invalid for selected template.

6304

400

Fee Visa Qualified Credit is invalid for selected template.

6305

400

Fee American Express is invalid for selected template.

6306

400

Fee Discover is invalid for selected template.

6307

400

Fee IC Plus: Interchange, Dues, Fees and Assessments is invalid for selected template.

6308

400

Fee PIN-Debit Conveyance is invalid for selected template.

6309

400

Fee EBT is invalid for selected template.

6310

400

Fee Mid Qualified Surcharge is invalid for selected template.

6311

400

Fee Non Qualified Surcharge is invalid for selected template.

6312

400

Fee Interchange Passthrough is invalid for selected template.

6313

400

Fee Authorization Fee is invalid for selected template.

6314

400

Fee AVS Transactions (Surcharge) is invalid for selected template.

6315

400

Fee Voice Authorization is invalid for selected template.

6316

400

Fee Chargeback Item Processing is invalid for selected template.

6317

400

Fee Retrieval Item Processing is invalid for selected template.

6318

400

Fee Monthly Account Fee is invalid for selected template.

6319

400

Fee Monthly Minimum Discount is invalid for selected template.

6320

400

Fee Gross Settlement Fee is invalid for selected template.

6321

400

Fee Debit Access Fee is invalid for selected template.

6322

400

Fee Monthly Compass Online Reporting is invalid for selected template.

6323

400

Fee Monthly Supply Club Membership is invalid for selected template.

6324

400

Fee Application Processing Fee is invalid for selected template.

6329

400

Fee IVR Authorization is invalid for selected template.

6331

400

Fee Annual Fee is invalid for selected template.

6332

400

Fee Semi-Annual Fee is invalid for selected template.

6333

400

Fee Interchange Adjustment is invalid for selected template.

6334

400

Fee Discount Adjustment is invalid for selected template.

6335

400

Fee Authorization Adjustment is invalid for selected template.

6336

400

Fee Chargeback is invalid for selected template.

6338

400

Fee Equipment Sale is invalid for selected template.

6339

400

Fee Other Adjustment is invalid for selected template.

6340

400

Fee Association Per Item Surcharge is invalid for selected template.

6341

400

Fee Association Foreign IC Surcharge is invalid for selected template.

6342

400

Fee Batch Processing is invalid for selected template.

6343

400

Fee Funds Transfer Processing is invalid for selected template.

6344

400

Fee Monthly Paper Statement is invalid for selected template.

6345

400

Fee Software Transaction Surcharge is invalid for selected template.

6346

400

Fee Software Installation is invalid for selected template.

6347

400

Fee Monthly Software is invalid for selected template.

6348

400

Fee Wireless/Cellular Transaction Surcharge is invalid for selected template.

6349

400

Fee Wireless/Cellular Installation is invalid for selected template.

6350

400

Fee Monthly Wireless/Cellular Access is invalid for selected template.

6351

400

Fee Wireless/Cellular Update is invalid for selected template.

6352

400

Fee Terminal Purchase is invalid for selected template.

6353

400

Fee Hardware Purchase is invalid for selected template.

6354

400

Fee Software Purchase is invalid for selected template.

6355

400

Fee Download Programming is invalid for selected template.

6356

400

Fee Non Supported Help Desk Call is invalid for selected template.

6357

400

Fee Monthly Warranty/Insurance is invalid for selected template.

6358

400

Fee Authorization Fee is invalid for selected template.

6359

400

Fee Settlement and Capture Fee is invalid for selected template.

6360

400

Fee Monthly Compass Fee is invalid for selected template.

6362

400

Fee American Express Auth, Capture Fee is invalid for selected template.

6363

400

Fee PIN Based Debit Transaction Fee is invalid for selected template.

6364

400

Fee EBT Transaction Fee is invalid for selected template.

6365

400

Fee Batch Fee is invalid for selected template.

6366

400

Fee Voice Authorization is invalid for selected template.

6367

400

Fee Monthly Statement Fee (per MID) is invalid for selected template.

6368

400

Fee Monthly Account (Residency) Fee is invalid for selected template.

6369

400

Fee Monthly Help Desk Fee (per MID) is invalid for selected template.

6370

400

Fee Chargeback Fee is invalid for selected template.

6371

400

Fee Retrieval Fee is invalid for selected template.

6372

400

Fee Keyed Application Fee is invalid for selected template.

6373

400

Fee Inactivity Fee is invalid for selected template.

6374

400

Fee Discover Qualified CheckCard is invalid for selected template.

6375

400

Fee Discover Qualified Credit is invalid for selected template.

6376

400

Fee Wright Express (Capture) is invalid for selected template.

6377

400

Fee Voyager (Capture) is invalid for selected template.

6378

400

Fee Minimum Monthly Discount Billed to Merchant is invalid for selected template.

6380

400

Fee Help Desk Calls for non-supported (Class B) terminals and stage-only builds is invalid for selected template.

6383

400

Fee PIN-Based Debit is invalid for selected template.

6384

400

Fee Other Expense Adjustment is invalid for selected template.

6385

400

Fee Retrieval Adjustment is invalid for selected template.

6386

400

Fee Other Expense Adjustment is invalid for selected template.

6387

400

Fee Other Passthrough Adjustment is invalid for selected template.

6388

400

Fee Equipment Sale is invalid for selected template.

6389

400

Fee Monthly Account Fee Adjustment is invalid for selected template.

6390

400

Fee Monthly Compass Online Reporting Adjustment is invalid for selected template.

6391

400

Fee Monthly Compass Fee Adjustment is invalid for selected template.

6392

400

Fee Batch Fee Adjustment is invalid for selected template.

6393

400

Fee Monthly Statement Fee (per MID) Adjustment is invalid for selected template.

6394

400

Fee Monthly Account (Residency) Fee Adjustment is invalid for selected template.

6395

400

Fee Monthly Help Desk Fee (per MID) Adjustment is invalid for selected template.

6396

400

Fee Partner Interchange Adjustment is invalid for selected template.

6397

400

Fee Non-Complete PCI Questionnaire Fee is invalid for selected template.

6400

400

Fee Host Capture Administrative Transaction Fee is invalid for selected template.

6401

400

Fee Host Capture Monthly Fee is invalid for selected template.

6402

400

Fee Host Capture Auth Transaction Fee is invalid for selected template.

6403

400

Fee Host Capture Administrative Transaction Fee is invalid for selected template.

6404

400

Fee Visa ZFL Fee is invalid for selected template.

6405

400

Fee Visa ZFL Fee is invalid for selected template.

6406

400

Fee Visa Misuse Fee is invalid for selected template.

6407

400

Fee Visa Misuse Fee is invalid for selected template.

6408

400

Fee Non-Complete PCI Questionnaire Fee is invalid for selected template.

6409

400

Fee Interchange is invalid for selected template.

6410

400

Fee Fees is invalid for selected template.

6411

400

Fee Assessment is invalid for selected template.

6412

400

Fee Foreign Fee is invalid for selected template.

6413

400

Fee PinDebit Network Fee is invalid for selected template.

6414

400

Fee PinDebit Switch Fee is invalid for selected template.

6415

400

Fee Wireless Terminal Fee is invalid for selected template.

6417

400

Fee EMF Expense is invalid for selected template.

6418

400

Fee EMF Revenue is invalid for selected template.

6419

400

Fee IVR Authorization is invalid for selected template.

6420

400

Fee Merchant Regulatory Reporting Fee Without Revenue Share is invalid for selected template.

6421

400

Fee Merchant Regulatory Reporting Fee With Revenue Share is invalid for selected template.

6422

400

Fee Partner Regulatory Reporting Fee is invalid for selected template.

6441

400

Fee VisaTransactionIntegrityFee is invalid for selected template.

6442

400

Fee VisaFixedAcquirerNetworkFee is invalid for selected template.

6443

400

Fee VisaTransactionIntegrityRevenue is invalid for selected template.

6444

400

Fee VisaFixedAcquirerNetworkRevenue is invalid for selected template.

6445

400

Fee VisaZFLPartnerExpense is invalid for selected template.

6446

400

Fee VisaAuthMisusePartnerExpense is invalid for selected template.

6448

400

Fee MembershipNet is invalid for selected template.

6449

400

Fee Amex Qualified Credit is invalid for selected template.

6450

400

Fee Amex Qualified Prepaid is invalid for selected template.

6473

400

Fee Monthly DataGuardian Fee is invalid for selected template.

6474

400

Fee Monthly DataGuardian Fee is invalid for selected template.

6475

400

Fee Partner PCI Scan Fee is invalid for selected template.

6476

400

Fee Merchant PCI Scan Fee is invalid for selected template.

6477

400

Fee Membership Fee Expense is invalid for selected template.

6478

400

Fee MasterCardMerchantLocationFeeExpense is invalid for selected template.

6479

400

Fee MasterCardMerchantLocationFeeRevenue is invalid for selected template.

6480

400

Fee Partner 3rd Party Setup Fee is invalid for selected template.

6481

400

Fee Merchant 3rd Party Setup Fee is invalid for selected template.

6482

400

Fee Partner 3rd Party Monthly Fee is invalid for selected template.

6483

400

Fee Merchant 3rd Party Monthly Fee is invalid for selected template.

6484

400

Fee Partner 3rd Party Per Transaction Fee is invalid for selected template.

6485

400

Fee Merchant 3rd Party Per Transaction Fee is invalid for selected template.

6486

400

Fee Partner 3rd Party Annual Fee is invalid for selected template.

6487

400

Fee Merchant 3rd Party Annual Fee is invalid for selected template.

6488

400

Fee Authorization Fee (IP) is invalid for selected template.

6489

400

Fee Authorization Fee (Non-IP) is invalid for selected template.

6490

400

Fee Non-Complete PCI Questionnaire Fee – Partner is invalid for selected template.

6491

400

Fee RAF Expense is invalid for selected template.

6492

400

Fee RAF Revenue is invalid for selected template.

6493

400

Fee MEBO Expense is invalid for selected template.

6494

400

Fee MEBO Revenue is invalid for selected template.

6495

400

Fee Card Present Processing Fee is invalid for selected template.

6496

400

Fee Card Not Present Processing Fee is invalid for selected template.

6497

400

Fee Deal Manager Platform Fee is invalid for selected template.

6498

400

Fee Fill My Book Platform Fee is invalid for selected template.

6500

400

Amex OptBlue Discount Fees Must Be Equal: Amex Qualified Credit.

6501

400

Amex OptBlue Discount Fees Must Be Equal: Amex Qualified Prepaid.

6502

400

Cash Discount Rate Fees Must Be Equal: MasterCard Debit.

6503

400

Cash Discount Rate Fees Must Be Equal: Visa Debit.

6504

400

Cash Discount Rate Fees Must Be Equal: MasterCard Credit.

6505

400

Cash Discount Rate Fees Must Be Equal: Visa Credit.

6506

400

Cash Discount Rate Fees Must Be Equal: Discover Debit.

6507

400

Cash Discount Rate Fees Must Be Equal: Discover Credit.

6508

400

Cash Discount Rate Fees Must Be Equal: Amex Qualified Credit.

6509

400

Cash Discount Rate Fees Must Be Equal: Amex Qualified Prepaid.

6510

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:MasterCard Debit.

6511

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Visa Debit.

6512

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:MasterCard Credit.

6513

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Visa Credit.

6514

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Discover Debit.

6515

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Discover Credit.

6516

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Amex Qualified Credit.

6517

400

Base Rate Surcharge (Qualified) Fees Must Be Equal:Amex Qualified Prepaid.

6518

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: MasterCard Debit.

6519

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: Visa Debit.

6520

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: MasterCard Credit.

6521

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: Visa Credit.

6522

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: Discover Debit.

6523

400

Visa/MasterCard/Discover Discount Fees Must Be Equal: Discover Credit.

6524

400

EMF Revenue is required when using EMF.

6601

400

GENERATED_IN_PRICING_API

6602

400

GENERATED_IN_PRICING_API

6603

400

GENERATED_IN_PRICING_API

6604

400

GENERATED_IN_PRICING_API

6880

400

Governing Master Template Id is required

6881

400

Governing Master Template Id provided is invalid

6882

400

Pay in Month is not allowed

6883

400

Governing Master TemplateId Cannot Be Changed

6901

400

Invalid template.

6902

400

Merchant Number is required for request.

6903

400

Pricing Plan is required for request.

6904

400

No Template With This ID Is Associated With This Hierarchy Node Key.

6905

400

Only One Default Pricing Template Can Be Selected Per Partner

6906

400

No Default Pricing Template Found

6907

404

No Pricing Templates were found for this application

7000

400

First Name is required for request.

7001

400

Last Name is required for request.

7002

400

Street Address is required for request.

7003

400

City is required for request.

7004

400

State is required for request.

7005

400

Zip Code is required for request.

7006

400

Date of Birth is required for request.

7007

400

Valid Date of Birth is required for request.

7008

400

Social Security Number is required for request.

7009

400

Valid Social Security Number is required for request.

7050

400

Valid Pricing Plan is required for request.

7051

400

Valid Equipment is required for request.

8000

400

User does not have any available categories.

8001

400

No report data was returned for request report.

8002

400

User does not have access to requested data.

8003

400

Request contained an invalid parameter.

8004

400

Please only use documentId or documentTypeName query parameters, not both.

8005

400

Year should be 4 digits long and only numbers.

8006

400

Month should be at most 2 digits long and only numbers.

Transaction (Quest) APIs

ACH

ACH Mobile Transactions

  • POST: Credit Transaction

  • POST: Debit Transaction

ACH Provider

  • GET: Get Paya Ach Provider By SecCode

  • GET: Get All Ach Providers For Specific Terminal

ACH Transactions

  • GET: Search for ACH Transactions

  • POST: Post Transaction

  • POST: Post a Credit Transaction

  • POST: Post a Debit Transaction

  • POST: Reversal Transaction

  • POST: Validate ACH Account

  • GET: Get Transaction

  • DELETE: Void Transaction

ACH Vault

  • POST: Create an ACH token

  • GET: Get ACH Token

  • PUT: Update ACH Token

  • DELETE: Delete ACH Token

Android Device Configuration

Android Device Configuration

  • GET: Get Android Device

Batches

Batches

  • GET: Get open batch

  • PUT: Close open batch

Batches Warehouse

  • GET: Get all batches

Gateway Settings

RPS Settings

  • GET: Get RPS Settings

  • POST: Update RPS Settings

  • PUT: Update RPS Settings

HPP Settings

  • GET: Get HPP Settings

  • POST: Create HPP Settings

  • PUT: Update HPP Settings

  • DELETE: Delete HPP Settings

PayLink Settings

  • GET: Get PayLink Settings

  • POST: Create PayLink Settings

  • PUT: Update PayLink Settings

  • DELETE: Delete PayLink Settings

Terminal Settings

  • GET: Get Terminal Settings

  • PUT: Update Terminal Settings

AVS Settings

  • GET: Get AVS Settings

  • PUT: Update AVS Settings

Check Duplicate Transaction Settings

  • GET: getSettings

  • POST: createSetting

  • PUT: updateSetting

CSC Settings

  • GET: Get CSC Settings

  • PUT: Update CSC Settings

Device Settings

  • GET: Get Device Settings

  • POST: Update(?) Device Settings

  • PUT: Update Device Settings

  • DELETE: Delete Device Settings

Transaction Alert Controller

  • GET: getSettings

  • POST: createSetting

  • DELETE: deleteSetting

Report Settings

  • GET: Get Report Settings

  • POST: Update(?) Report Settings

  • PUT: Update Report Settings

HPP Signature Verification Service

HPP Signature Verification Service

POST: Verify HPP Response

Mobile Transactions Using SDKs

Mobile Transactions using SDKs

  • POST: Authorization Transaction

  • POST: Forced Sale Transaction

  • POST: Refund Transaction

  • POST: Sale Transaction

Receipt Service

Receipt Service

  • POST: Post a receipt request

Recurring Payments API

Customer

  • GET: Search Customers

  • POST: Create a Customer

  • GET: Get a Customer's Info

  • PUT: Update a Customer

  • DELETE: Delete a Customer

Customer Token

  • GET: Get Tokens for a Customer

  • POST: Add an existing token to a customer

  • PUT: Update a Token

Customer Token Delete

  • DELETE: Delete a Token

Forecast

  • GET: Get a Plan Forecast

Payment Plans

  • GET: Search Plans

  • POST: Create a Plan

  • GET: Get a Plan's Info

  • PUT: Update a Plan

  • GET: Get a Plan's Expected Runs

  • DELETE: Delete a Plan

Search Payment Transaction

  • GET: Search Payments

Semi-Integrated API Batches (Transaction EMV Batches)

Semi-Integrated Batches

  • PUT: Close open batch

Basic Error Controller

  • GET/error errorHtml

  • HEAD/error errorHtml

  • POST/error errorHtml

  • PUT/error errorHtml

  • DELETE/error errorHtml

  • OPTIONS/error errorHtml

  • PATCH/error errorHtml

Semi-Integrated API Transactions (Transaction EMV)

Transaction EMV

  • POST: Post Transaction

  • POST: Authorization

  • POST: Forced Sale

  • POST: Refund

  • POST: Sale

  • POST: Token Only

Transaction Signature Service

Transaction Signature Service

  • POST: Post a transaction signature

  • GET: Get a transaction signature

Transactions (Gateway Proxy)

  • GET: Search Transactions

  • POST: Authorization Transaction

  • POST: Capture Transaction

  • POST: Forced Sale Transaction

  • POST: Refund Transaction

  • POST: Sale Transaction

  • POST: Void Transaction

  • PUT: Adjust Tip

Vault API (Token Controller)

Token Controller

  • GET: Search Tokens

  • POST: Create a token

  • GET: Get Token

  • DELETE: Delete Token

  • PUT: Update a token

ACH Request Validation & Return Codes

The following articles explain ACH request validation and return codes used for testing purposes:

Webhooks

Webhooks allow you to receive notifications when events occur on a Clearent merchant account or application submission. Instead of repeatedly polling our API to check for changes, Clearent sends HTTP requests directly to your configured endpoint whenever relevant events happen. This approach is more efficient, scalable, and provides immediate updates to your integration.

Webhook Subscriptions

Clearent offers the following webhook subscriptions that provide notifications for different aspects of merchant onboarding and payment processing:

  • Transaction Webhook – Delivers real-time notifications for transaction events.

  • Onboarding Webhooks – Track application status, provides alerts about required fixes, and delivers terminal shipping information.

  • Equipment Tracking & Activation Webhooks - Provide notifications when payment terminals are shipped and enable terminal activation for merchants.

For more information on Clearent's webhooks, refer to the following articles:

Prerequisites

Before you start using Clearent’s Webhooks, ensure you meet the following prerequisites:

Technical Requirements

  • Deploy a publicly accessible HTTPS endpoint that can receive and process webhook payloads

  • Implement proper security measures to validate webhook signatures

  • Set up appropriate error handling and retry logic

Configuration Options

Webhook URLs must be assigned to the account so Clearent can POST events to the correct destination.

Integrated Software Partners

To enable webhooks, you must provide Clearent with your designated webhook URLs. During account setup, Clearent will apply the appropriate webhook configuration.

Note: The setup process differs depending on the webhook type

Virtual Terminal Users

To add a webhook URL:

  1. Navigate to Settings > Terminal

  2. Add your URL to the Transaction Alert Callback URL field

  3. Click Save All to apply your settings

For more information about Virtual Terminal, refer to the following article:

Onboarding Webhooks

The Onboarding Webhooks provide updates throughout the merchant onboarding process. These include application status changes, required fixes, equipment tracking and activation.

For more information, refer to the following related articles:

Overview

What is Merchant Onboarding?

Merchant Onboarding is the process of registering, verifying, and enabling a business to start accepting payments on a payment platform. This involves collecting essential business information, verifying the identity of business owners, and evaluating risks to ensure compliance with legal and financial regulations. It is a crucial first step for seamless integration and efficient transaction processing.

Merchant Onboarding Options

We provide a range of flexible and customizable onboarding solutions tailored to suit different business needs and levels of technical expertise.

  • Automated Merchant Onboarding: A hosted, pre-built onboarding solution by Clearent, designed to streamline merchant onboarding with configurable workflows.

Note: White-label capabilities are coming soon, allowing for UI customization to match your brand

  • Manual Submission via Partner Portal: A simple way to onboard merchants by entering their details into the Partner Portal for review and approval.

  • API Integration: Enables seamless onboarding with direct API connections, providing full control over the user experience.

Choose the option that best fits your use case:

Additional Services

If you prefer a hands-off approach to merchant onboarding, we offer comprehensive support services to streamline the process. Our team can collaborate with you to develop a tailored Go-to-Market Strategy, including sales and marketing planning, to accelerate your business growth, and our experienced specialists can handle the entire merchant onboarding process on your behalf.

This option allows you to focus on your core business while ensuring compliance, reducing risk, and providing a seamless onboarding experience for your merchants.

Merchant Onboarding Process

Regardless of the merchant onboarding method you choose, the onboarding process typically follows these key steps:

  1. Collect Merchant Information (via Merchant Application form)

  2. Sign & Submit (Merchant Application)

  3. Merchant Verification & Underwriting (including Business Verification, Signer Verification, Risk Evaluation)

  4. Request for Additional Information (if needed)

  5. Approval or Rejection of the merchant application

1

Collecting Merchant Information

To begin the onboarding process, we require merchants to provide essential business details through the Merchant Application form. This includes key data like legal business name, address, owner information, and bank account details. The collected information is crucial for verification and compliance checks.

2

Sign & Submit

The next step is for the merchant to review, sign, and submit the application. This typically involves agreeing to the terms of service and providing consent for data verification and risk assessment.

3

Merchant Verification & Underwriting

During this stage, the submitted information undergoes a comprehensive review. The process involves:

  • Business Verification: Confirmation of the legal status and ownership details of the business.

  • Signer (Owner) Verification: Identity checks for business owners, often requiring government-issued ID documentation.

  • Risk Evaluation: Analysis of the business profile to assess creditworthiness and potential risks.

4

Request for Additional Information

If any discrepancies are identified during the verification process, additional details may be requested to resolve outstanding issues. This step is a part of the thorough risk and compliance assessment.

5

Approval or Rejection

Once all checks are completed, the application is either approved or rejected. Approved merchants are then going through the set up process to be ready to start accepting payments. If rejected, the merchant is notified with details for potential resolution or reapplication.

For more information on our Merchant Onboarding solutions, refer to the following documents:

Equipment Tracking

The Equipment Tracking webhook provides notifications when payment terminals are shipped to merchants. This webhook delivers detailed shipping information for each terminal device, including tracking numbers.

Payload Format and Example

The webhook delivers a JSON payload with the following structure:

Field Reference

Equipment Activation

This article describes the Equipment Activation webhook callback process, which enables payment terminal activation for merchants. The Activation Webhook allows clients to notify the activations-service when terminal activations are ready to be processed. The service then forwards API keys to the merchant's endpoint.

Endpoint Details

Request Format

The endpoint accepts a request with the following components:

  • merchantId as a URL parameter

  • JSON body containing an external identifier

Example Request Body

Note: The externalId is typically initiated through the Partner Portal.

Process Flow

When the service receives a callback request, it:

  1. Validates that an equipment order exists for the specified merchantId

  2. Retrieves the merchant URL for the given merchantId

    1. If no merchant URL is found, it returns the URL of the parent HNK

  3. Forwards API keys for terminals in the placed order to the merchant URL

  4. Records the callback in the ActivationDetails table of the Equipment database

Callback to Merchant

The service sends a POST request to the merchant URL with API keys for each terminal in the order.

Example Callback Payload

Response Codes

Equipment Tracking & Activation

The Equipment Tracking & Activation webhooks deliver notifications about payment terminal shipments and activation events. These webhooks enable you to track terminal deliveries and manage the activation process for your merchants.

For more information, refer to these related articles:

Automated Merchant Onboarding

Clearent’s Automated Merchant Onboarding solution offers a lightweight and efficient way of adding new merchants, where Clearent handles much of the user experience. With streamlined onboarding and automated payment processing, businesses can quickly and efficiently integrate new merchants. This solution eliminates the need for complex development or manual paperwork, ensuring a hassle-free onboarding process.

Note: Automated Merchant Onboarding was previously known as Launch for Integrator (L4I). You might still see references to L4I in some systems or materials.

For more information on the Automated Merchant Onboarding solution, refer to the following articles:

The provide a complete solution for onboarding merchants. It allows integrators to manage the merchant sign-up experience and ensure a smooth process.

This document provides an overview of the various available in our system, categorized by their functionality and purpose. Each API serves a specific role in managing different aspects of merchant operations, transactions, and configurations.

The Automated Merchant Onboarding Setup API () provides a lightweight method to add new merchants to the Clearent platform. We manage most of the user experience, simplifying the integration process.

The allows developers to access transaction data and generate reports programmatically. Use it to integrate transaction data with your existing systems and automate reporting.

The following are the result codes returned by the .

The are RESTful APIs that provides flexibility and control over payment processing. Use it to integrate payments into your point-of-sale (POS) system while reducing PCI scope and enhancing security with tokenization. It also supports in-person payments with encrypted card readers.

with us to know more.

Field
Description
Item
Value
Status Code
Meaning
Description

Boarding APIs
APIs
Merchant Onboarding APIs
Quest APIs
Automated Merchant Onboarding Setup API (Launch For Integrators Setup API)
Reporting API
Launch For Integrators Setup API
Reporting API
Merchant Onboarding APIs
Transaction (Quest) APIs
ACH Request Validation Codes
ACH Return Codes
Prerequisites
Transaction Webhook
Onboarding Webhooks
Equipment Tracking & Activation Webhooks
Virtual Terminal
Application Status
Application Fixes
Equipment Tracking & Activation
{
  "event": "Shipped",
  "merchantId": "88880000000123456",
  "orderId": "999990000000987654",
  "payload": {
    "terminals": [
      {
        "name": "Survey Name",
        "trackingNumber": "1Z81T8T20299581550",
        "deviceType": "VP3300 (Bluetooth)",
        "terminalId": 1111,
        "storeNumber": 1111
      }
    ]
  }
}

event

Identifies the webhook event type ("Shipped")

merchantId

Unique identifier for the merchant receiving the equipment

orderId

Unique identifier for the equipment order

payload.terminals

Array of terminal devices included in the shipment

payload.terminals[].name

Display name or description of the terminal

payload.terminals[].trackingNumber

Shipping tracking number

payload.terminals[].deviceType

Model and connection type of the terminal

payload.terminals[].terminalId

Unique identifier for the terminal device

payload.terminals[].storeNumber

Store location identifier where the terminal will be deployed

Service

activations-service

HTTP Method

POST

URL Path

/activations/{merchantId}/callback

Parameters

merchantId (URL parameter)

{
  "externalId": "12345"
}
{
    "externalIdentifier": "12345",
    "merchantAccountNumber": "6588000001234567",
    "keys": [
    {
       "type": "cnp",
       "productName": "Pi Technologies (ASeries)",
       "apiKey": "abc16ed42a9a99dd1f7890e4f00",
       "terminalid": "80608483",
       "publicKey": "301406072a8648ce3d0201060....459a12d5780d65e5a7a624a4ca005"
    }
 ]
}

200 (OK)

Success

The activation process completed successfully (no response payload)

424 (Failed Dependency)

Failure

The activation process failed (no response payload)

Configuring Automated Merchant Onboarding

The Automated Merchant Onboarding solution offers various configuration options to customize the merchant onboarding experience, ensuring seamless integration with your business operations. These settings help you tailor branding, communication, user management, and merchant support, creating a streamlined and efficient onboarding process.

Branding Options

Add Logo: Enhance brand recognition by adding your company’s logo to the onboarding interface. A branded experience builds trust and ensures consistency across all touchpoints, giving merchants a familiar and professional environment.

Communication Settings

Set a Postback URL: Define a Postback URL to receive real-time updates on merchant application status changes. This ensures that onboarding-related events—such as application approval, decline, or completion—are automatically communicated to your system, enabling timely and seamless updates.

Modify Support Contact Information

Customize the support email and phone number displayed in automated emails sent during the merchant application process. This ensures that merchants always have the correct contact details when they need assistance.

User Management

Automatically Create User Accounts: Enable automatic user account creation for the Merchant Portal and Virtual Terminal to simplify onboarding. This eliminates manual setup and ensures that merchants gain immediate access to their accounts upon approval.

Reminder Email Configuration

Set Automatic Reminder Intervals: Configure automated reminder emails to encourage merchants to complete their applications before the 7-day expiration period. The default reminder is sent 3 days before expiration, with options to send additional reminders 2 days or 1 day prior.

Application Completion

Predefine Completion of Application Field: Consult with a Clearent representative to determine the best strategy for defining application completion. This ensures that onboarding requirements align with your business model and industry standards.

Get in touch
Automated Merchant Onboarding
Merchant Onboarding via Partner Portal
Merchant Onboarding via API
Equipment Tracking Webhook
Equipment Activation Webhook
Prerequisites
Working with Automated Merchant Onboarding
Merchant Onboarding Status Webhooks
Configuring Automated Merchant Onboarding

Product

Objective

Utilize a pre-built, configurable onboarding application to streamline merchant setup.

Manual data entry and submission through an existing portal.

Onboard new merchants using API integration.

Recommended For

Integrators seeking a hassle-free, low-code solution with minimal integration effort. Ideal for those needing a quick-to-deploy platform for merchant setup, whether remote (via mobile, tablet, laptop) or in-person.

Integrators who prefer a manual, straightforward approach with no API integration.

Integrators who want complete control over the user experience and data flow.

Integration Effort

Low.

None.

High.

Development Effort

Minimal development required, leveraging a pre-built platform.

No development required; uses existing portal for setup.

Requires full development work to design and manage the onboarding flow.

Customization Flexibility

Various configuration options are available, including application questions (visibility & editability) and customizable Equipment Surveys. Note: UI brand customization is coming soon.

No customization; uses standard portal with fixed features.

Full flexibility to design, modify, and control every part of the onboarding experience.

Modifying Default Merchant Pricing

Automated Merchant Onboarding offers flexible pricing options, enabling software partners to modify predefined pricing structures to match their business needs and sales strategies. Instead of using a static pricing model, software partners can retrieve existing pricing templates, modify fees, and apply customized pricing plans at the merchant level.

For more information on modifying default merchant pricing, refer to the following articles:

Modifying Pricing Fees & Completing Merchant Application Record

  • Assign a pricing plan to the merchant.

  • Modify the pricing fees under the selected plan.

  • Complete the merchant application process with the required pricing details.

Adjusting pricing at this stage ensures that each merchant receives a tailored pricing structure that aligns with their business requirements.

This includes the following steps:

1

Submit Merchant Pricing Details

To onboard a merchant and apply pricing fees, send a POST request with the pricing details.

  • API Endpoint:

POST /api/launchIntegratorSetup/v1.0/integrateMerchant/{hierarchyNodeKey}

  • Path Parameter: hierarchyNodeKey - It identifies the hierarchy level under which the merchant is being onboarded.

{
  "pricingPlan": {
    "pricingFees": [
      {
        "clearentPricingFeeID": 101,
        "pricingFeeDescription": "Transaction Fee",
        "rate": 2.5,
        "fee": 0.30,
        "payInMonth1": 12,
        "payInMonth2": 24
      }
    ],
    "pricingPlanID": 2001,
    "pricingPlanTemplateID": 3001,
    "pricingTypeCode": "STANDARD",
    "isAdvancedPricing": true,
    "isEMF": true,
    "isDailySettle": true,
    "includeAssessments": true
  }
}
2

Understand the API Response

A successful response confirms that the pricing plan has been applied and returns the merchant’s pricing details.

{
  "merchantNumber": "123456789",
  "status": "Active",
  "pricingPlan": {
    "pricingFees": [
      {
        "clearentPricingFeeID": 101,
        "pricingFeeDescription": "Transaction Fee",
        "rate": 2.5,
        "fee": 0.30,
        "payInMonth1": 12,
        "payInMonth2": 24
      }
    ],
    "pricingPlanID": 2001,
    "pricingPlanTemplateID": 3001,
    "pricingTypeCode": "STANDARD",
    "isAdvancedPricing": true,
    "isEMF": true,
    "isDailySettle": true,
    "includeAssessments": true
  },
  "message": "Merchant pricing plan successfully applied."
}

After the successful modification of the pricing plan, the merchant application record is updated, and the new pricing structure is applied automatically. This ensures that merchants receive the correct pricing without requiring manual intervention.

Generating a Merchant Application

Note: The following steps are performed by the Partner, who is responsible for collecting merchant details and initiating the onboarding process.

To generate a merchant application:

1

Create a Merchant Application

To initiate merchant onboarding, collect the required details during your sign-up process. This includes the merchant’s email, business name, and Merchant Category Code (MCC).

{
    "merchantInformation": {
        "dbaName": "Stark Industries",
        "emailAddress": "tstark@starkindustries.com"
    },
    "salesProfile": {
        "mccCode": "5085"
    }
}

With these basic details, a merchant can initiate the onboarding process. The Automated Merchant Onboarding tool allows merchants to onboard into the system with minimal input, reducing integration efforts and streamlining the application process.

{
    "merchant": {
        "merchantInformation": {
            "dbaName": "Stark Industries",
            "merchantNumber": "6588949992012345",
            "emailAddress": "tstark@starkindustries.com",
            "website": “starkindustries.com”,
            "phones": null,
            "acceptsPaperStatements": false,
            "acceptsPaperTaxForms": false,
            "companyTypeId": 0,
            "seasonalSchedule": null,
            "salesInformation": null
        },
        "mailingAddress": null,
        "physicalAddress": null,
        "bankAccounts": null,
        "businessContacts": null,
        "salesProfile": {
            "useExtraCnpValidation": true,
            "mccCode": "5085",
            "cardPresentPercentage": 0.0,
            "motoKeyedPercentage": 0.0,
            "eCommercePercentage": 0.0,
            "returnRefundPolicy": null,
            "productsSold": null,
            "previouslyAcceptedPaymentCards": false,
            "previouslyTerminatedOrIdentifiedByRiskMonitoring": false,
            "reasonPreviouslyTerminatedOrIdentifiedByRisk": null,
            "currentlyOpenForBusiness": false,
            "annualVolume": 0.0,
            "averageTicket": 0.0,
            "highTicket": 0.0,
            "ownsProduct": false,
            "ordersProduct": false,
            "sellsFirearms": false,
            "sellsFirearmAccessories": false,
            "futureDeliveryTypeId": null,
            "otherDeliveryType": null,
            "futureDeliveryPercentage": 0.0,
            "fireArmsLicense": null,
            "cardBrands": null,
            "ebtNumber": null,
            "amexMID": null,
            "sellsCBD": false,
            "cbdSalesTypeID": null,
            "salesProfileCBD": null
        },
        "taxpayer": null,
        "externalCustomerId": null,
        "pricingPlan": {
            "pricingFees": [
                {
                    ...
                }
            ],
            "pricingPlanID": 13539,
            "pricingPlanTemplateID": 1060,
            "pricingTypeCode": "D",
            "isAdvancedPricing": false,
            "isEMF": false,
            "isDailySettle": true,
            "includeAssessments": false
        }
    },
    "applicationURL": "https://boarding-sb.clearent.net/launch-integrator-setup/merchant/4c87c74b-a483-4d4f-8656-b412345abcde",
    "errors": [],
    "metadata": {
        "exchangeId": "ID-clearent-security-edge-proxy-service-2-64e45785-eedd-40ae-a580-7d7709930004",
        "timestamp": "2024-06-28T15:10:53.7273247Z"
    }
}
2

Redirecting to the Application URL

After generating the application, the system generates an Application URL. You can either redirect the merchant automatically or send the link via email for them to complete the process.

{
…
"applicationURL": "https://boarding-sb.clearent.net/launch-integrator-setup/merchant/4c87c74b-a483-4d4f-8656-b46a59e2e3d4",
…
}

Once redirected, the merchant lands on the Automated Merchant Onboarding hosted application page, where they can enter additional details, verify their identity, and sign required documents digitally, ensuring a fast and seamless onboarding experience.

The applicant has seven days from the creation date to complete the application. If the application is not completed within seven days, the application will expire, and a new application will need to be created and completed.

Completing the Application

Note: The following steps are performed by the Merchant. After receiving the application link, the Merchant completes and submits their application through the Automated Merchant Onboarding tool.

To complete a merchant application:

1

Set an Acceptance PIN

To protect sensitive merchant data, Automated Merchant Onboarding requires users to set a 4-digit security PIN when starting an application. This PIN prevents unauthorized access to in-progress applications.

If the application session is abandoned, users must enter their previously created PIN to resume the process. After entering the PIN, they can click Continue to proceed with the application.

2

Enter an Existing PIN

If a user returns to an incomplete application, they will be prompted to enter their previously configured PIN to continue from where they left off.

3

Reset an Invalid or Forgotten PIN

If the PIN entry is invalid or forgotten, users can click Forgot PIN? to reset it.

After selecting Forgot PIN? users will receive a reset link via email. Clicking the reset link invalidates the old PIN and prompts the user to create a new PIN before accessing the application.

The PIN reset email is sent to the primary email address provided in the emailAddress object within the merchantInformation array during the initial merchant creation request to the Automated Merchant Onboarding web service.

When users click the reset link, they will be redirected to the Automated Merchant Onboarding application to create a new PIN. Once set, they can continue the application from where they left off.

4

Completing the Application

Automated Merchant Onboarding ensures data integrity and security by validating all submitted information before finalizing the application. The platform performs comprehensive input validation, checking data formats like email addresses and phone numbers and verifying that inputs meet the required criteria.

These security measures help maintain accuracy, compliance, and a smooth user experience throughout the onboarding process.

5

Signing the Merchant Agreement

Each designated contact signer must provide electronic consent before signing application documents. This consent enables the use of digital signatures and electronic records, replacing traditional paper-based processes.

Once the user reviews and agrees to the terms, they can sign electronically to confirm their acceptance of the agreement.

6

Finalizing Application Terms

After providing consent, users can proceed to review and sign all required application documents. Automated Merchant Onboarding guides them through the process, ensuring all necessary steps are completed.

Once the application is finalized, users can be automatically redirected to a designated URL for a seamless transition. This feature allows businesses to guide users to a confirmation page, additional resources, or any custom destination, optimizing the onboarding journey.

Working with Automated Merchant Onboarding

Working with Automated Merchant Onboarding involves:

Retrieving Existing Pricing Templates

To modify merchant pricing, you must first retrieve the available pricing templates from the Automated Merchant Onboarding system. These templates define different pricing structures, which can be assigned to merchants based on their business model and service requirements.

This includes the following steps:

1

Fetch Available Pricing Templates

  • API Endpoint: GET /api/pricing/v2/PricingPlan/{merchantNumber}/templates

  • Request Parameter: merchantNumber - It identifies the merchant whose pricing templates need to be retrieved.

2

Understand the API Response

A successful response provides a list of available pricing templates, allowing integrators to select the most suitable plan for each merchant.

[
    {
      "pricingPlanTemplateID": 101,
      "hierarchyNodeKey": "987654321",
      "templateName": "Standard Pricing Plan",
      "pricingTypeCode": "STANDARD",
      "isAdvancedPricing": false,
      "isDefaultTemplate": true,
      "isDisabled": false,
      "templateFees": [
        {
          "clearentPricingFeeID": 2001,
          "clearentPricingFeeDescription": "Transaction Fee",
          "isEditable": true,
          "isRequired": true,
          "isVisible": true,
          "isFee": true,
          "isRate": true,
          "isPayInMonthRequired1": false,
          "isPayInMonthRequired2": false,
          "defaultRate": 2.5,
          "minRate": 2.0,
          "maxRate": 3.5,
          "defaultFee": 0.30,
          "minFee": 0.25,
          "maxFee": 0.50,
          "rateLabel": "Percentage Rate",
          "feeLabel": "Fixed Fee"
        }
      ],
      "templateSettings": [
        {
          "pricingPlanSettingID": 5001,
          "settingName": "Daily Settlement",
          "description": "Enable daily settlement for transactions.",
          "isVisible": true,
          "isEditable": true,
          "defaultValue": true
        }
      ],
      "attributes": [
        {
          "name": "Region",
          "value": "USA",
          "type": "String"
        },
        {
          "name": "Currency",
          "value": "USD",
          "type": "String"
        }
      ]
    }
]

Starting New Application

The Merchant’s Onboarding begins with creating a new application in the Partner Portal. To create a new merchant application in the Partner Portal:

1

Access the Applications Page

  • Log in to the Partner Portal.

  • In the header menu, select Applications to navigate to the merchant applications page.

2

View and Filter Existing Applications

  • The Applications page displays all merchant applications with statuses such as Pending, In Progress, and Submitted.

  • Use the Search bar to find specific applications.

  • Select Filters to refine your search based on application status.

3

Start a New Application

  • Select Start New Application in the top-right corner.

  • You will be redirected to the Hierarchy page, where you can enter merchant details.

Adding Hierarchy & Compensation Details

Hierarchy and Compensation Details ensures that the merchant is correctly classified within the organization and compensation preferences are set.

1

Enter DBA Name

  • In the DBA (Doing Business As) Name field, enter the merchant’s business name.

Note: Ensure that the name follows the required format and does not contain invalid characters.

2

Select Service Organization/Hierarchy

  • Click inside the Choose a Service Organization/Hierarchy field.

  • Use the search icon to find and select the appropriate service organization.

3

Specify Merchant Type

  • Check the box if the merchant belongs to a chain.

  • Select whether the business operates as Brick & Mortar or E-commerce.

4

Declare Product Sales Information

  • Indicate if the business sells CBD products or other goods associated with Clearent’s CBD program by selecting one of the available options.

  • If the business does not sell CBD products, select No.

5

Set Compensation Preferences

  • Choose how you would like to be compensated upon the completion of the onboarding process:

    • All Residual: Receive ongoing residual payments.

    • Signing Bonus with Residual: Get a one-time bonus along with residuals.

6

Enter Additional Merchant Identifiers (Optional)

  • If applicable, enter a Referral Partner name.

  • To associate this merchant with an external system, enter:

    • SFOpportunityId (Salesforce Opportunity ID)

    • ExternalCustomerId (Customer ID from another system)

Entering Business Information

The Business Information page collects essential details about the merchant’s business, including address, contact details, legal information, and operational status.

1

Enter Business Identification Details

  • In the DBA (Doing Business As) Name field, enter the merchant’s business name.

  • Click on Select MCC to search and choose the appropriate Merchant Category Code (MCC).

2

Provide Business Address

  • Under Physical Address, enter:

    • Street Address

    • Apt, Suite, Etc. (Optional)

    • City

    • State (Select from the dropdown menu)

    • Zip Code

  • If the Mailing Address is the same as the physical address, check the box. Otherwise, enter the mailing address details separately.

3

Enter Contact Information

  • Enter the Business Phone Number.

  • Enter the Fax Number (if applicable for chargebacks).

  • Enter the Business Email Address.

  • Enter the Business Website (if available).

4

Configure Email Preferences

  • Check the box if the merchant wants to receive statements via email.

  • Check the box if the merchant prefers to receive tax forms via email.

5

Provide Legal Information

  • Select the Ownership Type from the dropdown (e.g., Sole Proprietor, LLC, Corporation).

  • Enter the Legal First Name and Legal Last Name of the business owner.

  • If the Federal Tax ID is the signer’s Social Security Number (SSN), check the box. Otherwise, enter the Federal Tax ID manually.

  • Select the State of Incorporation from the dropdown menu.

6

Specify Payment Processing Information

  • Select whether the business accepts or has previously accepted payment cards (Yes/No).

  • If Yes, choose the Payment Processor from the dropdown menu.

  • If the business has been previously terminated by a card brand or processor (e.g., Visa), select Yes and provide a Reason for Termination.

7

Define Business Operations

  • Select whether the business is currently open (Yes/No).

  • Indicate if the business operates seasonally (Yes/No).

  • If the business is seasonal, select the months of operation.

Merchant Onboarding Status Webhooks

The Automated Merchant Onboarding solution allows software partners to track their merchants' application progress using Application Status webhooks. By subscribing to these webhooks, integrators receive updates on any changes to a merchant’s application status. This eliminates the need for manual follow-ups and provides a seamless, automated tracking system.

For more information on merchant onboarding status webhooks, refer to the following document:

Merchant Onboarding via Partner Portal

The Partner Portal simplifies merchant onboarding with a structured, step-by-step approach, ensuring accuracy, compliance, and efficiency. Below is a Clearent-focused breakdown of the Merchant Onboarding Process, guiding partners from application submission to final approval.

The following articles detail the steps for successfully onboarding merchants through the Partner Portal:

Configuring Pricing Details

The Pricing section allows you to configure the merchant's pricing model, card type acceptance, fees, and other settlement-related details.

1

Select Card Types to Accept

  • Choose the card types that the merchant will accept for transactions:

    • Visa

    • MasterCard

    • Discover

    • American Express (Choose between OptBlue or Direct)

    • Pin Debit

    • EBT (Electronic Benefits Transfer)

2

Select Pricing Method/Program

  • Choose the Pricing Method/Program from the dropdown menu (e.g., IC Plus Standard – ISO).

3

Configure Card Association Assessment and Fees

  • Select Yes/No for Passthrough card association assessment and fees.

4

Set Card Type/Settlement Fees

Enter the fee values for each card type:

  • Visa Credit & Debit Discounts (Percentage and Per Item Fee)

  • MasterCard Credit & Debit Discounts (Percentage and Per Item Fee)

  • Discover Credit & Debit Discounts (Percentage and Per Item Fee)

  • Pin Debit – Choose whether to pass through network fees (Yes/No) and enter the applicable percentage and per-item fee.

5

Additional Fees & Discounts

Enter applicable fees, if any, such as:

  • PCI Non-Compliance Fee Revenue

  • Annual Fee

  • Semi-Annual Fee

  • First and Second Month Fees

  • AVS Transaction (Surcharge)

  • Chargeback Item Processing

  • Retrieval Item Processing

  • Monthly Minimum Discount

  • Voice Authorization Fee

  • Application Processing Fee

6

Other Fees

  • IVR Authorization Fee

  • Non-Supported Help Desk Call Fee

  • Monthly Paper Statement Fee

  • Monthly Compass Online Reporting Fee

  • Merchant Regulatory Fees

  • Batch Processing Fees

  • Debit Access Fee

7

3rd Party/Other Fees

  • Clearent does not bill these fees directly; they are for display only.

  • Enter details such as:

    • Annual Fee

    • Monthly Fee

    • Transaction Fee

    • Setup Fee

8

Save and Proceed

  • Click Save to apply the pricing settings.

  • Click Next to continue to the Banking Information section.

Conducting the Site Survey

The Site Survey step ensures that the merchant's physical location and business operations are verified before onboarding. This step is crucial for compliance and fraud prevention.

1

Confirm Survey Method

  • Select the checkbox to confirm if the site survey is in person (physical inspection of business location).

2

Select the Main Merchant Location

  • Choose the appropriate option for the merchant's business location:

    • Brick & Mortar – A physical storefront.

    • Tradeshow – A temporary or mobile merchant setup at events.

    • Residence – A home-based business.

    • Other – Any other type of business location.

  • If Other is selected, enter the business location details in the Other Location text field.

3

Verify Government-Issued ID

  • Select the checkbox to confirm that the merchant’s Valid government-issued ID has been reviewed and verified.

4

Verify Inventory Matches Business Operations

  • Select the checkbox Inventory matches the products/services sold to confirm that the merchant's inventory aligns with the declared business type.

5

Agree to Verification Terms

  • Read the verification statement to confirm that the site has been inspected or verified remotely.

  • Then select Yes, I agree to these terms to acknowledge the verification.

6

Save and Proceed

  • Click Save to store the site survey details.

  • Click Next to proceed to the Pricing Details page.

Adding Equipment

The Equipment section allows users to order and manage the necessary equipment for payment processing. Merchants can request equipment, track existing orders, and update their selections as needed. This step ensures that the merchant has the required hardware to support their payment transactions.

1

Navigating to the Equipment Page

  • After completing the Banking Information step, you will be directed to the Equipment page.

  • The page displays any open equipment orders associated with your account.

  • If you need to add new equipment, click the "Add Equipment" button located on the right side of the screen.

2

Adding Equipment

Upon clicking "Add Equipment", you will be directed to the Add Equipment form.

  • Selecting Equipment:

    • In the "Equipment Type" field, click on the search bar and select the required equipment type from the available options.

    • Enter the Quantity of the selected equipment in the provided dropdown field.

    • Click "Next" to proceed.

  • Reviewing Equipment Request:

    • Verify that the selected equipment type and quantity are correct.

    • If changes are needed, click the "Back" button to return to the previous screen.

    • Once confirmed, click "Submit" to finalize the equipment request.

3

Managing Equipment Orders

  • After submitting your request, you will be redirected to the Equipment page.

  • The newly requested equipment will now appear in the list of open equipment orders.

  • The Tracking column will display tracking information once the equipment is shipped.

  • If you need to modify an existing equipment order, navigate to the "Update Existing Equipment" tab.

Adding Banking Information

The Banking Information step allows users to securely add and manage bank accounts for transactions, including deposits, fees, and chargebacks. This step ensures that the merchant's banking details align with their legal business name or DBA (Doing Business As) name.

1

Accessing the Banking Page

  • After completing the pricing step, users will be directed to the Banking page.

  • To add a new bank account, click on the Add Bank button.

  • This action will open the Add a Bank Account (Checking) form.

2

Adding Bank Account Details

  • Bank Name: Enter the name of the bank where the merchant’s account is held.

  • Is the Merchant’s Account Under a Legal Name or DBA?

  • Select whether the bank account is listed under the Legal Name, DBA, Residence, or Other.

  • Name on Account: Enter the name as it appears on the bank account.

  • Routing Number: Provide the bank routing number.

  • Checking Account Number: Enter the checking account number.

  • Select Account Use: Check the boxes that apply to the usage of the bank account:

    • Deposits

    • Fees

    • Chargebacks

  • Click on the Save button to store the bank account details.

Note: If needed, users can add multiple bank accounts by repeating the process.

3

Viewing and Managing Bank Accounts

Once the bank information is saved, users will be redirected to the Banking Information page, where they can:

a. View Added Bank Accounts: A table displays the following details for each saved bank account:

  • Bank Name

  • Status (e.g., Pending Review, Approved, etc.)

  • Name on Account

  • Routing Number (partially masked for security)

  • Checking Account Number (masked for security)

  • Uses (Fees, Deposits, Chargebacks)

b. Edit or Delete Bank Information:

  • Click Edit to modify banking details.

  • Click Delete to remove an existing bank account.

c. Confirm Banking Agreement

  • Users must check the box confirming that the name on the bank account matches the merchant’s legal name or DBA name before proceeding.

Submitting Signature

The Signature Submission step is a crucial part of the merchant onboarding process in the Partner Portal. This step ensures that all necessary contacts and authorized signers are recorded for compliance and verification purposes.

1

Accessing the Signature Submission Page

  • Navigate to the Partner Portal.

  • Select Signatures from the top navigation menu.

  • The Signature Submission page will be displayed, allowing you to add a new contact.

2

Adding a New Contact

To add a new contact, follow these steps:

  • Enter Personal Details:

    • First Name

    • Last Name

    • Date of Birth

    • Social Security Number (SSN) (if applicable)

  • Select Contact Type:

    • Signer (Must be an individual with control of the business)

    • Owner

    • General Contact

  • Provide Contact Information:

    • Email Address

    • Phone Number

    • Fax (optional)

  • Enter Address Details:

    • Home Address

    • City

    • State

    • Zip Code

    • Country

  • Select Representation for Contact:

    • Compass User

    • Primary Contact

  • Additional Information:

    • Title

    • Country of Citizenship

3

Saving Contact Information

Once all required fields are completed:

  • Review the entered information for accuracy.

  • Click Save & Add Contact to submit the details.

Once you have selected a pricing template, you can apply and modify the pricing fees before finalizing the merchant application. Use the endpoint to:

To further optimize the onboarding process, include all essential information upfront when passing data to the associated API (). By providing comprehensive client-specific details in the POST request, you ensure that the generated application URL is pre-filled with relevant data. This minimizes redundant data entry for merchants, accelerates the onboarding process, and reduces potential delays.

The API () enables integrators to fetch a list of available pricing templates associated with a merchant, which can be used as a base for further modifications.

To retrieve the pricing templates for a specific merchant, send a GET request to the . This will return a list of all pricing templates that are currently available for the merchant.

Automated Merchant Onboarding
Manual Submission via Partner Portal
Merchant Onboarding via API
Retrieving Existing Pricing Templates
Modify Pricing Fees and Completing Merchant Application Record
Create a Merchant
Launch for Integrators API
Generating a Merchant Application
Completing the Application
Modifying Default Merchant Pricing
Pricing Plan API
Pricing Plan API
Webhooks
Starting New Application
Adding Hierarchy and Compensation Details
Entering Business Information
Entering Profile Details
Conducting the Site Survey
Configuring Pricing Details
Adding Banking Information
Adding Equipment
Submitting Signature
Reviewing & Submitting Application
Viewing Application Summary

Test Cards & ACH Accounts

To help you validate your integration, you can use the following test card and ACH account details to run transactions in the sandbox environment.

Note: Use test cards and test ACH account only in the sandbox environment.

Test Cards

Card Type
Card Number
Expiration Date
Security Code
Billing Zip Code

Visa

4012 0000 9876 5439

MM/YY -any future date

999

85284

MasterCard

5499 7400 0000 0057

MM/YY -any future date

998

85284

MasterCard

2223 0000 4840 0011

MM/YY -any future date

998

85284

AMEX

3714 496353 92376

MM/YY -any future date

9997

85284

Discover (use to test Surcharge- Credit)

6011 0009 9302 6909

MM/YY -any future date

996

85284

Diners

3055 155515 1618

MM/YY -any future date

996

85284

JCB

3530 1420 1994 5859

MM/YY -any future date

996

85284

ACH Test Account

Routing Number
Account Number

490000018 (New provider- use for new sandbox setups) Test transactions under $25

Any digits

Merchant Onboarding via API

For more information on the Merchant Onboarding API solution, refer to the following articles:

Understanding Integration

Clearent uses an API-driven workflow to onboard new merchants. This automated process streamlines the workflow from application submission to equipment activation, helping merchants get started quickly.

The following image and step-by-step guide outline the integration flow:

1

Merchant Data Collection

Merchant onboarding begins with Merchant Data Collection, where the integrator collects and submits essential details using the Integrator UI. This interface integrates with Clearent’s backend systems to create and manage merchant profiles.

APIs Used:

Once the data is submitted, Clearent’s system validates the provided details and returns responses for verification.

2

Data Validation and Correction

Key Validations Include:

  • Business Contact Validation: Verifies business ownership details and information.

  • Bank Validation: Confirms banking details to prevent transaction errors.

These validations ensure that all merchant information is accurate and ready for processing.

To enable corrections based on webhook notifications, we recommend following these steps:

  1. Implement webhook consumption to receive notifications

  2. Display the notifications to merchants in a user-friendly format

  3. Collect the updated data from merchants

  4. Submit the corrected data using the same APIs used during the Merchant Data Collection process

  5. Proceed with the Sign Application and Submit Application steps

Note: Merchants can still proceed even if corrections are not made immediately.

APIs Used:

3

Merchant Agreement and Application Submission

Merchants review their applications, sign agreements electronically, and submit the finalized application. Clearent logs terms, IP addresses, and timestamps to ensure transparency.

  • Electronic Signature Submission: Merchants sign agreements electronically to streamline the process.

    Document Upload Alternative: Pre-signed agreements can also be uploaded for verification.

APIs Used:

4

Automated Underwriting and Decisioning

Once the application is submitted, Clearent triggers a Webhook URL again to start the underwriting process. The Automated Underwriting system evaluates the merchant’s risk and compliance. There are three possible outcomes:

  • Approval: The merchant passes underwriting and moves to the equipment setup phase.

  • Manual Review: Additional verification may be required, such as further documentation or business validation.

  • Decline: The application is rejected if the merchant does not meet compliance or risk thresholds.

5

Equipment Setup and API Key Integration

For approved merchants, Clearent configures the necessary payment hardware and provides API keys for seamless system integration.

Automated Equipment Setup (Quest/TSYS):

  • Configures merchant hardware, such as POS systems and card readers.

  • Assigns API Keys for merchants integrating Clearent’s payment processing system.

Step 5.1: Run Card-Not-Present (CNP) Transactions

From this stage, merchants can begin processing Card-Not-Present (CNP) transactions, such as online, phone, or virtual payments, after their profile is created and data is validated.

Note: CNP transactions don’t require physical equipment. Once data validation and underwriting are complete, merchants can start accepting remote payments.

6

Equipment Shipping and Activation

After approval, equipment is shipped and pre-configured for immediate use. Merchants can activate the equipment and begin in-person transactions.

Stage 6.1: Run Card-Present (CP) Transactions

After receiving and activating equipment, merchants can process Card-Present (CP) transactions in-store using devices like card readers or POS terminals.

Note: CP transactions require functional hardware. Once activated, merchants can immediately start in-person payment processing.

Reviewing & Submitting Application

The Review & Submit step is the final stage of the merchant onboarding process in the Partner Portal. This step allows users to verify all entered details, resolve any outstanding errors, and submit the application for approval.

1

Accessing the Review & Submit Page

  • Navigate to the Partner Portal.

  • Click on Review & Submit in the top navigation menu.

  • The Review & Submit page will be displayed, showing any errors that need resolution and a list of required submission documents.

2

Resolving Errors

If there are any outstanding errors preventing submission, they will be displayed under the Errors to Resolve section. Users must review and correct these errors before proceeding. Common errors may include:

  • Invalid characters in business contact names.

  • Missing required signatures for sections such as Merchant Agreement, Personal Guarantee, Bank Disclosure, and W-9.

  • Missing electronic signature agreements.

  • Missing required equipment validation.

Once all issues are addressed, the system will allow resubmission.

3

Reviewing Submission Documents

Below the Errors to Resolve section, users will find the Submission Documents panel. This displays the status of essential documents:

  • Application (✔ / ❌)

  • Personal Guarantee (✔ / ❌)

  • Bank Verification (✔ / ❌)

To upload any missing documents:

  • Click the Add a Document button.

  • Select and upload the required file.

  • Ensure all documents are successfully added.

4

Reviewing Merchant Information

At the bottom of the page, merchant-related details such as Service Organization, Compensation Type, and Referral Partner will be displayed. If necessary, users can edit this information:

  • Click Edit Info.

  • Make the necessary updates.

  • Save the changes.

5

Submitting the Application

After resolving all errors and ensuring all required documents are uploaded:

  • Review all information for accuracy.

  • Click the Submit button.

  • The application will be sent for processing and approval.

Once submitted, the application will be reviewed by the system. Users may receive notifications regarding the approval status or additional actions required.

Note: Ensure all steps are completed accurately to avoid delays in the approval process.

Prerequisites

Required Information

To begin the onboarding process with Clearent's API, merchants need two key elements:

  • Secret Access Key: A unique key provided by Clearent to securely authenticate API requests.

  • Unique Merchant Identifier (MID): The ID associated with the merchant application, unique for each merchant and environment.

Available Environments

Clearent offers two distinct environments to support merchant onboarding:

  • Sandbox: A secure testing environment for development and integration before going live.

  • Production: The live environment for processing real-world transactions once the merchant has successfully completed the onboarding process.

For more information, refer to the following article:

Key Features

Clearent's Onoarding API empowers merchants with programmatic control over the entire onboarding journey. Its key features include:

  • Secure Access: All API requests are authenticated using the Secret Access Key and MID, ensuring robust security throughout the onboarding process.

  • Multiple Endpoints: Dedicated endpoints are available for each stage of the onboarding process, enabling precise control over the data provided and allowing merchants to tailor their onboarding experience to specific needs.

Viewing Application Summary

The Application Summary page provides an at-a-glance view of the merchant application’s progress in the Partner Portal. This page allows users to track the status of different sections, access merchant details, and manage the application as needed. Users can download the application or delete it if required.

1

Accessing the Application Summary Page

To navigate to the Application Summary page:

  • Log in to the Partner Portal.

  • Click on Applications in the top navigation menu.

  • Select the desired merchant application from the list.

  • The Application Summary page will display the details and statuses of each section.

2

Merchant Details Section

The Merchant Details section provides essential information about the merchant, including:

  • Merchant Name – Displays the registered name of the merchant.

  • Merchant Address – Shows the merchant’s business address.

  • MID (Merchant Identification Number) – A unique identifier assigned to the merchant.

  • Rep – Displays the assigned representative, if applicable.

3

Application Status Section

The Application Status section outlines the progress of each required step in the application process. Each section displays a status indicator:

  • Completed – The section has been successfully filled and submitted.

  • In Progress – The section is partially completed and requires further action.

  • Pending – No information has been provided yet.

4

Status Categories

  • Business – Indicates the completion status of the merchant’s business details.

  • Profile – Displays the status of profile-related information, including business structure and ownership details.

  • Site Survey – Shows whether the required site survey has been completed.

  • Pricing – Indicates if pricing details have been configured.

  • Banking – Displays the status of bank account details and verification.

  • Equipment – Reflects whether equipment has been selected and assigned.

  • Signatures – Indicates if all necessary signatures have been collected and submitted.

  • Submit – The final step, where users can review and submit the application for processing.

5

Managing the Application

The Application Summary page includes the following management options:

  • Download & Print App – Allows users to download a copy of the application for records or submission.

  • Delete App – Provides an option to remove the application permanently from the system. Users should confirm before proceeding, as this action is irreversible.

Next Steps

  • If any section is marked as In Progress or Pending, users should click on the respective section to complete the required information.

  • Once all sections display Completed, navigate to the Submit section to finalize and submit the application.

  • Users should verify all details for accuracy before submission to prevent processing delays.

Entering Profile Details

The Profile Details page captures key business metrics, sales profile, and vendor details to assess transaction behavior and business operations.

1

Enter Business Volume Information

  • Annual Volume: Enter the estimated total annual sales in USD.

  • Average Ticket: Enter the estimated average transaction amount per sale.

  • High Ticket: Enter the highest transaction amount.

2

Configure Sales Profile

  • Use the Card Present slider to indicate the percentage of transactions where the card is physically present.

  • Use the Card Not Present slider for the percentage of transactions processed remotely (such as online or phone orders).

3

Define E-Commerce Operations

  • Select Yes/No for ECOMM to indicate if the business processes e-commerce transactions.

  • Select Yes/No to indicate if the business provides products or services in the future after purchase, such as subscriptions or delayed product fulfillment.

4

Provide Vendor Details

  • Vendor Name: Enter the primary vendor supplying critical products or services.

  • Vendor Address: Enter the vendor’s address.

5

Save and Proceed

  • Click Save to store the profile details.

  • Click Next to proceed to the Site Survey section.

Configuring Merchant Pricing

The 'Merchant Pricing' API is designed to facilitate the management of pricing templates and pricing plans for each onboarding merchant. Clearent offers a streamlined solution to manage these plans and help merchants streamline their pricing strategy.

  • Customizable Pricing Plans: With Clearent, merchants can easily create and manage tailored pricing structures, including transaction fees, service charges, and other cost factors to fit the specific needs of each account.

  • Transparent and Competitive Rates: Pricing structures are designed to align with the merchant’s business model, ensuring clarity and offering competitive rates tailored to their needs. Using Clearent’s templates, merchants can configure plans that meet their operational requirements.

This endpoint utilizes both POST and PUT methods, enabling users to create a new pricing plan or update existing plans efficiently.

  • POST https - /api/pricing/v2/PricingPlan/{merchantNumber}

  • PUT https - /api/pricing/v2/PricingPlan/{merchantNumber}/{id}

{
  "pricingFees": [
    {
      "clearentPricingFeeID": 101,
      "pricingFeeDescription": "Transaction Processing Fee",
      "rate": 2.9,
      "fee": 0.30,
      "payInMonth1": 10.00,
      "payInMonth2": 10.00
    },
    {
      "clearentPricingFeeID": 102,
      "pricingFeeDescription": "Monthly Service Fee",
      "rate": 0.0,
      "fee": 25.00,
      "payInMonth1": 25.00,
      "payInMonth2": 25.00
    }
  ],
  "pricingPlanID": 5001,
  "pricingPlanTemplateID": 3002,
  "merchantNumber": "1234567890123456",
  "discountQualificationRangeID": 2,
  "signatureDebitDiscountQualificationRangeID": 3,
  "pricingTypeCode": "INTERCHANGE_PLUS",
  "isAdvancedPricing": true,
  "isEMF": true,
  "isDailySettle": true,
  "includeAssessments": true,
  "effectiveStartDateTimeUTC": "2024-03-01T00:00:00Z",
  "effectiveEndDateTimeUTC": "2025-03-01T00:00:00Z"
}

Working with Merchant Onboarding API

This document outlines the steps for integrating merchant onboarding. The following image and step-by-step guides provide a detailed process for integration.

For more information on each integration step, refer to the articles below:

Gathering Merchant Demographics

Clearent collects detailed demographic information to create a comprehensive profile for each business. This helps us understand the operational structure, compliance requirements, and financial needs of the applicant.

The process includes two steps:

1. Create New Merchant Account

2. Add Merchant Demographics Information

Taxpayer Information

The ‘Taxpayer Information’ endpoint adds essential taxpayer details (necessary for compliance with tax regulations) to the merchant account. It uses the POST method to submit relevant taxpayer data, such as the merchant’s legal name, tax ID, state of incorporation, etc. This information is crucial to ensure proper identification and reporting for the businesses.

POST https - /api/demographics/v2/Taxpayers/{merchantNumber}

Banking Information

The ‘Banking Information’ endpoint adds the banking details (for handling merchant transactions) to the merchant account. It uses the POST method to submit information such as deposits, fees, chargebacks, etc. for the specific merchantNumber (16-digit MID).

POST https - /api/demographics/v1/BankAccounts/{merchantNumber}

Sales Profile

The 'Sales Profile' endpoint documents the business model, revenue streams, and sales expectations for the merchant. It adds essential sales processing information, card brand entitlements, and other merchant-specific details that are crucial for the merchant's payment processing setup. Using the POST method, this endpoint outlines the sales activities and product offerings associated with the specific merchant number.

POST https - /api/demographics/v2/SalesProfiles/{merchantNumber}

Site Survey

The ‘Site Survey’ endpoint records on-site data for physical validation of the business. It submits information about the Sales Rep or Agent’s acknowledgment of completing due diligence during the site survey. Using the POST method, it captures key verification details such as valid identification, inventory checks, and in-person verification.

POST https - /api/demographics/v1/SiteSurveys/{merchantNumber}

Beneficial Ownership Agreement

The ‘Beneficial Ownership Agreement’ endpoint confirms legal compliance by acknowledging the beneficial ownership details of members with 25% or more ownership. Using the POST method, it captures and submits the ownership information, ensuring that the necessary legal requirements are met. This process helps verify the ownership structure of the business and ensures compliance with regulations.

POST

https - /api/demographics/v1/BusinessContacts/{merchantNumber}/benificialowneragreement

Upload Document

The ‘Upload Document’ endpoint allows users to upload required documents for a merchant account using the assigned merchantNumber. Using the POST method, it enables the submission of document files along with their document ID and category, ensuring that all necessary paperwork is properly attached to the merchant’s account for processing.

POST /api/demographics/v1/Documents/{merchantNumber}

Creating a Merchant Profile

The merchant onboarding process through the API begins with creating a merchant profile. This step involves two key actions:

1

Request a Merchant Identifier (MID)

Clearent assigns a unique 16-digit Merchant Identifier (MID) to each merchant. The MID tracks transactions and ensures accurate processing throughout the application lifecycle. It acts as a unique identifier for individual merchants or portfolios.

2

Create a Merchant Application

Clearent generates the merchant application and securely links all essential details to the MID. It uses the POST method to allow the submission of essential data necessary to establish a merchant profile. This ensures that the merchant’s account is set up effectively to manage credit card transactions and related services.

POST https - /api/BoardingManagement/v1.0/Applications/Create

Ordering and Setting Up Equipment

The 'Equipment Ordering' API facilitates the submission of completed equipment surveys for selected products. Clearent simplifies hardware provisioning, ensuring seamless integration for transaction processing.

  • Equipment Surveys: Merchants select the equipment they need, such as POS systems or card readers. For each product, Clearent provides a tailored survey with specific questions.

  • Hardware Provisioning: After completing the survey, merchants submit the details to Clearent, which prepares the devices.

All hardware is configured and linked to the MID for seamless integration with Clearent’s payment systems. This process ensures a streamlined approach to configuring and ordering equipment efficiently.

Utilizing the POST method, it allows users to submit their equipment orders after retrieving and completing a dynamic survey tailored to the chosen product.

  • POST /api/merchant/{merchantNumber}/equipment

Clearent's is designed to simplify and streamline the onboarding process for new merchants seeking credit card processing services. It is a RESTful API that utilizes secure HTTPS communication, ensuring reliable and secure data exchange for payment processing.

– Creates the Merchant Identifier (MID) and merchant profile.

, , and – Processes equipment details, pricing structures, and merchant demographics.

After submitting the application, Clearent validates the data. The notifies the integration system of any required corrections.

: Updates and validates merchant details, taxpayer data, business contacts, and bank account information.

– Signature Endpoints: Captures electronic signatures.

– Submit Signature & Submit Application Endpoints: Finalizes the application for review.

The merchant receives real-time updates on their application status via .

Before you start using Clearent’s , ensure you meet the following prerequisites.

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of API.

Create Merchant

A registered applicant must call the ‘Create Merchant’ endpoint to create new merchant accounts within the application. It validates the provided business model with essential fields such as dbaName, hierarchyNodeKey, and userName. This endpoint uses the POST method to submit and store all critical merchant information, ensuring streamlined operations throughout their lifecycle.

POST https - api/demographics/v1/Merchants

Once validation is complete, the merchant is created, and the changes are queued for processing. This response includes the merchant's details, setting the foundation for adding demographic information by initiating other relevant endpoints in the subdomain.

Business Contact

The ‘Business Contact’ endpoint allows users to establish a primary point of contact for the business and ensures the total ownership adds up to 100%. By using the POST method, this endpoint enables the submission of essential details such as personal information and ownership stakes to the merchant account, ensuring accurate record-keeping of each business contact.

POST https - /api/demographics/v1/BusinessContacts/{merchantNumber}

Physical Address

The ‘Physical Address’ endpoint assigns a physical location to the merchant account, representing the geographic site where the business operates. It uses the POST method to submit location details with specific parameters. This address must be a registered business or retail location.

POST https - /api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber}

Mailing Address

The ‘Mailing Address’ endpoint assigns an address for correspondence and official communications to the merchant account. It uses the POST method to submit address details with specific parameters (similar to Physical Address). A mailing address must be provided even if it matches the physical address.

POST https - /api/demographics/v1/MerchantMailingAddresses/{merchantNumber}

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of API.

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of endpoint.

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of API.

Merchant Onboarding API
Prerequisites
Understanding Integration
Working with Merchant Onboarding API
Boarding Management API
Equipment API
Pricing API
Demographics API
Application Fixes Webhook
Demographics API
Demographics API
Boarding Management API
Webhook Notifications
Merchant Onboarding API
Sandbox & Production Environments
Pricing Plan
{
  "businessID": 524398752,
  "hierarchyNodeKey": "1234567800000001",
  "dbaName": "Jane's Sandwiches",
  "merchantNumber": "1234567891234567",
  "emailAddress": "jane-doe@sandwiches.com",
  "webSite": "https:/www.janessandwiches.com",
  "phones": [
    {
      "phoneTypeCodeID": 1,
      "areaCode": "415",
      "phoneNumber": "5551234",
      "extension": "101"
    }
  ],
  "acceptsPaperStatements": true,
  "acceptsPaperTaxForms": false,
  "companyTypeId": 2,
  "isChainMerchant": false,
  "seasonalSchedule": {
    "january": true,
    "february": false,
    "march": true,
    "april": true,
    "may": true,
    "june": false,
    "july": true,
    "august": true,
    "september": false,
    "october": true,
    "november": true,
    "december": false
  },
  "salesInformation": {
    "salesInformationID": 1001,
    "businessID": 2002,
    "assignedUser": 3003,
    "referralPartner": "John Doe",
    "compensationType": 2
  }
}
{
  "phoneNumbers": [
    {
      "phoneTypeCodeID": 1,
      "areaCode": "415",
      "phoneNumber": "5555678",
      "extension": "102"
    }
  ],
  "businessContactId": 1001,
  "contact": {
    "countryOfCitizenshipCode": 840,
    "address": {
      "line1": "456 Market St",
      "line2": "Suite 300",
      "line3": "",
      "city": "San Francisco",
      "countryCode": 840,
      "stateCode": "CA",
      "zip": "94103"
    },
    "ssnLastFour": "6789",
    "encryptedSSN": "ENCRYPTED_VALUE",
    "ssn": "123-45-6789",
    "contactId": 2002,
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1985-07-22T00:00:00.000Z"
  },
  "ownershipAmount": 50,
  "emailAddress": "john.doe@business.com",
  "title": "Managing Partner",
  "contactTypes": [
    {
      "businessContactContactTypeID": 3003,
      "businessContactID": 1001,
      "contactTypeID": 2
    }
  ],
  "isCompassUser": true,
  "isMerchantHomeUser": true,
  "isVirtualTerminalUser": true,
  "isAuthorizedToPurchase": true
}
{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}
{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}
{
  "legalFirstName": "John",
  "legalLastName": "Doe",
  "tin": "12-3456789",
  "encryptedTIN": "ENCRYPTED_TIN_VALUE",
  "tinTypeID": 3,
  "businessLegalName": "Doe Enterprises LLC",
  "stateIncorporatedCode": "CA"
}
{
  "bankAccountID": 1001,
  "bankName": "Bank of America",
  "nameOnAccount": "Doe Enterprises LLC",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 3,
  "bankAccountNameTypeID": 1,
  "aba": "091000019",
  "accountNumber": "123456789012",
  "lastFourAccountNumber": "9012",
  "encryptedAccountNumber": "ENCRYPTED_ACCOUNT_VALUE",
  "voidedCheckDocumentID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": true,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2024-10-15T10:18:39.702Z"
}
{
  "usesFulfillmentHouse": true,
  "offersNegativeOptionBilling": false,
  "fulfillmentHouseAddress": {
    "line1": "1011 Northwest Ave",
    "line2": "Suite 223",
    "line3": "",
    "city": "Kansas City",
    "countryCode": 840,
    "stateCode": "MO",
    "zip": "64105"
  },
  "fulfillmentHousePhone": {
    "areaCode": "816",
    "phoneNumber": "5556789",
    "extension": "105",
    "phoneTypeCodeID": 3
  },
  "vendorName": "Doe Distribution Inc.",
  "dateOfIncorporation": "2018-06-15T00:00:00",
  "useExtraCnpValidation": true,
  "isECommerce": true,
  "mccCode": "5812",
  "cardPresentPercentage": 40,
  "returnRefundPolicy": "Full refunds are available within 60 days.",
  "productsSold": "Organic food and beverages.",
  "previouslyAcceptedPaymentCards": true,
  "previousProcessorId": 12,
  "previouslyTerminatedOrIdentifiedByRiskMonitoring": false,
  "reasonPreviouslyTerminatedOrIdentifiedByRisk": "",
  "currentlyOpenForBusiness": true,
  "annualVolume": 750000,
  "averageTicket": 65.50,
  "highTicket": 850,
  "ownsProduct": true,
  "ordersProduct": true,
  "sellsFirearms": false,
  "cbdSalesTypeID": 2,
  "salesProfileCBD": {
    "annualCBDRevenuePercentage": 20,
    "cbdProductInventoryPercentage": 50,
    "salesProfileCBDCategory": 2,
    "cbdCategoryID": 1
  },
  "sellsFirearmAccessories": false,
  "futureDeliveryTypeID": true,
  "otherDeliveryType": "Standard shipping",
  "otherDeliveryTypeInDays": 7,
  "futureDeliveryPercentage": 60,
  "fireArmsLicense": "",
  "cardBrands": [1, 2, 3, 4],
  "ebtNumber": "1998882",
  "amexMID": "1998882"
}
{
  "siteTypeID": 4,
  "otherSiteTypeDescription": "Retail Storefront",
  "siteSurveyConductedInPerson": true,
  "merchantAcquisitionTypeID": 3,
  "validIDVerified": true,
  "inventoryMatchesProductSold": true,
  "inventoryMatchesProductSoldComments": "Inventory check completed; products match business description.",
  "agreementAccepted": true,
  "selfSignUpApplication": false
}
{
  "allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded": true
}
"string"
{
  "hierarchyNodeKey": "1234567800000001",
  "dbaName": "Jane's Sandwiches"
}
{
  "merchantNumber": "9876543210123456",
  "metadata": {
    "exchangeId": "EX123456",
    "timestamp": "2025-02-17T17:57:49.203Z"
  },
  "orderCreateTime": {
    "calendarType": "ISO8601",
    "fieldsComputed": 0,
    "fieldsNormalized": 0,
    "firstDayOfWeek": 1,
    "lenient": true,
    "minimalDaysInFirstWeek": 4,
    "time": "2025-02-17T17:57:49.203Z",
    "timeInMillis": 1708186669203,
    "timeZone": {
      "displayName": "Eastern Standard Time",
      "dstsavings": 3600,
      "id": "EST",
      "rawOffset": -18000
    },
    "weekDateSupported": true,
    "weekYear": 2025,
    "weeksInWeekYear": 52,
    "zoneShared": true
  },
  "orderId": "ORD-20250217-001",
  "orderItems": [
    {
      "completionDate": "02/17/2025 05:57 PM",
      "errors": [],
      "manufacturer": "Verifone",
      "orderItemId": 1001,
      "orderItemMetadata": [
        {
          "apiKey": "API-KEY-123",
          "orderStatus": "Shipped",
          "productManufacturer": "Verifone",
          "productModel": "VX520",
          "publicKey": "PUBLIC-KEY-456",
          "salesforceCaseNumber": "SF-789654",
          "serialNumber": "SN-00123456789",
          "storeNumber": 101,
          "tcn": "TCN-ABC123",
          "terminalId": 56789,
          "trackingNumber": "1Z999AA10123456784",
          "vNumber": "VNUM-98765"
        }
      ],
      "productName": "Verifone VX520 Terminal",
      "productType": "Hardware",
      "quantity": 2,
      "surveyValid": true,
      "trackingNumber": "1Z999AA10123456784",
      "validFrontends": ["POS System"]
    }
  ],
  "orderModifyTime": {
    "calendarType": "ISO8601",
    "fieldsComputed": 0,
    "fieldsNormalized": 0,
    "firstDayOfWeek": 1,
    "lenient": true,
    "minimalDaysInFirstWeek": 4,
    "time": "2025-02-18T10:00:00.000Z",
    "timeInMillis": 1708260000000,
    "timeZone": {
      "displayName": "Eastern Standard Time",
      "dstsavings": 3600,
      "id": "EST",
      "rawOffset": -18000
    },
    "weekDateSupported": true,
    "weekYear": 2025,
    "weeksInWeekYear": 52,
    "zoneShared": true
  },
  "resubmit": false,
  "status": "Active",
  "validFrontends": ["POS System", "E-commerce"]
}
Creating a Merchant Profile
Completing the Merchant Application
Submitting the Signature
Submitting the Application
Merchant Demographics
Create Merchant Application
Equipment Boarding
Learn More
Learn More
Learn More
Learn More

Cloud EMV

Clearent’s Cloud EMV offers a unified, cloud-based payment integration, enabling POS systems to support various payment device brands and enhance the payment experience.

This semi-integrated solution integrates payments into your platform without requiring PCI DSS compliance or lengthy EMV certifications. Clearent’s Cloud EMV API allows integration with Clearent’s cloud, eliminating the need for multiple integrations with each payment terminal.

The Cloud EMV integration enables:

  • Merchants to use various card-present payment devices with easy and secure transactions.

  • Viewing your connection with Clearent.

  • Identifying the source of payment processing potential issues.

  • Resolving payment processing issues quickly.

For more information, see the following articles:

Submitting the Application

Once your application is signed, it's time to submit it for processing. By calling the ‘Submit Application’, a merchant can finalize the application and send it to Clearent. At this stage, your merchant application is directed to one of our internal teams who will take care of any necessary setup, such as:

  • Underwriting: Clearent reviews the merchant application to assess compliance and manage risk.

  • Equipment Activation: Clearent prepares the configured equipment, ensuring it’s ready for immediate use.

This step transitions the merchant from onboarding to operational readiness.

Once the necessary evaluations are complete, the merchant is fully onboarded. Clearent ensures a smooth transition, enabling merchants to start processing payments without delays.

Overview

Clearent provides multiple payment solutions to support different business models. Whether you need Online, In-Person, On-the-Go, or Recurring (Subscription) payments, Clearent has options designed for secure and efficient transaction processing. Choose the best method based on your business needs and technical setup.

Payment Solutions

Online

Clearent supports online payments with various integration options:

In-Person

Process face-to-face transactions securely and efficiently with Clearent's in-person payment solutions:

On the Go

Recurring / Subscription

Set up and manage recurring payment plans across a small or large set of customers:

For detailed implementation instructions, refer to the specific integration guides for each solution:

Working with Cloud EMV

Clearent’s Cloud EMV API allows you to manage all payment devices through Clearent’s cloud.

The following articles help working with Clearent's Cloud EMV:

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of endpoint.

: Embed a customizable, responsive payment module into your website.

: Manage a hosted pay page with the ability to customize fields and layouts.

: Integrate your software or terminals directly into Clearent's Quest Payment Gateway using a single, REST-based API.

: Send customers a secure payment link via SMS and email to complete transactions online.

: Accept payments online using the Virtual Terminal without any equipment.

: Embed payments into your platform without handling PCI DSS compliance or lengthy EMV certifications. Instead of integrating separately with each payment terminal, perform a single integration with Clearent's cloud.

: Use IDTech VP8300 card reader with a USB connection for payments acceptance—this takes you out of PCI Scope.

Enable payments on iOS and Android platforms using that provide seamless integration and allow businesses to accept payments:

: Enable payments on Android platforms.

: Enable payments on iOS platforms.

: Use the API to leverage a card on file (token) to set up, edit, and manage recurring payment plans.

: Utilize Virtual Terminal to set up and manage recurring payments using various payment methods.

Working with Cloud EMV
Direct Data Transfer to Clearent's Cloud
Payment Authorization Process via Clearent's Quest Payment Gateway
Submit Application
JavaScript SDK
Hosted Payment Page (HPP)
Transaction API
Paylink
Virtual Terminal
Cloud EMV
JavaScript SDK (USB)
Clearent's Mobile SDKs
Mobile SDK (Android)
Mobile SDK (Apple)
Recurring Transaction API
Virtual Terminal
Cloud EMV
JavaScript SDK
Hosted Payments
Mobile EMV SDK
ACH Transaction Integration
Paylink
Virtual Terminal
Direct Data Transfer to Clearent's Cloud
Payment Authorization Process via Clearent's Quest Payment Gateway

Direct Data Transfer to Clearent's Cloud

The following steps transfer data directly to the Clearent’s cloud:

1

Your POS system requests credentials for the registered credit card terminal device from Clearent’s Cloud.

2

Clearent’s Cloud EMV requests card data entry from the registered credit card terminal device.

3

The credit card terminal sends the card data entry to Clearent's Gateway.

Completing the Merchant Application

Clearent collects and validates all the required information to process transactions for the merchant account. This includes the following steps:

These steps can be completed in any order, but all must be finalized before the application is signed.

Submitting the Signature

Clearent requires merchant’s consent through signature submission to complete the onboarding application. Once all necessary information has been added, a merchant can easily provide his/her signature in one of the following two ways:

Electronic Signature Submission

Merchants can digitally sign all required documents for a fast and secure process.

Process:

  • Select at least one business contact as a signer (this is typically done when entering demographic information).

  • Present the ‘Terms and Conditions’ to the user for review.

  • Provide a clear option for the user to confirm their acceptance (e.g., a clickable checkbox).

  • Send the collected information to the ‘Signatures' endpoint.

  • Complete the submission by sending the electronic signatures via ‘Signature Submission’ endpoint.

Signature Submission via Document Upload

Merchants preferring physical signatures can print, sign, and then upload the signed documents for submission.

Process:

  • Mark at least one business contact as a signer (again, likely done when providing demographic information).

  • Provide a way for users to upload a document through your site.

  • Send the uploaded document to the ‘Document Upload’ Endpoint.

  • Send the gathered information to the ‘Signatures' endpoint.

  • Complete the submission by sending the electronic signatures via ‘Signature Submission’ endpoint.

When a merchant attempts to submit the signatures, the system will validate all the entered information and return a list of any issues found. If no issues are detected, merchant can proceed to submit the signatures.

This process ensures that Clearent receives proper authorization while offering flexibility in how signatures are submitted. After submission, no further changes can be made to the merchant through the Merchant Onboarding Boarding API.

JavaScript SDK

For more information on Clearent’s JavaScript SDK solution, refer to the following articles:

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation ofAPI.

Clearent’s JavaScript SDK solution allows you to integrate payments into your website seamlessly. Clearent’s payment frame ensures adherence to . Clearent’s payment frame is responsive, allowing you to style content using the host page.

Gathering merchant demographics
Configuring pricing
Setting up and ordering equipment
{
      "signatureSourceTypeId": 1,
      "signatureSourceTypeName": "OnlineForm",
      "signatureSourceTypeDescription": "Agreement was provided online through an E-Signature system or by indicating on an approved html form."
    }

Payment Authorization Process via Clearent's Quest Payment Gateway

The following steps process payment authorization:

1

Clearent Gateway sends an authorization approval response for card data entry when you call our Cloud EMV API.

2

The registered credit card terminal requests a response using Clearent’s Cloud EMV API.

3

Clearent’s Cloud EMV API sends a response to your POS system.

Signature Submission
PCI Security Standard Council - Best Practices for Securing E-commerce
Prerequisites
Working with JavaScript SDK
Card Validations
Configuring with JavaScript SDK

Browser Support

Clearent’s JavaScript SDK solution only work with latest versions of:

  • Chrome

  • Firefox

  • Edge

  • Safari

Prerequisites

Before you start using Clearent’s JavaScript SDK solution, ensure you meet the following prerequisites:

  • Use HTTPS for your website.

  • Host the JavaScript SDK page on a web server.

  • Do not publish your public Key outside of your code.

Note: Clearent’s JavaScript SDK does not function when you load the hosting page using .

When using the USB Card Reader, plug it into a USB port that supports USB 2.0 or later.

See the for more information.

File URI scheme
VP8300
Clearent’s JavaScript SDK - Browser Support

Working with JavaScript SDK

Working with Clearent's JavaScript SDK involves:

Adding the Payment Form
Formatting the Payment Form
Processing the Payment
Using the Apple Pay for Web
Using the Google Pay
Using IDTech VP8300

Adding the Payment Form

Follow the below steps to add the payment form into your website using Clearent’s JavaScript SDK solution:

1

Add the div provided to you into your code to contain the payment form.

<div id="payment-form"></div>
2

Add the script tag into the JavaScript SDK library.

<script src="https://gateway-sb.clearent.net/js-sdk/js/clearent-host.js"></script> code
3

Add the Global Callback Handlers into your code to receive the success or error messages from the JavaScript SDK. You can also add the Promises to receive the success or error messages alternate to avoid global callback handlers.

<script type="text/javascript">
    // When you get a successful token response and
    // use this to make a sale/auth on your backend
    function ClearentTokenSuccess(raw, json) {
        console.log("ClearentTokenSuccess");
        console.log(raw);
        console.log(json);
        // now you can send the token to your server
        // to complete the transaction via mobile-gateway
    }
    function ClearentTokenError(raw, json) {
        console.log("ClearentTokenError");
        console.log(raw);
        console.log(json);
    }
</script>java
4

Call the init method using the baseUrl and pk provided to you for your sandbox.

<script type="text/javascript">
    ClearentSDK.init({
        "baseUrl": "https://gateway-sb.clearent.net",
        "pk": "YOUR PUBLIC KEY GOES HERE"
    });
</script>

After into your website, the cardholders can enter the payment information using the form.

Adding the Payment Form

Card Expiration Date Validation

The payment transaction requires expiration date unless you store or provide card tokens to the cardholders.

Credit card expiration date is validated by:

  • Using expiration date field values, excluding non-numeric characters.

  • Entering the values in four-digits format: two-digit month and two-digit year (MMYY).

Tip: The cardholder should enter two-digit year (YY) that is greater than or equal to the current year and two-digit month (MM) that is greater than or equal to the current month.

Google Pay for Web

Google Pay allows you to make secure payments using an internet browser.

The following articles help you with Google Pay payment method.

Prerequisites

Follow the prerequisites below before you incorporate Google Pay on your website:

  • Serve an HTTPS webpage with a TLS domain-validated certificate.

  • Use one of the following supported web browsers:

    • Google Chrome

    • Mozilla Firefox

    • Apple Safari

    • Microsoft Edge

    • Opera

    • UCWeb

  • Implement the manual card entry of the JavaScript SDK solution.

Supported Payment Methods

You must have the payment and address information of your customers who use Google Pay.

Supported Cards

  • Visa

  • MasterCard

  • American Express

  • Discover

Merchant Capabilities

  • Credit cards (Visa or Mastercard)

  • Debit cards (Visa or Mastercard)

Getting Started

Note: You can use a Merchant ID provided by Clearent, which you will need for production access from Google.

Follow the below steps to start using the Google Pay on your website:

1
2

Add the function below to your website to check whether your customer uses Google Pay.

This function helps you decide whether to display the Google Pay button in the customer’s browser.

ClearentSDK.googlePayAvailable()

Configuring the onClick Event

Follow the below steps to configure the onClick event for your payment process:

1

Start the Google Pay session using the init function below.

const request = {
	"total": {
		"label": "Sasha's Mustard Shop",
		"amount": "0.01",
		"type": "final"
	}
};
const buttonConfig = {
	"buttonColor": "default",
	"buttonType": "buy",
	"buttonLocale": "en",
	"buttonSizeMode": "fill"
};
ClearentSDK.init({
	"baseUrl": "https://gateway-sb.clearent.net",
	"pk": "Your public key",
	"enableGooglePay": true,
	"googlePayRequest": request,
	"googlePayButtonConfig": buttonConfig
});
2

Clearent’s JavaScript SDK handles the Apple Pay token and converts it into the JWT that you process.

<script type="text/javascript">
            // When you get a successful token response and
            // use this to make a sale/auth on your backend
            function ClearentTokenSuccess(raw, json) {
                console.log("ClearentTokenSuccess");
                console.log(raw);
                console.log(json);
                // now you can send the token to your server
                // to complete the transaction via mobile-gateway
            }
            function ClearentTokenError(raw, json) {
                console.log("ClearentTokenError");
                console.log(raw);
                console.log(json);
            }
        </script>
3

Send the token provided by Clearent to your server using the secure transmission.

4

Provide the secret API key to Clearent from your server.

Note: Do not provide the secret API key from your website.

5

Return a successful token response you receive to the JavaScript SDK to handle it appropriately.

Formatting the Payment Form

Clearent’s JavaScript SDK payment frame allows you to format the content using the style attributes when you call the ClearentSDK.init() method.

The following code sample generates a form where the input fields display blue text by default, and the text changes to purple when the field is selected for input:

Example code:

<script type="text/javascript">
    ClearentSDK.init({
        "baseUrl": "https://gateway-sb.clearent.net",
        "pk": "YOUR PUBLIC KEY GOES HERE",
        "styles": ".form-control{color: blue;}.form-control:focus{color: purple;}"
    });
</script>

Tip: Access the element classes, IDs, and structure from the browser’s Developer toolbar to build any override styles for your payment page.

The following error will be displayed when you set an external resource or data/blob content in the style attributes during formatting the content.

Processing the Payment

1

Call the ClearentSDK.getPaymentToken method.

ClearentSDK.getPaymentToken();
2

Add Promises to receive the success or error message from the ClearentSDK.getPaymentToken() function.

ClearentSDK.getPaymentToken().then(
    (result) => {
        // this function is called if getting a payment token was successful
        console.log("ClearentTokenSuccess");
        console.log(result);
    },
    (error) => {
        // this function is called if getting a payment token failed
        console.log("ClearentTokenError");
        console.log(error);
    }
);
3
{
   "code":"200",
   "status":"success",
   "exchange-id":"ID-clearent-mobile-jwt-1-c32bfe39-d454-4e34-8b4f-94d850643e48",
   "payload":{
      "mobile-jwt":{
         "jwt":"eyJhbGciOi23UzIh4iJ9.eyJsYXN0LWZvdXIiOiIxMrkP8iwid
                HlwZSI6Ik1BTlVBTCIsImV4cCI6MTU0NzY0NjU2MSwidG9rZW4iOiIxMTAwMDAw
                MDAwMDEzNTkyIn0.eT8c_5yUzxCxL2MEtmbG444eTFRW7OxzRF7x4uRIo-U",
         "last-four":"1111"
      },
      "payloadType":"mobile-jwt"
   }
}
4

Call to the clearent-mobile-gateway from your backend using the mobilejwt field and api-key.

POST /rest/v2/mobile/transactions/sale
Accept:application/json
Content-Type:application/json
api-key:YOUR_API_KEY_GOES_HERE
mobilejwt:eyJhbGciOi23UzIh4iJ9.eyJsYXN0LWZvdXIiOiIxMrkP8iwid
 HlwZSI6Ik1BTlVBTCIsImV4cCI6MTU0NzY0NjU2MSwidG9rZW4iOiIxMTAw
 MDAwMDAwMDEzNTkyIn0.eT8c_5yUzxCxL2MEtmbG444eTFRW7OxzRF7x4uRIo-U
Body
{
    "type": "SALE",
    "amount": "15.55",
    "software-type": "AwesomePOSSoftware",
    "software-type-version":"1"
}

You will receive the below response after successful transaction or an error response if the transaction fails.

{
    "code": "200",
    "status": "success",
    "exchange-id": "ID-clearent-mobile-gateway-1-2a6b56d3-c660-4810-95ea-9fb9a21c6634",
    "payload": {
        "transaction": {
            "amount": "15.55",
            "id": "2586119",
            "type": "SALE",
            "result": "APPROVED",
            "card": "XXXXXXXXXXXX1111",
            "csc": "999",
            "authorization-code": "TAS022",
            "batch-string-id": "938",
            "display-message": "Transaction approved",
            "result-code": "000",
            "exp-date": "1220",
            "software-type": "AwesomePOSSoftware",
            "card-type": "VISA",
            "last-four": "1111"
        },
        "payloadType": "transaction"
    }
}

Example: Decoded, unencrypted, signed JWT

Cover

Partner Solutions

Build, scale, and optimize your portfolio with flexible integrations and powerful tools. Easily onboard merchants, process transactions, and access detailed reporting to drive success.

Cover

Merchant Solutions

Manage and grow your business with seamless payment acceptance, transaction tracking, reporting, and dedicated support—everything you need to stay in control.

Cover

Payment Solutions

Secure, scalable, and seamless payment processing capabilities. Our reliable infrastructure ensures security, compliance, and timely funding.

Using IDTech VP8300

  • Contactless

  • Chip

  • Swipe

Note: Ensure the card reader has a USB connection to communicate with Clearent’s JavaScript SDK.

Prerequisites

  • Use a device with Windows or macOS that includes a USB port.

  • Serve your application over HTTPS in both development and production environments.

  • Your domain must have a valid SSL certificate.

  • Implement the manual card entry of the JavaScript SDK solution.

Initializing the SDK

Call the following init function that has the enableReader flag set to true and the deviceType set to IDTECH, which supports the card reader.

ClearentSDK.init({
                  "baseUrl": "https://gateway-sb.clearent.net",
                  "pk": "YOUR PUBLIC KEY GOES HERE"
                  "enableReader":true,
                  "deviceType": "IDTECH"
                 });

Connecting the Card Reader

Plug the card reader into a USB port on your device.

Note: You can use an adapter if your device does not have a USB port.

Selecting the Reader Button

Selecting the Reader button next to the Card Number input field completes the entry of card details into the fields of the Payment Details form.

Presenting Card to Reader

Present the card when you see the message ‘Ready for card reader…’ on the Payment Details form.

Note: Do not present the card to the reader unless you see the message ‘Ready for card reader…’ on the Payment Details form to avoid incorrectly filling the card data into the fields.

You will see masked information in the fields of the Payment Details form.

Note: To clear the information from all fields in the Payment Details form, select the Clear button in the upper-right corner.

Selecting the Submit Button

To send the card data to Clearent, select the Submit Payment button.

Connecting in HID Mode

Card Validations

We implement the following basic client-side validations with the best security practices on the Clearent servers to improve user experience and reduce errors. These validations prevent attempting the use of your website as a validator for stolen credit cards:

Card Number Validation

Credit card numbers are validated by:

  • Getting the card token.

  • Using card number field values, excluding non-numeric characters.

  • Passing the remaining digits through the Luhn algorithm.

Note: Passing the remaining digits of the credit card through the Luhn algorithm does not prove the validation but helps prevent typing errors.

Apple Pay for Web

Apple Pay for Web lets you accept payments from customers using the Safari browser on their iOS devices.

The following sections explain how to integrate Apple pay on your website.

Prerequisites

Make sure the following requirements are met before integrating Apple Pay and accepting payments on your website:

  • A MacBook running macOS 10.12.1 or later

  • An iPhone running iOS 10.1 or later

  • Safari browser

  • A server that supports Apple Pay

  • An application served over HTTPS in both development and production environments

  • A valid SSL-certified domain

  • A server that supports Transport Layer Security (TLS) version 1.2 or later

Always implement manual card entry in the JavaScript SDK as a fallback option.

Supported Payment Methods

You can collect the payment and address information of your customers who use Apply Pay.

Supported Cards

  • Visa

  • MasterCard

  • American Express

  • Discover

Merchant Capabilities

  • Credit cards (Visa or Mastercard)

  • Debit cards (Visa or Mastercard)

Unsupported Payment Methods

  • In-App Payments

  • Recurring Payments

  • Split Shipment

  • Voids/Refunds through Apple Pay

Getting Started

To register and verify your domain with Apple:

  1. Provide your domain(s) that will be used for Apple Pay.

  2. Host the verification file provided by Clearent to you on the following URL, replacing [DOMAIN_NAME] with your domain name.

URL: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

This URL must be publicly accessible to allow Apple to verify the file.

  1. Send the hosted file with the appropriate URL to register and verify your domain with Apple.

  2. Clearent will confirm once your domain is successfully verified.

Setting Up Apple Pay

Adding the Apple Pay Button

1

Create a container on your website to add the Apple Pay button with the default style.

<button id="apple-pay-button" class=""></button>

To request button type for your website:

{
    "total": {
        "label": "AAA",
        "type": "final",
        "amount": "1.99"
    }
}
2

Add the function to check whether your customer uses Apple Pay. This function helps you decide whether to display the Apple Pay button in the customer’s browser.

ClearentSDK.applePayAvailable()

Configuring the onClick Event

To configure the onClick event for your payment process:

1

Add the onClick object into your payment sheet to start the Apple Pay session.

if(ClearentSDK.applePayAvailable()) {
  let applyPaymentSheet = YOUR_PAYMENT_SHEET
  jq2("#apple-pay-button").on("click", () => {
      const session = ClearentSDK.buildApplePaySession(applyPaymentSheet);
// optional dynamic handling events can be added here (see below for details)
      session.begin()
  });
}
2

The JavaScript SDK handles the Apple Pay token and converts it into a JSON Web Token (JWT).

function ClearentTokenSuccess(raw, json) {
    console.log("ClearentTokenSuccess");
    console.log(raw);
    console.log(json);
    console.log("-----------------------------------------------");
    console.log("now you can send the token to your server");
    console.log("to complete the transaction via mobile-gateway");
    console.log("-----------------------------------------------")
}
function ClearentTokenError(raw, json) {
    console.log("ClearentTokenError");
    console.log(raw);
    console.log(json);
}
3

Send the JSON Web Token (JWT) to your server using a secure connection.

4

Provide the secret API key to Clearent from your server.

Don’t expose the secret API key in your website code.

5

Clearent returns a successful token response.

6

Send the token response to the JavaScript SDK for handling.

Testing Apple Pay for Web

Apple requires an offline test implementation of Apple Pay for apps, websites, and point-of-sale systems.

Calculating Final Transaction Cost

You can calculate final transaction cost using customer’s payment method, billing address, shipping address, and shipping method:

Refer the following example to implement the optional handlers in your payment sheet:

Example:

jq2("#apple-pay-button").on("click", () => {
    const session = ClearentSDK.buildApplePaySession(request);
  session.onshippingmethodselected = function (event) {
    selectedShippingMethod = event.shippingMethod
    const newTotalAmount = calculateTotal….
    const newLineItems = [update line items…]
    session.completeShippingMethodSelection(
      {
        newTotal: {
          label: request.total.label,
          amount: newTotalAmount,
          type: final }, // newTotal is required
        newLineItems,
      }
    )
  }
   session.oncancel = function(event) {
       …add logic for when session is cancelled by user
}
…. Other optional handlers can be added here
    session.begin()
});

Add a payment method to your Google account using the reference.

Adhere to the .

Create a request object and a buttonConfig object using the reference before you call our init function.

Note: Before moving to the next step, ensure you have integrated with Clearent’s JavaScript SDK to avoid an error. For more information, see .

Example: Payment form
Example: Browser's developer toolbar
Example: Error from the browser's developer toolbar

Clearent provides a secure, signed JSON Web Token () when the cardholder selects the Submit button on your .

To receive a secure and signed and complete the payment on your backend:

Call the JWT service using the ClearentTokenSuccess function to receive the secure, signed, and unencrypted JSON Web Token in the field shown below.

Example: Decoded, unencrypted, signed JWT

Clearent’s JavaScript SDK supports an IDTech card reader for payments acceptance. This card reader supports three interaction methods:

Follow the requirements below before you start using the card reader:

Example: Payment form
Example: Payment for
Example: Payment for
Example: Payment for

Note: The success and error functions are triggered when you call the mobile JWT or ACH mobile JWT to create a secure JWT, which presents the card or ACH data. See for more information.

When you connect to the in HID mode, a security window appears in your browser. This window allows you to select the terminal for connecting to the VP8300 in HID mode, enabling access to the device.

Before connecting to the in HID mode, you must:

Set the Card Reader to HID mode.

Sometimes, cardholders might enter a cancelled, non-issued or invalid card number in the . This payment information is validated on the backend when you submit the sale request.

Refer to the for setting up your production environment.

Clearent handles the process for you by creating an Apple Merchant ID and Certificate Signing Request. For more information, see .

Apple provides several types of buttons so that you can choose the button type that fits best with the terminology and flow of your purchase or payment experience. For more information on Apple Styling Guidelines, see .

Before moving to the next step, ensure you have integrated with Clearent’s JavaScript SDK to avoid an error. For more information, see .

You can test your Apple Pay transaction using the reference.

If you want to calculate the final transaction cost using payment method, add the optional handler in your payment sheet.

If you want to calculate the final transaction cost using shipping method, add the optional handler in your payment sheet.

If you want to calculate the final transaction cost using billing address and shipping address, add the optional handler in your payment sheet.

You can add the optional handler, which triggers when the customer clicks the Cancel button, to cancel the Apple Pay session.

Getting Started with Google Pay
Google Pay and Wallet APIs Acceptable Use Policy
Brand Guidelines by Google
Clearent’s JavaScript SDK
VP8300
VP8300
Clearent's ACH Transaction Integration
VP8300
VP8300
VP8300
VP8300
Card Number Validation
Card Expiration Date Validation
Card CSC/CVC Validation
Payment Form
Apple Server Configurations
Merchant Validation
Apple Developer Documentation
Apple Pay
Clearent’s JavaScript SDK
Sandbox testing
onpaymentmethodselected
onshippingmethodselected
onshippingcontactselected
oncancel
payment form
JWT
JWT
JWT

Card CSC/CVC Validation

By default, payment transactions require security codes (CSC, CID, CVC, CVV, CVV2).

Credit card security codes are validated by:

  • Using CSC/CVC field values, excluding non-numeric characters.

Note:

  • Following credit cards include three-digit security code:

    • Visa

    • MasterCard

    • Discover

    • Diner’s Club

    • JCB

  • Following credit card includes four-digit security code:

    • American Express

Using Methods

Refer to the following table to configure your payment page:

Using this method…
You can…
Sample Code
Remark

addMetaKeyBlocker()

Block meta key combinations (alt or ctrl) for the hosting page.

Some card readers may generate keystrokes that include meta keys even after the card read is complete, causing unnecessary behavior in the browser window.

Tip: To make this setting effective, set the enableReader member to True.

<script> ClearentSDK.addMetaKeyBlocker(); </script>

This setting blocks certain meta key combinations, except for closing the window (Ctrl + W), opening a new window (Ctrl + N), or opening a new tab (Ctrl + T).

getPaymentToken()

Receive a token for payment gateway transaction, calling successCallback on success or errorCallback on error.

ClearentSDK.getPaymentToken();

None

init(obj)

Initialize the Clearent JavaScript SDK integration and create the Payment Details form for entry.

// Sandbox URL for testing // use Sandbox public key <script src="https://gateway-sb.clearent.net/js-sdk/js/clearent-host.js"></script> <script> ClearentSDK.init({ "baseUrl": "https://gateway-sb.clearent.net", "pk": "YOUR_SANDBOX_PUBLIC_KEY_HERE", }); </script>

You can set the properties of the JSON-formatted object when you initialize the Clearent JavaScript SDK integration.

removeMetaKeyBlocker()

Remove a meta key combination blocker enabled using the blockMetaKeys member or the addMetaKeyBlocker method.

<script> ClearentSDK.removeMetaKeyBlocker(); </script>

reset()

Reset the JavaScript SDK integration.

Warning: When you use the reset() method, the Clearent Payment iFrame is completely removed.

ClearentSDK.reset();

You can call Clearent.init to initialise the JavaScript SDK integration.

ClearentCardReadComplete()

Call the function when the card read process is complete using the USB card reader.

function ClearentCardReadComplete(){ console.log("Card Read is complete"); }

You can call the function if it is defined on the host page. This function does not return card data or Europay, Mastercard and Visa (EMV) data to maintain the Payment Card Industry (PCI) compliances.

ClearentCardReadStart()

Call the function when the card read process starts using the USB card reader.

function ClearentCardReadStart(){ console.log("Card Read has started"); }

You can call the function if it is defined on the host page.

ClearentEntryModeChange(mode)

Call the function when the entry mode changes to manual or swipe.

function ClearentEntryModeChange(mode){ console.log("User set SDK to mode: ", mode); }

You can call the function if it is defined on the host page.

ClearentOnPaymentTypeChange(paymentType)

Call the function to receive a raw server response or a JSON-formatted response data object if getPaymentToken returns successfully.

function ClearentOnPaymentTypeChange(paymentType) { console.log("Payment Type was changed to: " + paymentType); }

You can call the function if it is defined on the host page.

ClearentTokenError(responseRaw, responseJSON)

Call the function to receive a raw server response or a JSON-formatted response data object if getPaymentToken returns an error.

function ClearentTokenError(responseRaw, responseJSON){ console.log("ClearentTokenError"); console.log(responseRaw); console.log(responseJSON); }

You can call the function if it is defined on the host page.

ClearentTokenSuccess(responseRaw, responseJSON)

Call the function to receive a raw server response or a JSON-formatted response data object if getPaymentToken is successful.

function ClearentTokenSuccess(responseRaw,responseJSON){ console.log("ClearentTokenSuccess"); console.log(responseRaw); console.log(responseJSON); // now you can send the token to your server // to complete the transaction via mobile-gateway }

You can call the function if it is defined on the host page.

ClearentValidation(messages)

Call the function to validate the payment form fields information that returns the validation message with a JavaScript array.

function ClearentValidation(messages) { console.log("ClearentValidation"); console.log(messages); // you can handle these messages and display in your own form // empty messages array indicates no validation errors }

When the payment fields have valid information, a JavaScript array in the validation message will be empty.

Using Members

Refer to the following table to configure your payment page popup:

Using this member…
You can…
Type
Default Value
Remark

accountNumberMasked

Decide if the Account Number field should display masked information after the customer exits the field.

Boolean

True

To unmask the Account Number field when your customer exits this field, set the accountNumberMasked member to False.

accountNumberPlaceholder

Decide the text to display for the Account Number field before your customer provides input.

String

Account Number

None

accountTypePlaceholder

Decide the text to display for the Account Number field before your customer selects it.

String

Account Type

None

allowAutoComplete

Decide if the fields in the Payment Details form should autocomplete.

Boolean

True

To configure the cardholder-facing implementation, set the allowAutoComplete member to True.

To configure the merchant-facing implementation, set the allowAutoComplete member to False.

allowEmbedded

Decide if JavaScript SDK's host page should be embedded in another page.

Boolean

True

None

baseUrl

Decide if the Clearent Gateway base URL should be set to sandbox or production URL.

Note: You must set the baseUrl to sandbox or production URL.

String

Null

None

blockMetaKeys

Decide if meta key combinations (alt or ctrl) should be blocked for the hosting page.

Some card readers may generate keystrokes that include meta keys even after the card read is complete, causing unnecessary behavior in the browser window.

Mode

False

The blockMetaKeys member allows you to block meta key combinations on all pages containing the Clearent script.

This setting blocks certain meta key combinations, except for closing the window (Ctrl + W), opening a new window (Ctrl + N), or opening a new tab (Ctrl + T).

cardFormatted

Decide if the card field should be formatted as the customer enters information in the field.

Note: To make this setting effective, set the enableReader member to True.

Boolean

True

The cardFormatted member allows you to display the text in the Card Payment fields in a format similar to how the information appears on the physical card as the customer enters information.

To configure the cardholder-facing implementation, set the cardFormatted member to True.

cardMasked

Decide if the card field should display masked information after the customer exits the field.

Boolean

True

To unmask the Card Payment fields when your customer exits fields, set the cardMasked member to False.

To configure the cardholder-facing implementation, set the cardMasked member to True.

cardPlaceholder

Decide the text to display for the card field before your customer provides input.

String

Card Number

None

cardReadCompleteCallback

Decide the name of the function to call to receive a message after completing the card read.

String

ClearentCardReadComplete

None

cardReadStartCallback

Decide the name of the function to call to receive a message when starting the card read.

String

ClearentCardReadStart

None

clearFormOnSuccess

Decide if the Payment Details form should be cleared on a successful call to getPaymentToken().

Boolean

False

The clearFormOnSuccess member allows you to clear the form in a back-office implementation.

cvcMasked

Decide if the CSC field should display masked information after the customer exits the field.

Boolean

True

To unmask the Card Payment fields when your customer exits this field, set the accountNumberMasked member to False.

To configure the cardholder-facing implementation, set the cvcMasked to True.

cvcPlaceholder

Decide the text to display for the CVC field before your customer provides input.

String

CSC

None

cvcRequired

Decide if the CVC field is mandatory for customer to enter a value.

Boolean

True

None

deviceType

Decide the device type of external keyboard-emulation card reader.

String

Null

The deviceType member allows you to add an external card reader.

Clearent’s JavaScript SDK supports following Card Reader:

  • IDTECH

enableAch

Decide if the customer should pay with an online check.

Boolean

False

None

enableReader

Decide if an external card reader should be supported for reading cards.

Boolean

False

You need to add the Card Reader button to start reading the card details using an external keyboard-emulation card reader.

Clearent’s JavaScript SDK supports following card reader:

  • IDTECH

entryModeChangeCallback

Decide the name of the function to call to receive a message when changing the card entry mode.

String

ClearentEntryModeChange

None

errorCallback

Decide the name of the function to call to receive the getPaymentToken() response.

String

ClearentTokenError

None

expDateFormatted

Decide if the Expiration Date field should be formatted on entry.

Boolean

True

The expDateFormatted member allows you to display the text in the Expiration Date field in a format similar to how the information appears on the physical card as the customer enters information.

To configure the cardholder-facing implementation, set the expDateFormatted to True.

expDateMasked

Decide if the Expiration Date field should be masked when customer exits the field.

Boolean

True

To unmask the Expiration Date field when your customer exits this field, set the expDateMasked member to False.

To configure the cardholder-facing implementation, set the expDateMasked to True.

expDatePlaceholder

Decide the text to display for the Expiration Date field before your customer provides input.

String

MMYY

None

individualNamePlaceholder

This member allows you to decide the text to display for the Expiration Date field before your customer selects the field.

String

Name on account

None

initialMode

Decide if the Payment Details form should open in manual card entry mode or keyboard reader mode.

String

Manual

You need to set the enableReader member to True before setting the initialMode member.

When you set the initialMode member to manual or reader mode, the payment form will actively listen for keystrokes generated by the card reader.

Your customers will see errors and retries if they enter keystrokes that are part of the card read.

We recommend testing this use case before implementation.

paymentFormId

Decide the ID of div element that will hold the Payment Details form.

String

payment-form

To avoid conflicts with existing code and page element IDs, set the paymentFormId member to a value other than the default.

paymentTypeCallback

Decide the name of the function to call the onPaymentTypeChange().

String

ClearentOnPaymentTypeChange

To call the function, set the enableReader member to ACH.

This function is called when the payment type changes to card or ACH.

pk

Public Key

Note: You must set the pk member.

String

Null

None

routingNumberMasked

Decide if the Routing Number field should be masked when customer exits the field.

Boolean

True

To unmask the Routing Number field when your customer exits this field, set the routingNumberMasked member to False.

routingNumberPlaceholder

Decide the text to display for the Routing Number field before your customer provides input.

String

Routing Number

None

showValidationMessages

Decide if validation messages should be displayed below the payment form.

Boolean

True

To configure the handling of validation messages elsewhere, set the showValidationMessages member to False.

styles

Decide the style for the framed contents.

String

Null

You can use the IDs and classes from your browser’s Developer tools to style the frame of the payment page.

successCallback

Decide the name of the function to call to receive the getPaymentToken() response.

String

ClearentTokenSuccess

This function is called when the getPaymentToken generate successful.

validationCallback

Decide the name of the function to call to receive the validation messages.

String

ClearentValidation

None

Learn More
Learn More
Learn More

Browser Support

Clearent’s Hosted Payments solution only work with latest versions of:

  • Chrome

  • Firefox

  • Edge

  • Safari

Prerequisites

Before you start using Clearent’s Hosted Payments solution, ensure you meet the following prerequisites:

  • Use HTTPS for your website.

  • Do not publish the public key outside of your code.

Hosted Payments

Clearent’s Hosted Payments solution ensures secure online payment acceptance on your website. Simply copy and paste a few lines of code to integrate customizable payment options into your existing site.

With Clearent’s Hosted Payments solution, you can:

  • Customize payment pages, forms, and buttons.

  • Style payment pages with custom colors, text, brand logos, images, and checkout options.

  • Collect information such as invoice or order numbers for online payment reconciliation.

For more information on Clearent’s Hosted Payments solution, refer to the following articles:

Configuring with JavaScript SDK

This is the page description that I can enter

You can quickly and easily configure the text and behavior of your payment page popup:

Provide the domain that sends transaction requests in the production environment using our portal.

See the for more information.

Note: The hosted button works only for registered websites that accept online payments.

Merchant Onboarding
Browser Support
Pay Now
Prerequisites
Transaction Responses
Response Validations
Card Validations
Working with Hosted Payments
Using Members
Using Methods

Working with Hosted Payments

Clearent’s Hosted Payments allows you to integrate the following payment options in your website:

Before you start configuring the payment options, you must:

  • Create a Clearent Merchant Account.

  • Complete the Payment Button request form.

Configuring the Pay Now Button
Configuring Payment Page with an Amount Field
Configuring Payment Page with an Optional Billing Address and Headline Text
Configuring Payment Page with the Save Card Option
Configuring the Add Payment Method Button
Styling Your Brand on the Payment Page
Configuring Apple Pay for Web
Configuring Hosted Payment Page Using Members
Configuring Hosted Payment Page Using Methods
Configuring Hosted Payment Page Using Functions