Skip to navigation

Create a new payer

View as Markdown

Create a new payer in the system.

A payer is an entity that sends money to your platform via ACH debit transactions. Each payer must have a unique email address within your organization.

Required Information

When creating a payer, you must provide:

  • Email: Must be unique within your organization
  • Name: Full name of the payer

Validation

name and email follow the same rules as Create a new payee:

  • Name: letters A–Z and a–z, characters in U+00C0–U+017F (accented Latin letters such as é, ñ, ü, plus × and ÷), digits, spaces, hyphens (-), underscores (_), and straight apostrophes ('). Any other character is rejected, including &, ,, ., /, (, ), en and em dashes, and curly apostrophes (’). Leading and trailing spaces are removed, and runs of whitespace become one space.
  • Email: must be a valid address. Addresses on special-use domains are rejected: .arpa, .invalid, .local, .localhost, .onion, and .test.

Response

Returns the newly created payer object with:

  • Unique payer ID
  • All provided information
  • Timestamps for creation and last update

Errors

Status CodeError CodeDescription
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action
409DUPLICATE_RESOURCEA payer with this email already exists. details.duplicate_fields is ["email"].
422VALIDATION_ERRORThe request body failed validation, for example a name with characters that are not allowed or an email on a reserved domain. details.errors[] lists each failing field and its message.

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

Request

This endpoint expects an object.
namestringRequired1-255 characters

Name may contain only letters A-Z and a-z, characters in U+00C0-U+017F (accented Latin letters such as é, ñ, ü, ł, plus × and ÷), digits, spaces, hyphens (-), underscores (_), and straight apostrophes (’). Other punctuation, such as & , . / ( ), en or em dashes, and curly apostrophes (’), is not allowed.

emailstringRequiredformat: "email"<=255 characters

Must be a valid email address. Special-use domains are rejected: .arpa, .invalid, .local, .localhost, .onion, and .test.

country_codeenumOptional
Allowed values:
country_sub_divisionstring or nullOptional<=35 characters
State, province, or country subdivision
citystring or nullOptional<=35 characters
City or town name
address_linestring or nullOptional<=500 characters
Street address, building number, postal code, etc.
postal_codestring or nullOptional<=16 characters
Zip or postal code
metadatamap from strings to strings or nullOptional

Response

Payer created successfully
dataobject
warningstring or nullOptional