> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Payer Name
> Submits a payer name for review. Send JSON, or `multipart/form-data` when supporting documents ride along with the submission. In sandbox the name is approved and activated immediately and comes back as `active`.
Submits a payer name — the name your beneficiary sees on a payout — for review. The submission lands in the same review queue as one made in the dashboard.
Request bodies here are **snake\_case** (`display_name`, `entity_type`); responses are **camelCase** (`name`, `type`). Payouts use a third spelling, `payerNameId`, in line with the rest of [Withdraw Funds](/api-reference/endpoint/wallet/withdraw).
## Example Request (business, JSON)
Use JSON when your account does not require supporting documents, or when you will attach them in a second call.
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/payer-names" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "business",
"display_name": "Acme Trading Ltd",
"registration_number": "RC1234567",
"registration_date": "2019-04-02",
"country": "NG",
"address_line": "14 Marina Road",
"city": "Lagos",
"state_province": "Lagos",
"postal_code": "101001",
"metadata": { "vendor_id": "V-4471" }
}'
```
## Example Request (individual, with documents)
Send `multipart/form-data` to submit the name and its documents in one round trip. Repeat the `documents` field once per file; `documentDescriptions` labels them positionally.
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/payer-names" \
-H "X-API-Key: your_api_key_here" \
-F "entity_type=individual" \
-F "display_name=Ada Obi" \
-F "first_name=Ada" \
-F "last_name=Obi" \
-F "country=NG" \
-F "address_line=14 Marina Road" \
-F "city=Lagos" \
-F "state_province=Lagos" \
-F "documents=@passport.pdf" \
-F "documentDescriptions=International passport"
```
Multipart fields all arrive as text, so `metadata` cannot be sent this way — it is rejected with a `400`. Submit with documents first, then set metadata with [Update Payer Name](/api-reference/endpoint/payer-names/update).
## Example Response
```json theme={null}
{
"status": 201,
"message": "Payer name submitted for review",
"success": true,
"data": {
"id": "9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f",
"type": "business",
"name": "Acme Trading Ltd",
"firstName": null,
"lastName": null,
"registrationNumber": "RC1234567",
"registrationDate": "2019-04-02",
"country": "NG",
"address": { "line1": "14 Marina Road", "city": "Lagos", "state": "Lagos", "postalCode": "101001" },
"status": "pending_review",
"isDefault": false,
"decisionNote": null,
"documents": [],
"metadata": { "vendor_id": "V-4471" },
"createdAt": "2026-09-01T09:14:22.000Z",
"updatedAt": "2026-09-01T09:14:22.000Z"
}
}
```
## Fields
| Field | Type | Required | Notes |
| -------------------------- | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_type` | string | Yes | `individual` or `business` |
| `display_name` | string | Yes | What the beneficiary sees. Max 255 characters |
| `first_name` / `last_name` | string | No | Individuals only. Send the name already split — we do not guess where to split it |
| `registration_number` | string | No | Company registration number, or a government ID number for an individual |
| `registration_date` | string | No | `YYYY-MM-DD` |
| `country` | string | Yes | ISO 3166-1 alpha-2, or a country name we can resolve to one. Anything that does not resolve to two letters is rejected |
| `address_line` | string | Yes | Max 500 characters |
| `city` | string | Yes | |
| `state_province` | string | Yes | |
| `postal_code` | string | No | |
| `metadata` | object | No | Flat key/value data of your own, echoed back on responses and webhooks. Values may be strings (max 500 characters), numbers or booleans. JSON requests only |
| `documents` | file(s) | Conditional | Required when `requirements.documentsRequired` is `true` for your account. PDF, JPEG, PNG or Word, up to 10MB each |
| `documentDescriptions` | string(s) | No | Labels the files positionally |
Documents are read by Rolla's reviewers only. They are stored privately, are never forwarded to a payout rail, and are served through signed links that expire after an hour.
## After you submit
The name comes back as `pending_review` and is not usable yet. Review resolves it to `approved` (from which it moves on to registration), `changes_requested`, or `rejected` — subscribe to the [payer name webhook events](/api-reference/webhooks/events#payer-name-events) rather than polling. The full lifecycle is in the [Named Payouts guide](/guides/named-payouts#the-lifecycle).
**In sandbox, a submission is approved and activated immediately** and comes back as `active`, so you can exercise attaching it to a payout without waiting on a reviewer.
## Errors
| Status | Cause |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | A field is missing or malformed, or your account requires a document and none was attached |
| `403` | Named Payouts are not enabled for this account (`code: PAYER_NAMES_DISABLED`) |
| `409` | You already have a payer name with this name in review or approved. Names are compared case-insensitively; a rejected or archived name does not block reuse |
## OpenAPI
````yaml POST /payer-names
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/payer-names:
post:
summary: Create Payer Name
description: >-
Submits a payer name for review. Send JSON, or `multipart/form-data`
when supporting documents ride along with the submission. In sandbox the
name is approved and activated immediately and comes back as `active`.
operationId: createPayerName
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayerNameRequest'
example:
entity_type: business
display_name: Acme Trading Ltd
registration_number: RC1234567
registration_date: '2019-04-02'
country: NG
address_line: 14 Marina Road
city: Lagos
state_province: Lagos
postal_code: '101001'
metadata:
vendor_id: V-4471
multipart/form-data:
schema:
type: object
description: >-
Use this when attaching documents with the submission. Every
field arrives as text, so `metadata` cannot be sent this way —
set it afterwards with a JSON update.
required:
- entity_type
- display_name
- country
- address_line
- city
- state_province
properties:
entity_type:
type: string
enum:
- individual
- business
description: Whether the payer is a company or a person.
example: business
display_name:
type: string
minLength: 1
maxLength: 255
description: >-
The name the beneficiary sees. Must be unique among your
payer names that are in review or approved, compared
case-insensitively.
example: Acme Trading Ltd
first_name:
type: string
maxLength: 120
nullable: true
description: >-
Individuals only. Send the name already split rather than
letting us guess where to split it.
last_name:
type: string
maxLength: 120
nullable: true
description: Individuals only.
registration_number:
type: string
maxLength: 120
nullable: true
description: >-
Company registration number, or a government ID number for
an individual.
example: RC1234567
registration_date:
type: string
nullable: true
pattern: ^\d{4}-\d{2}-\d{2}$
description: YYYY-MM-DD.
example: '2019-04-02'
country:
type: string
minLength: 1
maxLength: 100
description: >-
The payer's country. ISO 3166-1 alpha-2, or a country name
we can resolve to one. Anything that does not resolve to two
letters is rejected with a `400`.
example: NG
address_line:
type: string
minLength: 1
maxLength: 500
example: 14 Marina Road
city:
type: string
minLength: 1
maxLength: 120
example: Lagos
state_province:
type: string
minLength: 1
maxLength: 120
example: Lagos
postal_code:
type: string
maxLength: 32
nullable: true
example: '101001'
documents:
type: array
items:
type: string
format: binary
description: >-
Supporting files. PDF, JPEG, PNG or Word (`.doc`, `.docx`),
up to 10MB each. Repeat the field to attach more than one.
documentDescriptions:
type: array
items:
type: string
description: >-
Labels for the files, positionally: the first value labels
the first file. Repeat the field once per file.
example:
entity_type: individual
display_name: Ada Obi
first_name: Ada
last_name: Obi
country: NG
address_line: 14 Marina Road
city: Lagos
state_province: Lagos
documentDescriptions:
- International passport
responses:
'201':
description: >-
Payer name submitted for review. In sandbox the message is `Payer
name created` and the name comes back as `active`.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code, repeated in the body
example: 201
message:
type: string
example: Payer name submitted for review
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/PayerName'
example:
status: 201
message: Payer name submitted for review
success: true
data:
id: 9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f
type: business
name: Acme Trading Ltd
firstName: null
lastName: null
registrationNumber: RC1234567
registrationDate: '2019-04-02'
country: NG
address:
line1: 14 Marina Road
city: Lagos
state: Lagos
postalCode: '101001'
status: pending_review
isDefault: false
decisionNote: null
documents: []
metadata:
vendor_id: V-4471
createdAt: '2026-09-01T09:14:22.000Z'
updatedAt: '2026-09-01T09:14:22.000Z'
'400':
description: >-
Bad request — a field is missing or malformed, or your account
requires a supporting document and none was attached
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 400
message: >-
At least one supporting document is required — attach a
business registration, ID or similar to justify this payer
name
'401':
description: Unauthorized — invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — Named Payouts are not enabled for this account
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 403
message: >-
Payer names are not enabled for this account. Contact your
Rolla account manager to turn them on.
code: PAYER_NAMES_DISABLED
'409':
description: >-
Conflict — you already have a payer name with this name in review or
approved
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 409
message: >-
You already have a payer name "Acme Trading Ltd" in progress
or approved
components:
schemas:
PayerNameRequest:
type: object
description: A payer name submission. Field names are snake_case.
required:
- entity_type
- display_name
- country
- address_line
- city
- state_province
properties:
entity_type:
type: string
enum:
- individual
- business
description: Whether the payer is a company or a person.
example: business
display_name:
type: string
minLength: 1
maxLength: 255
description: >-
The name the beneficiary sees. Must be unique among your payer names
that are in review or approved, compared case-insensitively.
example: Acme Trading Ltd
first_name:
type: string
maxLength: 120
nullable: true
description: >-
Individuals only. Send the name already split rather than letting us
guess where to split it.
last_name:
type: string
maxLength: 120
nullable: true
description: Individuals only.
registration_number:
type: string
maxLength: 120
nullable: true
description: >-
Company registration number, or a government ID number for an
individual.
example: RC1234567
registration_date:
type: string
nullable: true
pattern: ^\d{4}-\d{2}-\d{2}$
description: YYYY-MM-DD.
example: '2019-04-02'
country:
type: string
minLength: 1
maxLength: 100
description: >-
The payer's country. ISO 3166-1 alpha-2, or a country name we can
resolve to one. Anything that does not resolve to two letters is
rejected with a `400`.
example: NG
address_line:
type: string
minLength: 1
maxLength: 500
example: 14 Marina Road
city:
type: string
minLength: 1
maxLength: 120
example: Lagos
state_province:
type: string
minLength: 1
maxLength: 120
example: Lagos
postal_code:
type: string
maxLength: 32
nullable: true
example: '101001'
metadata:
type: object
additionalProperties:
oneOf:
- type: string
maxLength: 500
- type: number
- type: boolean
description: >-
Flat key/value data of your own, echoed back on responses and
webhooks. Keys are at most 64 characters; values may be strings (max
500 characters), numbers or booleans. JSON requests only — a
multipart request cannot carry it.
example:
vendor_id: V-4471
PayerName:
type: object
description: >-
A payer name: the name a beneficiary sees on a payout you send.
Responses are camelCase; request bodies are snake_case.
properties:
id:
type: string
format: uuid
example: 9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f
type:
type: string
enum:
- individual
- business
example: business
name:
type: string
description: The name shown to the beneficiary.
example: Acme Trading Ltd
firstName:
type: string
nullable: true
description: Individuals only; `null` for a business.
lastName:
type: string
nullable: true
description: Individuals only; `null` for a business.
registrationNumber:
type: string
nullable: true
example: RC1234567
registrationDate:
type: string
nullable: true
format: date
example: '2019-04-02'
country:
type: string
description: ISO 3166-1 alpha-2 country code.
example: NG
address:
type: object
properties:
line1:
type: string
example: 14 Marina Road
city:
type: string
example: Lagos
state:
type: string
example: Lagos
postalCode:
type: string
nullable: true
example: '101001'
status:
type: string
enum:
- pending_review
- changes_requested
- processing
- active
- action_required
- rejected
- archived
description: >-
Where the payer name has got to: Rolla review and provider
registration collapsed into one value. Only `active` is fully
usable. Note that the `status` query filter on List Payer Names
takes review statuses instead, where `approved` covers `processing`,
`active` and `action_required`.
example: active
isDefault:
type: boolean
description: Applied to payouts that do not name a payer name.
example: false
decisionNote:
type: string
nullable: true
description: >-
The reviewer's note, verbatim. Set on `changes_requested` and
`rejected`, cleared on an update.
documents:
type: array
items:
$ref: '#/components/schemas/PayerNameDocument'
metadata:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
description: >-
Your own flat key/value data, echoed back verbatim. Omitted entirely
when you have not set any.
example:
vendor_id: V-4471
createdAt:
type: string
format: date-time
example: '2026-09-01T09:14:22.000Z'
updatedAt:
type: string
format: date-time
example: '2026-09-02T11:02:41.000Z'
Error:
type: object
required:
- status
- message
description: >-
Error envelope. Some errors add further top-level fields (for example
`accountBlocked`, `provider`, `missingFields`); the endpoint documents
them where they apply.
additionalProperties: true
properties:
status:
type: integer
description: HTTP status code, repeated in the body as a number
example: 400
message:
type: string
description: Human-readable description of what went wrong
example: Validation failed
code:
type: string
description: >-
Machine-readable error code, present on some errors only. See the
Errors concept page for the taxonomy.
example: ACCOUNT_RESTRICTED
errors:
type: array
description: 'Present on `400` validation failures: one entry per offending field'
items:
type: object
properties:
path:
type: array
items:
type: string
example:
- amount
message:
type: string
example: >-
amount must be a whole number of smallest currency units (e.g.
cents)
PayerNameDocument:
type: object
description: >-
A supporting document attached to a payer name. Read by Rolla review
only; never forwarded to a payout rail.
properties:
id:
type: string
format: uuid
example: 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091
fileName:
type: string
example: certificate-of-incorporation.pdf
description:
type: string
nullable: true
description: >-
The label you sent in `documentDescriptions`, or `null` for an
unlabelled file.
example: Certificate of incorporation
fileType:
type: string
description: MIME type.
example: application/pdf
fileSize:
type: integer
description: Size in bytes.
example: 284122
downloadUrl:
type: string
description: >-
Signed URL, valid for 1 hour from the time the response was
generated. An empty string when the stored object is no longer
available.
example: https://files.rolla.xyz/payer_name_docs/...
createdAt:
type: string
format: date-time
example: '2026-09-01T09:14:22.000Z'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````