Create Payer Name
curl --request POST \
--url https://api.rolla.xyz/api/v1/external/payer-names \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"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"
}
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/payer-names"
payload = {
"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" }
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://api.rolla.xyz/api/v1/external/payer-names', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/payer-names",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rolla.xyz/api/v1/external/payer-names"
payload := strings.NewReader("{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/payer-names")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/payer-names")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}{
"status": 400,
"message": "At least one supporting document is required — attach a business registration, ID or similar to justify this payer name"
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 403,
"message": "Payer names are not enabled for this account. Contact your Rolla account manager to turn them on.",
"code": "PAYER_NAMES_DISABLED"
}{
"status": 409,
"message": "You already have a payer name \"Acme Trading Ltd\" in progress or approved"
}Payer Names (Named Payouts)
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.
POST
/
payer-names
Create Payer Name
curl --request POST \
--url https://api.rolla.xyz/api/v1/external/payer-names \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"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"
}
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/payer-names"
payload = {
"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" }
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://api.rolla.xyz/api/v1/external/payer-names', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/payer-names",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rolla.xyz/api/v1/external/payer-names"
payload := strings.NewReader("{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/payer-names")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/payer-names")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entity_type\": \"business\",\n \"display_name\": \"Acme Trading Ltd\",\n \"registration_number\": \"RC1234567\",\n \"registration_date\": \"2019-04-02\",\n \"country\": \"NG\",\n \"address_line\": \"14 Marina Road\",\n \"city\": \"Lagos\",\n \"state_province\": \"Lagos\",\n \"postal_code\": \"101001\",\n \"metadata\": {\n \"vendor_id\": \"V-4471\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}{
"status": 400,
"message": "At least one supporting document is required — attach a business registration, ID or similar to justify this payer name"
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 403,
"message": "Payer names are not enabled for this account. Contact your Rolla account manager to turn them on.",
"code": "PAYER_NAMES_DISABLED"
}{
"status": 409,
"message": "You already have a payer name \"Acme Trading Ltd\" in progress or approved"
}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.Example Request (business, JSON)
Use JSON when your account does not require supporting documents, or when you will attach them in a second call.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)
Sendmultipart/form-data to submit the name and its documents in one round trip. Repeat the documents field once per file; documentDescriptions labels them positionally.
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.Example Response
{
"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 aspending_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 rather than polling. The full lifecycle is in the Named Payouts guide.
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 |
Authorizations
Your Rolla API key
Body
application/jsonmultipart/form-data
A payer name submission. Field names are snake_case.
Whether the payer is a company or a person.
Available options:
individual, business Example:
"business"
The name the beneficiary sees. Must be unique among your payer names that are in review or approved, compared case-insensitively.
Required string length:
1 - 255Example:
"Acme Trading Ltd"
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.
Required string length:
1 - 100Example:
"NG"
Required string length:
1 - 500Example:
"14 Marina Road"
Required string length:
1 - 120Example:
"Lagos"
Required string length:
1 - 120Example:
"Lagos"
Individuals only. Send the name already split rather than letting us guess where to split it.
Maximum string length:
120Individuals only.
Maximum string length:
120Company registration number, or a government ID number for an individual.
Maximum string length:
120Example:
"RC1234567"
YYYY-MM-DD.
Pattern:
^\d{4}-\d{2}-\d{2}$Example:
"2019-04-02"
Maximum string length:
32Example:
"101001"
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.
Show child attributes
Show child attributes
Example:
{ "vendor_id": "V-4471" }
Response
Payer name submitted for review. In sandbox the message is Payer name created and the name comes back as active.