Payment Processing: Payment Methods

Overview

The SDK automatically displays payment methods based on your checkout session configuration. Payment methods are defined using the TenderTypeOptions array in your checkout session.

Available Payment Methods

Supported Tender Types

Based on the actual SDK implementation, the following payment methods are available:

type TenderType = 'Credit' | 'ACH' | 'GooglePay' | 'ApplePay';

Payment Method	TenderType	Description
Credit/Debit Cards	`Credit`	Visa, Mastercard, American Express, Discover
Google Pay	`GooglePay`	Google's digital wallet
Apple Pay	`ApplePay`	Apple's digital wallet
ACH	`ACH`	Bank account (eCheck) payments

Configuring Payment Methods

Checkout Session Configuration

Set available payment methods when creating your checkout session:

// Backend: Single payment method
const checkoutSession = {
    ClientId: 'your_client_id',
    TenderTypeOptions: ['Credit'],
    Sale: {
        DeviceGuid: 'your_device_guid',
        Amount: 125.50
    }
};

// Backend: Multiple payment methods
const checkoutSession = {
    ClientId: 'your_client_id',
    TenderTypeOptions: ['Credit', 'GooglePay', 'ApplePay'],
    Sale: {
        DeviceGuid: 'your_device_guid',
        Amount: 125.50
    }
};

Default Payment Method

Specify which payment method should be selected when the form renders. Only Credit and ACH can be set as the default payment method — other values are ignored and the first available method is selected instead:

// Frontend: Set default payment method
await connexpay.createPaymentForm({
    element: '#connexpay-element',
    checkoutSessionID: sessionId,
    defaultPaymentMethod: 'ACH'  // Optional; 'Credit' or 'ACH'
});

The default only applies when the method is included in the checkout session's TenderTypeOptions.

Credit Card Payments

Credit Card Processing

Credit cards are processed through the standard payment form:

// Create form with credit card support
await connexpay.createPaymentForm({
    element: '#connexpay-element',
    checkoutSessionID: sessionId
});

// Process credit card payment
try {
    const result = await connexpay.confirmPayment();
    
    if (result.sale) {
        console.log('Credit card payment successful:', result.sale.guid);
        handlePaymentSuccess(result);
    }
} catch (error) {
    console.error('Credit card payment failed:', error);
    handlePaymentError(error);
}

Supported Card Networks

The SDK supports the following credit card networks:

Visa
Mastercard
American Express
Discover

Credit Card Validation

The SDK automatically validates:

Card Number: 12-19 digits after removing spaces
Expiration Date: Format and future date validation
Security Code: CVV/CVC validation based on card type

// Listen for validation errors
connexpay.on('error', (error) => {
    if (error.category === 'VALIDATION_ERROR') {
        // Handle field-specific errors
        if (error.fields) {
            error.fields.forEach(fieldError => {
                switch (fieldError.field) {
                    case 'cardNumber':
                        handleError('card-number', fieldError.message);
                        break;
                    case 'expirationDate':
                        handleError('expiry', fieldError.message);
                        break;
                    case 'securityCode':
                        handleError('cvv', fieldError.message);
                        break;
                }
            });
        }
    }
});

Digital Wallet Payments

Apple Pay

Apple Pay requires merchant verification and is processed directly through the SDK:

// Apple Pay is handled automatically when available
// Ensure ApplePay is in TenderTypeOptions
const checkoutSession = {
    TenderTypeOptions: ['Credit', 'ApplePay'],
    // ... other configuration
};

// Apple Pay processing is handled internally
try {
    const result = await connexpay.confirmPayment();
    // Apple Pay payment completed
} catch (error) {
    // Handle Apple Pay errors
    if (error.message === 'Apple Pay: User canceled.') {
        console.log('User canceled Apple Pay');
    }
}

Apple Pay Requirements

Merchant Verification: Your domain must be verified with Apple
HTTPS: Required for Apple Pay functionality
Safari/iOS: Apple Pay only works on Apple devices and Safari

