Named Payouts

A payout you send arrives at the beneficiary’s bank under your own business name — the name on your Rolla account. That is the default and it needs no setup. Named Payouts add the other names you may legitimately pay under: affiliated payer names for your related entities or your end-customers. Register them, then choose which one a beneficiary sees on each payment. Two situations it solves:

A related entity of yours. A subsidiary, a trading name, or another company in your group pays its own suppliers from your Rolla balance, and the supplier should see that entity rather than the parent.
Your end-customer’s name on payments you send for them. If you move money on behalf of businesses using your product, each payment can go out under the name of the customer it belongs to.

A payer name is not free text on a transaction. It is a registered identity: you submit who the payer is and evidence for it, Rolla reviews it, and it is then registered with our payout partners before any money can move under it. That is what makes it acceptable to the receiving bank — and why the flow has a review step in it.

Named Payouts are off until Rolla turns them on for your account. Until then, every endpoint in this guide answers 403 with code: PAYER_NAMES_DISABLED. Talk to your account manager or support@rolla.xyz to have it enabled.

Checking whether it is on

One call, no side effects:

curl "https://api.rolla.xyz/api/v1/external/payer-names" \
  -H "X-API-Key: your_api_key_here"

A 403 means the feature is not enabled for you. A 200 also tells you whether your account must attach supporting documents to a submission:

{
  "status": 200,
  "message": "Payer names retrieved",
  "success": true,
  "data": {
    "payer_names": [],
    "pagination": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 },
    "requirements": { "documentsRequired": true }
  }
}

Read requirements.documentsRequired before you build your submission flow. Most accounts must send at least one document; Rolla can relax that per account.

Payer names are also managed in the dashboard, under Named Payouts. A name registered there is the same record you read over the API, in the same review queue — teams commonly register names by hand and only use the API to attach them to payouts.

Register a payer name

Submit the payer’s legal identity and the evidence for it. Business payers need their registration details; individual payers need their name split into first and last.

curl -X POST "https://api.rolla.xyz/api/v1/external/payer-names" \
  -H "X-API-Key: your_api_key_here" \
  -F "entity_type=business" \
  -F "display_name=Acme Trading Ltd" \
  -F "registration_number=RC1234567" \
  -F "registration_date=2019-04-02" \
  -F "country=NG" \
  -F "address_line=14 Marina Road" \
  -F "city=Lagos" \
  -F "state_province=Lagos" \
  -F "postal_code=101001" \
  -F "documents=@certificate-of-incorporation.pdf" \
  -F "documentDescriptions=Certificate of incorporation"

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": "individual",
    "display_name": "Ada Obi",
    "first_name": "Ada",
    "last_name": "Obi",
    "registration_number": "A01234567",
    "country": "NG",
    "address_line": "14 Marina Road",
    "city": "Lagos",
    "state_province": "Lagos",
    "metadata": { "customer_id": "cus_8812" }
  }'

display_name is the name the beneficiary sees. Everything else is what the review and the registration are built on. Full field reference on Create Payer Name. Three things that catch people out:

Request bodies are snake_case, responses are camelCase. You send display_name and read back name; you send entity_type and read back type.
metadata cannot be sent on a multipart request. Multipart fields all arrive as text, so submit with documents first and set metadata afterwards with a JSON update.
Documents are for Rolla’s reviewers. PDF, JPEG, PNG or Word, up to 10MB each. They are stored privately and never forwarded to a payout partner.

The lifecycle

A payer name is reviewed by Rolla, then registered with the payout partners that will carry it. Both halves are collapsed into the single status on the record.

pending_review

Submitted and waiting on a Rolla reviewer. You can still edit it, and attach more documents.

changes_requested (if something is wrong)

The reviewer needs a correction. decisionNote says what, in their own words. Update the name to answer, which resubmits it.

processing

Approved by Rolla and being registered with our payout partners. Nothing is required from you. This step is not instant — it can run into hours, occasionally longer, because a partner does its own review.

active

Registered and usable. Payouts can now go out under this name.

Two outcomes end the story instead: rejected, where Rolla declined the name and decisionNote says why, and action_required, where every payout partner refused or errored on the registration. Neither resolves itself — action_required in particular will never become active on its own, so treat it as a prompt to talk to us rather than something to wait out.

Status reference

`status`	Meaning	Usable on a payout?	What to do
`pending_review`	Waiting on a Rolla reviewer	Accepted, but the payout waits	Nothing
`changes_requested`	A correction is needed; see `decisionNote`	Accepted, but the payout waits	Update and resubmit
`processing`	Approved, being registered with our partners	Accepted, but the payout waits	Nothing
`active`	Registered and ready	Yes	Use it
`action_required`	Every partner refused the registration	No	Contact support
`rejected`	Rolla declined it; see `decisionNote`	No — rejected with a `400`	Submit a different name
`archived`	You retired it	No — rejected with a `400`	Submit a new name to use it again

The status filter on List Payer Names takes review statuses rather than these, so approved there covers processing, active and action_required. Filter on approved, then keep the ones returned as active.

Being told, rather than polling

