Collecting Payment Details

Creating a Payer

A Payer represents the individual or organization you want to collect money from. Typical examples include policyholders, brokers, employers, or business partners.

Creating a payer helps you tie payment activity and reconciliation back to a specific entity. The full list of request parameters can be found here.

Example

POST https://api.withacclaim.com/v1/payers
Content-Type: application/json
Authorization: Bearer myApiKey

{
    "given_name": "Jane",
    "family_name": "Doe",
    "email": "[email protected]",
}

Creating a Tokenization Request

A Tokenization Request lets your payer securely provide payment details through an Acclaim-hosted interface. Payment details never pass through your backend. The Create Tokenization Request documentation has more details about this endpoint.

POST https://api.withacclaim.com/v1/tokenization_requests
Content-Type: application/json
Authorization: Bearer myApiKey

{
    "payer_id": "pyr_93LdZvQ19a"
}

Response: (abbreviated)

{
  "id": "trq_7QvP1mNw3d",
  "session_identifier": "trq_s3UBMW8il18ICbev1EUdKT1Fclwbnd3EUjxkqkpj6N6FfE6gJRWVEtO2ZpM95eRSThzxWdV77fLlMNNKovx0Rq5JEmdxNOv2gjMMlrGe90AEwy6f3Nxx05INZrAo4AyL"
}

Collecting Details Securely with the Payment Element

<script src="https://cdn.withacclaim.com/v1/acclaim.js"></script>

<form id="payment-form">
    <div id="payment-container"></div>
    <button type="submit" id="submit-button">Submit</button>
</form>

<script>
    async function setupPayment() {
        // Initialize Acclaim
        const acclaim = new Acclaim({
            publishableKey: 'pk_live_your_api_key',
        });

        // Create and mount element
        const element = await acclaim.createElement('trq_s3UBMW8il18ICbev1EUdKT1Fclwbnd3EUjxkqkpj6N6FfE6gJRWVEtO2ZpM95eRSThzxWdV77fLlMNNKovx0Rq5JEmdxNOv2gjMMlrGe90AEwy6f3Nxx05INZrAo4AyL');
        await element.mount('#payment-container');

        // Handle the submission of the form the Payment Element is embedded within
        const theForm = document.getElementById('payment-form');
        theForm.addEventListener('submit', async (e) => {
            e.preventDefault();

            // Hide any previous error messages
            hideError();

            const submitButton = document.querySelector('#submit-button');
            submitButton.disabled = true;
            submitButton.textContent = 'Processing...';

            try {
                const result = await element.submit();

                if (result.status === 'succeeded') {
                    window.location.href = '/success';
                } else {
                    throw new Error(result.error?.message || 'Payment failed');
                }
            } catch (error) {
                showError(error.message);
                submitButton.disabled = false;
                submitButton.textContent = 'Pay Now';
            }

            return false;
        });
    }

    function showError(message) {
        const errorElement = document.querySelector('#error-message');
        errorElement.textContent = message;
        errorElement.style.display = 'block';
    }

    function hideError() {
        const errorElement = document.querySelector('#error-message');
        errorElement.style.display = 'none';
    }

    setupPayment();
</script>

Processing Payments

Processing payments in Acclaim Collect happens in two major steps:

Create a Payment Request: an instruction to collect money from a payer
Process the Payment: by either (a) confirming a payment method supplied via UI, or (b) charging a previously saved token

Payment Requests provide a consistent flow for collecting premiums, deductibles, fees, or partner remittances across multiple PSPs.

Creating a Payment Request

The full list of request parameters can be found here.

POST https://api.withacclaim.com/v1/payment_requests
Content-Type: application/json
Authorization: Bearer myApiKey

{
    "payer_id": "pyr_93LdZvQ19a",
    "amount": 12000,
    "currency": "usd",
    "description": "April premium",
    "payment_method_id": "pm_4NtzLp83Da"
}

Processing a Payment Request

Once the payment request has a payer and payment method assigned, or collected, it is ready to be processed, which will create a payment. The Process Payment Request documentation has more details.

POST https://api.withacclaim.com/v1/payment_requests/{payment_request_id}/process
Content-Type: application/json
Authorization: Bearer myApiKey

Response: (abbreviated)

{
  "status": "succeeded"
}

Tracking Payment State

You can track the status of a payment request in two ways:

Polling from your backend

GET /v1/payment_requests/{payment_request_id}

Useful for synchronous flows or to verify final state after a redirect.

Listening for webhooks

Acclaim sends webhook events for all major lifecycle changes:

payment_request.succeeded
payment_request.failed
tokenization_request.succeeded

Handling Failed Payments

When a payment request moves to a failed state:

You may:

Present the payer with a link to re-enter payment details
Trigger a new tokenization request
Retry with a fallback PSP (if configured)
Mark the invoice as overdue in your internal billing system

Acclaim returns granular error codes to help categorize failed payments (insufficient funds, authentication failed, payment method unsupported, network issues, etc.).

Summary

A Payment Request is the core object for charging payers.
Payments can be processed immediately using a saved token, or interactively using the Payment Element.
Acclaim manages the full lifecycle, including PSP routing, authentication, and error handling.
Use webhooks to reliably update your systems when payments succeed or fail.