Google Pay

Google Pay integration supports various card networks and authentication methods:

// Google Pay configuration is handled automatically
// Ensure GooglePay is in TenderTypeOptions
const checkoutSession = {
    TenderTypeOptions: ['Credit', 'GooglePay'],
    // ... other configuration
};

// Google Pay processing
try {
    const result = await connexpay.confirmPayment();
    // Google Pay payment completed
} catch (error) {
    // Handle Google Pay specific errors
    console.error('Google Pay error:', error);
}

ACH Payments

ACH (bank account) payments are collected through a dedicated bank account form rendered by the SDK. Include ACH in your checkout session's TenderTypeOptions to enable it:

// Backend: Enable ACH (alone or alongside other methods)
const checkoutSession = {
    ClientId: 'your_client_id',
    TenderTypeOptions: ['Credit', 'ACH'],
    Sale: {
        DeviceGuid: 'your_device_guid',
        Amount: 125.50,
        Customer: {
            FirstName: 'Sarah',   // First and last name are mandatory for ACH sales
            LastName: 'Johnson'
        }
    }
};

// Frontend: Render the form with ACH pre-selected (optional)
await connexpay.createPaymentForm({
    element: '#connexpay-element',
    checkoutSessionID: sessionId,
    defaultPaymentMethod: 'ACH'
});

// Process the ACH payment
try {
    const result = await connexpay.confirmPayment();
    if (result.sale) {
        console.log('ACH payment created:', result.sale.guid);
    }
} catch (error) {
    console.error('ACH payment failed:', error);
}

ACH Form Fields

The SDK collects and validates the following bank account details:

Field	Validation
Name on account	2-50 characters; letters, spaces, hyphens, apostrophes, and periods only
Account type	`Checking` or `Saving`
Routing number	9 digits; validated with the ABA routing number checksum
Account number	1-20 characters, letters and numbers only
Confirm account number	Must match the account number

Validation failures reject the confirmPayment() promise with field-level errors (fields: nameOnAccount, accountType, routingNumber, accountNumber, confirmAccountNumber).

ACH Processing Notes

The customer's first and last name (set via the checkout session Customer or setCustomer()) are mandatory for ACH sales.
The customer's IP address is required for all ACH sales for regulatory compliance; the SDK supplies it automatically with the transaction.
A successful ACH confirmPayment() resolves with the created sale in result.sale, including result.sale.bankAccount (account type, name on account, and last four of the account number).
verifyPayment() can be used with ACH to validate the bank account without processing the transaction.

ACH Verification and Tokenization

Use verifyPayment() to validate the customer's bank account details without creating a sale. A successful verification returns the tokenized bank account, which you can store and reuse for future sales without collecting the bank details again:

try {
    const result = await connexpay.verifyPayment();

    if (result.verify?.bankAccount) {
        const account = result.verify.bankAccount;

        // Store these for future sales — no raw account data is exposed
        console.log('Bank account guid:', account.guid);
        console.log('Reusable token:', account.accountAndRoutingNumberToken);
        console.log('Display as:', `${account.accountType} ****${account.accountNumberLastFour}`);
    }
} catch (error) {
    console.error('ACH verification failed:', error);
}

The verified bank account is returned with:

Field	Description
`guid`	Unique identifier for the stored bank account
`accountType`	`Checking` or `Saving`
`accountNumberLastFour`	Last four digits of the account number (for display)
`nameOnAccount`	Name on the account
`accountAndRoutingNumberToken`	Encrypted token representing the account and routing number pair

The same tokenized bankAccount (including accountAndRoutingNumberToken) is also returned on successful ACH sales created with confirmPayment().

Reusing the token: create later sales server-side through ConnexPay's Create Sale API by sending BankAccount.AccountAndRoutingNumberToken in place of AccountNumber and RoutingNumber. AccountType, NameOnAccount, and the Customer (with first and last name) are still required:

// Backend: create a subsequent ACH sale with the stored token
const sale = {
    DeviceGuid: 'your_device_guid',
    Amount: 89.00,
    TenderType: 'ACH',
    RequestIp: customerIp,          // Required for ACH
    IncludeRiskAnalysis: true,      // Required for ACH
    BankAccount: {
        AccountAndRoutingNumberToken: storedToken,
        AccountType: 'Checking',
        NameOnAccount: 'Sarah Johnson',
        Customer: {
            FirstName: 'Sarah',
            LastName: 'Johnson'
        }
    },
    ConnexPayTransaction: { ExpectedPayments: 1 }
};

await fetch('https://sandboxsalesapi.connexpay.com/api/v1/sales', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(sale)
});

Payment Processing Methods

confirmPayment()

Process the actual payment transaction:

try {
    const result = await connexpay.confirmPayment();
    
    if (result.sale) {
        // Payment successful
        console.log('Transaction ID:', result.sale.guid);
        console.log('Amount:', result.sale.amount);
        
        // Redirect or show success
        window.location.href = `/success?tx=${result.sale.guid}`;
    }
} catch (error) {
    // Payment failed
    console.error('Payment failed:', error.message ?? error);
    showPaymentError(error.message ?? error);
}

verifyPayment()

Verify payment details without processing the transaction. The verification result (result.verify) includes a card guid (or bank account details for ACH) which can be used later when creating a sale via ConnexPay's Create Sale API.

try {
    const result = await connexpay.verifyPayment();
    
    // Payment verification successful
    console.log('Payment method verified:', result);
    
    // Create a sale through ConnexPay's Sales API 
    
} catch (error) {
    // Verification failed
    console.error('Payment verification failed:', error);
}

Payment Method Selection

Handling Payment Method Changes

The SDK automatically handles payment method selection, but you can listen for changes:

// The SDK internally tracks the selected payment method
// Payment method is automatically set when user selects an option

// Process payment with selected method
async function processPayment() {
    try {
        const result = await connexpay.confirmPayment();
        // Payment processed with user's selected method
    } catch (error) {
        if (error.message === 'No payment method has been selected') {
            showError('Please select a payment method');
        }
    }
}

Payment Method Validation

// The SDK validates payment method selection automatically
connexpay.on('error', (error) => {
    if (error.category === 'PAYMENT_ERROR' && 
        error.message === 'No payment method has been selected') {
        // Prompt user to select a payment method
        showPaymentMethodSelection();
    }
});

Error Handling

Payment Error Types

Based on the actual implementation, handle these error scenarios:

async function handlePaymentProcessing() {
    try {
        const result = await connexpay.confirmPayment();
        return result;
    } catch (error) {
        switch (error.category) {
            case 'VALIDATION_ERROR':
                handleValidationError(error);
                break;
                
            case 'PAYMENT_ERROR':
                handlePaymentError(error);
                break;
                
            default:
                handleGenericError(error);
        }
    }
}

function handleValidationError(error) {
    // Handle field validation errors
    if (error.fields) {
        error.fields.forEach(field => {
            console.log(`${field.field}: ${field.message}`);
        });
    }
}

function handlePaymentError(error) {
    // Handle payment processing errors
    switch (error.message) {
        case 'No payment method has been selected':
            showError('Please select a payment method');
            break;
            
        case 'Apple Pay: User canceled.':
            // User canceled Apple Pay - don't show error
            break;
            
        case 'Payment already performed':
            showError('This payment has already been completed');
            break;
            
        default:
            showError(error.message || 'Payment processing failed');
    }
}

Common Payment Errors

Error Message	Cause	Solution
`No payment method has been selected`	User hasn't selected payment method	Prompt user to select method
`Apple Pay: User canceled.`	User canceled Apple Pay	Allow retry with different method
`Payment already performed`	Checkout session already used	Create new checkout session
`ConnexPay SDK is not ready`	SDK not initialized	Wait for 'ready' event