Subscribe to the payer name webhook events and you never have to poll:

Event	Fires when
`payer_name.approved`	Rolla approved the name; registration is starting
`payer_name.changes_requested`	A correction is needed — `data.reason` carries the note
`payer_name.rejected`	Rolla declined the name — `data.reason` carries why
`payer_name.active`	Registered and usable. This is the one that matters operationally
`payer_name.action_required`	Every partner refused; nothing more will happen without us

Pay under a name

Pass payerNameId to Withdraw Funds:

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "USD",
    "beneficiaryId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "description": "Invoice 2291",
    "payerNameId": "9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f"
  }'

Which name a payout goes out under is settled in this order, first match wins:

The payerNameId on the payout

Your explicit choice for this payment.

Your default payer name

Applied whenever payerNameId is omitted. Set one with Set Default Payer Name to apply a name across an integration without touching your payout code.

Your own business name

The default with no setup, and what you still get if you register no names or set no default.

The payer name is recorded on the transaction, so a payout always reports the name it was sent under even if you archive that name later.

A payout attached to a name that is not yet active is accepted, and then waits. This is deliberate: you usually register a name because of a payment you are about to make, and refusing the payout would make you come back and redo it. But the money does not move until the name is usable, so for anything time-sensitive, wait for payer_name.active before sending.

A payerNameId that Rolla cannot use is refused outright and the payout is not created. On POST /wallet/withdraw every such refusal comes back as a 400, whether the name was rejected, archived, unknown, or belongs to another account; the message says which. The payer-name endpoints themselves answer 404 for an unknown id, so do not branch on the status code alone when you call both.

Where the name is applied

Named Payouts apply to USD international wire (SWIFT) payouts only. That is the one rail that carries a registered payer end to end. Attaching a payerNameId to any other rail — ACH, domestic wire, crypto, NGN, XAF, mobile money — does not fall back to your own name. The payout is refused outright with a 400 and nothing is created:

A payer name can only be used on an International Wire (SWIFT) payout. Remove the payer name,
or send this payment to a beneficiary whose withdrawal method is international_wire.

So a default payer name only takes effect on international wire payouts; payouts on every other rail are unaffected by it and go out under your own business name.

Testing in sandbox

A sandbox submission is approved and activated immediately, with no reviewer and no partner registration. Create a payer name with a sandbox key and it comes back as active, ready to attach to a payout — so you can build the whole flow, including the payout leg, in one sitting. What sandbox cannot show you is the waiting: pending_review, changes_requested and processing do not occur there. Drive those paths from your own tests rather than expecting sandbox to produce them, and make sure your integration handles a name that is not usable yet.

Rules worth knowing before you build

Rule	Detail
One live copy of a name	You cannot have two payer names with the same `display_name` in review or approved at once — matched case-insensitively. Rejected and archived names do not block reuse
One default	Setting a new default moves the flag off the old one. Only a name that has cleared review can be the default
Editing resets review	Any update, including a metadata-only one, returns the name to `pending_review` and clears the reviewer’s note. Batch your corrections
Approved names are frozen	Once approved, a name cannot be edited. Archive it and submit a new one
Archiving is soft and final	The record and payout history stay; the name stops being usable and cannot be un-archived
Documents are attachable only during review	Once a decision is made, Attach Documents answers `409`
Document links expire	`downloadUrl` is valid for 1 hour. Get a fresh one from Get Document URL

Errors

Status	Code / message	Cause
`403`	`PAYER_NAMES_DISABLED`	Named Payouts are not enabled for your account
`400`	`Validation failed`	A field is missing or malformed; `errors` names each one
`400`	At least one supporting document is required	Your account has `documentsRequired: true` and you sent none
`400`	That payer name was rejected / has been archived	You attached an unusable name to a payout
`404`	Payer name not found	No such name on your account. On the payer-name endpoints only — a payout refuses an unknown name with a `400`
`409`	You already have a payer name ”…” in progress or approved	Duplicate `display_name`
`409`	This payer name can no longer be edited	It has been approved, rejected or archived

Next steps

Create Payer Name

Field reference, document rules, and the multipart form.

Withdraw Funds

Attach payerNameId to a payout.

Payer name events

Be told when a name becomes usable.

Send Payouts

The payout flow this plugs into.

Manage Your Own Money

Guides

Checking whether it is on

Register a payer name

The lifecycle

Status reference

Being told, rather than polling

Pay under a name

Where the name is applied

Testing in sandbox

Rules worth knowing before you build

Errors

Next steps

Create Payer Name

Withdraw Funds

Payer name events

Send Payouts

​Checking whether it is on

​Register a payer name

​The lifecycle

​Status reference

​Being told, rather than polling

​Pay under a name

​Where the name is applied

​Testing in sandbox

​Rules worth knowing before you build

​Errors

​Next steps

Create Payer Name

Withdraw Funds

Payer name events

Send Payouts

Checking whether it is on

Register a payer name

The lifecycle

Status reference

Being told, rather than polling

Pay under a name

Where the name is applied

Testing in sandbox

Rules worth knowing before you build

Errors

Next steps