Orchestrate
Creating Accounts
Accounts API

Creating Accounts via API

Learn when and how to create the different account types via the back-end API

Payload accounts can be useful actors in your orchestration layer. Payers and recipients can be modeled as an Account. This guide shows how to create accounts via the Accounts API, when to use legal entities, and how to configure accounts so they’re ready for invoicing, payments, and payouts.

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.

Creating Customer Accounts

When to create customer accounts via the API

Use the backend /accounts API when you plan to explicitly create and manage customer accounts as part of an isolated workflow, not inline when creating transactions and payment methods, and when using the Enrollment Link or Form is not ideal.

Common use cases

  • Your platform is in charge of onboarding and maintaining customer records.
  • You are bulk-provisioning or migrating customers.
  • The account supports wallets, balances, subscriptions, or multi-step flows.
  • You need deterministic, idempotent account creation outside of a payment request.

Calling the API

Below are a few different examples of creating customer accounts for varying use-cases.

Create a basic customer account

Create a simple customer account with just a name when you don't need entity details or KYC verification. This is ideal for low-risk SaaS billing, early onboarding flows, and guest or trial customers.

create_cust.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a basic customer account
customer = pl.Account.create(
    type='customer',
    name='Acme Corporation'
)
 
print(f"Created customer account: {customer.id}")

This call creates a customer account with only two fields:

  • type='customer' tells Payload this account is a payer, not a processing account.
  • name='Acme Corporation' is the display name used in invoices, portals, and reporting.

This pattern is ideal for low-risk SaaS billing where you don’t need full KYC, early onboarding flows where you want to track billing before collecting full details, and guest or trial customers (often combined with keep_active=false, discussed later).

Response Example

