Orchestrate
Creating Accounts
Enrollment Plugin
Open in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

Creating Accounts via the Enrollment Plugin

Learn when and how to create the different account types via the enrollment plugin

Payload accounts can be useful actors in your orchestration layer. Payers and recipients can be modeled as an Account. This guide covers how to create processing accounts using the Enrollment Plugin, including when to use it and how to configure it for your onboarding flow.

Prerequisites

Before writing any code, it’s helpful to learn about the following topics.

How to use accounts and pick the right type

Learn the difference between customer, processing, and generic account types, and when to use each type.

Learn when to use entities to verify

Learn when to include entity information with an account for higher-risk payments, KYC and regulatory requirements.

When to use the Enrollment Plugin

Create processing accounts via the enrollment plugin when you need an embedded onboarding flow inside your application. By using the plugin, compliance, consent, and other legal requirements are handled automatically and abstracted away.

Use the enrollment plugin when you want a turnkey, compliant, and low-code way to onboard processing accounts without handling sensitive data, terms presentation, or regulatory flow logic yourself. The plugin ensures the submitter is shown and agrees to all required terms, captures attestations, and collects sensitive information directly within a hosted, PCI-compliant environment—removing that responsibility from your application.

Common use cases

  • You want an embedded onboarding flow inside your application (iframe or inline widget) rather than redirecting users to a standalone enrollment link
  • You want a consistent, compliant UX across web, mobile, and low-code platforms
  • You don’t want to handle sensitive identity, business, or financial data directly

Usage

There are two steps to using the plugin: creating an intent and passing that to the plugin on the front end.

The examples below show both steps in two different form factors.

app.py
modal.html
modal.js
PythonRubyPHPNode.jsC#JavaShell
ReactJavaScript
import os
 
import payload
from flask import Flask, jsonify
 
pl = payload.Session(os.getenv('PL_API_KEY'))
app = Flask(__name__)
 
 
@app.route('/enroll_intent')
def get_enroll_intent():
    enroll_intent = pl.Intent.create(type='account_enrollment_plugin')
 
    return jsonify({'token': enroll_intent.token})
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Enroll Button - Vanilla JS</title>
  <script src="https://payload.com/Payload.js"></script>
</head>
<body>
  <button id="enroll-btn" disabled>Open Processing Account Form Modal</button>
 
  <script src="modal.js"></script>
</body>
</html>
const btn = document.getElementById('enroll-btn');
 
// Fetch token and enable button
fetch('/enroll_intent')
  .then(r => r.json())
  .then(data => {
    btn.disabled = false;
    btn.onclick = () => {
      Payload(data.token);
      new Payload.ProcessingAccount()
        .on('success', evt => console.log(evt.account.id))
        .on('closed', evt => console.error('Closed:', evt));
    };
  })
  .catch(err => console.error('Failed to load client token:', err));

This example shows the steps to setting up the plugin as a modal overlay and capturing the result.

  1. Create intent token with type='account_enrollment_plugin' and provide the token value to the front-end
  2. Use the token to launch the EnrollmentPlugin on the front-end
  3. Use the onSuccess(evt) listener to capture the ID of a newly onboarded account

This pattern will create a full processing account via the plugin and initiates the KYC process. To monitor the results of the KYC process, subscribe to the related webhook trigger.

app.py
inline.html
inline.js
PythonRubyPHPNode.jsC#JavaShell
ReactJavaScript
import os
 
import payload
from flask import Flask, jsonify
 
pl = payload.Session(os.getenv('PL_API_KEY'))
app = Flask(__name__)
 
 
@app.route('/enroll_intent')
def get_enroll_intent():
    enroll_intent = pl.Intent.create(type='account_enrollment_plugin')
 
    return jsonify({'token': enroll_intent.token})
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Enroll Form - Vanilla JS</title>
  <script src="https://payload.com/Payload.js"></script>
</head>
<body>
  <h3>Embedded Processing Form</h3>
  <div id="form-container">Loading...</div>
 
  <script src="inline.js"></script>
</body>
</html>
// Fetch token and mount inline form
fetch('/enroll_intent')
  .then(r => r.json())
  .then(data => {
    Payload(data.token);
    new Payload.ProcessingAccount({
      inline: true,
      container: '#form-container'
    })
      .on('success', evt => console.log('Account created:', evt.account.id))
      .on('closed', evt => console.error('Closed:', evt));
  })
  .catch(err => {
    console.error('Failed to load client token:', err);
    document.getElementById('form-container').textContent = 'Failed to load form';
  });

This example shows the steps to setting up the plugin as an inline form embedded directly in your page.

  1. Create intent token with type='account_enrollment_plugin' and provide the token value to the front-end
  2. Use the token to mount the inline form using inline: true and specify a container
  3. Use the onSuccess(evt) listener to capture the ID of a newly onboarded account

This pattern will create a full processing account via the plugin and initiates the KYC process. To monitor the results of the KYC process, subscribe to the related webhook trigger.

Enrollment Plugin Options

The Intent schema defines the structure and properties of intent objects in the Payload API. Intents represent various types of user interactions and requests, including checkout links, payment forms, enrollment links, and more.

Intent Options

Available fields that can be used when creating the intent object

