This guide walks through the core flow:

Create a Payer and Setup Request
Securely capture and store the payment method using Payment Element
Charge the payment method using Payment Requests

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": "jane@example.com",
}

Creating a Setup Request

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

POST https://api.withacclaim.com/v1/setup_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
Confirm the Payment Request: 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"
}

Confirming a Payment Request

Once the payment request has a payer and payment method assigned, or collected, it is ready to be confirmed, which will attempt to collect payment. The Confirm Payment Request documentation has more details.

POST https://api.withacclaim.com/v1/payment_requests/{payment_request_id}/confirm
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
setup_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 setup 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.). See Payment failures for the complete list of codes and messages.

Summary

A Payment Request is the core object for charging payers.
Payments can be confirmed 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.

DEVELOPER GUIDES

COLLECT

DISBURSE

TREASURY

Quickstart Guide

Collecting Payment Details

Creating a Payer

Example

Creating a Setup Request

Collecting Details Securely with the Payment Element

Processing Payments

Creating a Payment Request

Confirming a Payment Request

Tracking Payment State

Handling Failed Payments

Summary

​Collecting Payment Details

​Creating a Payer

​Example

​Creating a Setup Request

​Collecting Details Securely with the Payment Element

​Processing Payments

​Creating a Payment Request

​Confirming a Payment Request

​Tracking Payment State

​Handling Failed Payments

​Summary

Collecting Payment Details

Creating a Payer

Example

Creating a Setup Request

Collecting Details Securely with the Payment Element

Processing Payments

Creating a Payment Request

Confirming a Payment Request

Tracking Payment State

Handling Failed Payments

Summary