{
  "id": "acc_1a2b3c4d5e6f",
  "object": "account",
  "type": "customer",
  "name": "Acme Corporation",
  "email": null,
  "entity": null,
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Create a customer account with an individual entity

When you need KYC-level information for a person (for example, higher-risk payments, regulatory requirements, or future merchant upgrades), embed an individual entity inline on the account.

create_cust_entity.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create customer with individual entity details
customer = pl.Account.create(
    type='customer',
    name='John Smith',
    entity={
        'type': 'individual',
        'legal_name': 'John Smith',
        'country': 'US',
        'phone_number': '1231231234',
        'tax_id': {'value': '123121234'},
        'address': {
            'address_line_1': '123 Example St',
            'city': 'New York',
            'state_province': 'NY',
            'postal_code': '11111',
        },
    },
)
 
print(f"Created individual customer: {customer.id}")
print(f"Entity type: {customer.entity.type}")

Key fields in the inline entity object:

  • type='individual' marks this as a person, not a business.
  • legal_name is the full legal name used for KYC and tax reporting.
  • country (currently US or CA) drives tax ID type and compliance rules.
  • phone_number is the primary contact number for verification and communication.
  • tax_id.value is the 9-digit tax identifier (for example, SSN for US individuals).
  • address is the residential address used for verification (no PO boxes).

Use this pattern when you need to run KYC on a payer, you expect this individual might later become a merchant (so you can reuse the entity), or you want a single source of truth for legal identity tied to the account.

Embedding the entity here creates a new Entity record behind the scenes. If the same person will have multiple accounts, consider creating the Entity once and referencing it via entity_id instead.

Create multiple customers in a single call

If you’re migrating large numbers of customers from a legacy system, you may import in bulk for improved performance.

bulk_create_custs.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create multiple customers at once
customers = pl.Account.create(
    [
        {
            "type": "customer",
            "name": "Customer One",
            "contact_details": {"email": "[email protected]"},
        },
        {
            "type": "customer",
            "name": "Customer Two",
            "contact_details": {"email": "[email protected]"},
        },
        {
            "type": "customer",
            "name": "Customer Three",
            "contact_details": {"email": "[email protected]"},
        },
    ],
)
 
print(f"Created {len(customers)} customers")
for customer in customers:
    print(f"  - {customer.name} ({customer.contact_details.email})")

Here you pass object='list' to signal a bulk operation and values as an array of account objects, each with type='customer', email, and name.

Use this when migrating thousands of existing customers into Payload or running backfills and sync jobs from an external CRM or billing system.

Creating Processing Accounts (Advanced use only)

When to create processing accounts via the API

Create processing accounts via backend API when you need full control over the onboarding UX and data model, and are comfortable handling the compliance and legal requirements that our embedded enrollment form or enrollment link normally abstracts away.

In these advanced integrations, you are responsible for ensuring the submitter is presented with and explicitly agrees to our terms and required disclosures at the time of enrollment, and for capturing that consent in your own system.

Common use cases

  • You have a rich internal merchant/tenant model and need tight alignment with your own onboarding flow.
  • You want to pre-provision or bulk-create processing accounts (migrations, automation, multi-tenant setups).
  • You need to orchestrate custom risk/KYB steps or conditional questions based on your own logic.
  • You must integrate account creation into an existing signup or configuration workflow instead of a standalone hosted form.

Calling the API

Below is an example of creating processing accounts via the back-end API

create_processing.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
account = pl.Account.create(
    # Create processing account with business entity details
    type="processing",
    name="Example LLC",
    entity={
        "type": "business",
        "legal_name": "Example LLC",
        "country": "US",
        "phone_number": "1231231234",
        "tax_id": {"value": "123121234"},
        "address": {
            "address_line_1": "123 Example St",
            "city": "New York",
            "state_province": "NY",
            "postal_code": "11111",
        },
        "business": {
            "category": "real_estate",
            "structure": "llc",
            "website": "https://example.com",
            "formation": {"state_province": "NY", "date": "2019-10-01"},
            "primary_contact": {
                "name": "John Smith",
                "email": "[email protected]",
            },
            "stakeholders": [
                {
                    "country": "US",
                    "personal_information": {
                        "full_name": "John Smith",
                        "email": "[email protected]",
                        "birth_date": "1990-05-10",
                        "phone_number": "1231231234",
                    },
                    "address": {
                        "address_line_1": "123 Example St",
                        "city": "New York",
                        "state_province": "NY",
                        "postal_code": "11111",
                    },
                    "govt_id": {"tax_id": {"value": "123121234"}},
                    "association": {
                        "title": "CEO",
                        "ownership": {"percentage": 100, "years_owned": "5"},
                        "roles": {},
                    },
                }
            ],
        },
    },
)
 
print(f"Created processing account: {account.id}")
print(f"Business category: {account.entity.business['category']}")
print(f"Stakeholders: {len(account.entity.business['stakeholders'])}")

This call creates a processing account with the following fields:

  • type='processing' tells Payload this account is a processing account, not a payer.
  • entity=pl.Entity(type=’business’, ....) is required. Processing accounts require an attached business entity.

This pattern will create a full processing account via API, and initiates the KYC process. It's important to ensure the agreement terms are captured before submitting the processing account info via the API.

Next Steps

Layer on payment methods, billing, merchant onboarding, and reporting

Configure Billing and Autopay

Start with Creating Invoices for customer billing, set up Billing Schedules for recurring charges, and enable autopay with Payment Link, Payment Method API, Payment Portal, or Secure Form.

Onboard Merchants as Processing Accounts

Create verified entities with Creating Entities, configure Processing Accounts for marketplace sellers, set up Processing Settings for transaction rules, and monitor KYC Results for compliance.

Build Reporting and Reconciliation

Understand the Reporting Overview to track financial data, learn Building Report Queries for custom reports, and use Payment Reports and Invoice Reports for financial reconciliation.

Add Payment Methods

Store customer payment methods with Payment Method API, configure Default Payment Methods for autopay and payouts, and enable digital wallets like Apple Pay and Google Pay.

Related articles

OverviewEnrollment Link