account_enrollment_plugin
object
Configuration for the account enrollment plugin intent. Use this type to embed an onboarding form in your application using the Payload JavaScript SDK. The enrollment plugin allows businesses to sign up for payment processing, providing their business information and undergoing verification. Returns a token for rendering the enrollment UI with the SDK. Required when type is account_enrollment_plugin.
account_template
object
Pre-filled account information for the enrollment. Includes the account ID (to link to an existing account) and account type (processing). Use this to pre-populate account details or associate the enrollment with an existing account record.
entity
object
A list of prefilled values for the enrolled account's legal entity. When provided, these values will populate the corresponding fields in the enrollment form.
country
enum[string]
The country that the enrolled legal entity is registered in. Valid countries to register are currently Canada ("CA") and the United States of America ("US").
Values: CA, US
legal_name
string
Pre-filled legal name for the entity being enrolled. For businesses, this is the registered legal business name. For individuals, this is the person's full legal name. When provided, this value will populate the legal name field in the enrollment form.
type
enum[string]
Optional type of legal entity being enrolled. When provided, it must be either "business" (for companies, organizations, or business entities) or "individual" (for individual persons). When omitted, the recipient can choose in the enrollment form. Determines which onboarding fields and verification requirements apply.
Values: business, individual
id
string
Pre-filled unique identifier for the account being enrolled. When provided, this existing account will be used. If not provided, a new account will be created during enrollment. Use this to link enrollment to an existing account record.
payment_methods
array
A list of payment method templates with prefilled values that will be applied to payment methods associated with this merchant account during enrollment.
account_defaults
object
Default transaction types that this payment method will be used for. Controls whether the payment method is the default for paying or funding transactions, and which specific types of transactions it applies to.
funding
enum[string]
Controls which funding transaction types this payment method can be used for. Possible values: "all" (use for all funding transactions), "deposits" (use only for receiving deposits), or "withdraws" (use only for withdrawals). Determines the default usage for receiving funds.
Values: all, deposits, withdraws
paying
enum[string]
Controls which paying transaction type this payment method will be the default for. Possible values: "all" (use for all paying transactions), "payments" (use only for sending payments), or "payouts" (use only for receiving payouts). Determines the default usage for sending funds. If the account default is set for payments, that payment method will be used for any automatic invoice payments.
Values: all, payments, payouts
account_holder
string
Pre-filled name of the account holder for the payment method. For bank accounts, this is the name on the account. For cards, this is the cardholder name. When provided, this value will be used to populate the form.
account_id
string
The ID of the account that will own this payment method. Links the payment method to a specific customer or processing account. Used to associate the payment method with the correct account when it is created.
bank_account
object
Configuration specific to bank account payment methods. Contains bank account-specific settings such as the currency.
currency
enum[string]
The currency for bank account transactions. Must be either "USD" (US Dollars) or "CAD" (Canadian Dollars). Determines the currency for transactions using this bank account.
Values: USD, CAD
billing_address
object
Pre-filled billing address for the payment method. When provided, these values will be used to populate the address fields in the checkout form. Customers may be able to edit these values depending on checkout configuration.
address_line_1
string
Street address of the address
address_line_2
string
Unit number of the address
city
string
City of the company
country_code
string
Country code of the address
postal_code
string
Postal code of the address
state_province
string
State of the address
id
string
The unique identifier of an existing payment method to update. When provided, the form will be used to update the payment method, such as revalidating the CVV, updating the expiration date, or changing the billing address.
transfer_type
enum[string]
The transfer capabilities for this payment method. Possible values: "send_only" (can only send payments/fund payouts), "receive_only" (can only receive payouts/deposits), or "two_way" (can both send and receive). Controls how the payment method can be used for transactions.
Values: send_only, receive_only, two_way
type
enum[string]
The type of account being enrolled. Currently only "processing" is supported for account enrollment, which creates a merchant/processor account capable of receiving payments and sending payouts.
Values: processing

Plugin Options

Available fields that can be used when setting up the enrollment plugin on the front-end

hide_fee_schedule
boolean
Optional boolean that, when set to true, suppresses the display of the fee schedule on the enrollment form. Use this when you need a cleaner or simplified onboarding experience and prefer to manage fee disclosures separately.
inline
boolean
Optional boolean that, when set to true, renders the enrollment form inline within your page container instead of using a modal overlay. Use this when the form should feel native to your application's layout or when modal interactions are not desired.
container
object
Optional DOM element that specifies where the enrollment form should be rendered when inline is set to true. Provide an HTML element or selector to embed the form directly into your page's layout.

Next Steps

Configure payment routing, monitor KYC results, and build payment flows

Configure Processing Settings and Monitor Onboarding

Set up Processing Settings to configure payment routing and processing preferences, monitor identity verification with KYC Results, subscribe to Webhook Events for account and KYC status updates, and review Processing Accounts Overview to understand processing account capabilities.

Create Payment Flows for Merchants

Accept payments on behalf of processing accounts with Creating Payment Intents, store and manage customer payment methods using Payment Methods, and send payouts to processing accounts with Creating Transfers.

Build Reporting and Reconciliation

Track enrollment and payment metrics with Reporting Overview, create custom reports using Building Report Queries, and monitor payment activity with Transaction Reports for financial reconciliation.

Explore Alternative Onboarding Methods

Generate shareable enrollment URLs with Enrollment Link for email or SMS distribution, or use Accounts API for full programmatic control over account creation and onboarding workflows.

Related articles

Enrollment LinkDefault Methods