> ## 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.

# Get Payer Name

> Retrieves a single payer name, including its documents and the reviewer note if a decision has been made. An id that belongs to another account answers `404`, the same as one that does not exist.

Retrieves one payer name, including its documents and the reviewer's note if a decision has been made.

## Example Request

```bash theme={null}
curl "https://api.rolla.xyz/api/v1/external/payer-names/9f8e7d6c-5b4a-4938-8271-0a1b2c3d4e5f" \
  -H "X-API-Key: your_api_key_here"
```

## Example Response (changes requested)

```json theme={null}
{
  "status": 200,
  "message": "Payer name retrieved",
  "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": "changes_requested",
    "isDefault": false,
    "decisionNote": "The registration number does not match the certificate you attached. Correct it and resubmit.",
    "documents": [
      {
        "id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
        "fileName": "certificate-of-incorporation.pdf",
        "description": "Certificate of incorporation",
        "fileType": "application/pdf",
        "fileSize": 284122,
        "downloadUrl": "https://files.rolla.xyz/payer_name_docs/...",
        "createdAt": "2026-09-01T09:14:22.000Z"
      }
    ],
    "metadata": { "vendor_id": "V-4471" },
    "createdAt": "2026-09-01T09:14:22.000Z",
    "updatedAt": "2026-09-02T11:02:41.000Z"
  }
}
```

`decisionNote` is the reviewer's own words, and it is the whole point of a `changes_requested` or `rejected` outcome — show it to whoever has to act on it. It is cleared when you resubmit.

<Note>
  A payer name id that belongs to another account answers `404`, the same as one that does not exist.
</Note>


## OpenAPI

````yaml GET /payer-names/{payerNameId}
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/{payerNameId}:
    get:
      summary: Get Payer Name
      description: >-
        Retrieves a single payer name, including its documents and the reviewer
        note if a decision has been made. An id that belongs to another account
        answers `404`, the same as one that does not exist.
      operationId: getPayerName
      parameters:
        - name: payerNameId
          in: path
          required: true
          description: The payer name id.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Payer name retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code, repeated in the body
                    example: 200
                  message:
                    type: string
                    example: Payer name retrieved
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/PayerName'
              example:
                status: 200
                message: Payer name retrieved
                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: changes_requested
                  isDefault: false
                  decisionNote: >-
                    The registration number does not match the certificate you
                    attached. Correct it and resubmit.
                  documents:
                    - id: 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091
                      fileName: certificate-of-incorporation.pdf
                      description: Certificate of incorporation
                      fileType: application/pdf
                      fileSize: 284122
                      downloadUrl: https://files.rolla.xyz/payer_name_docs/...
                      createdAt: '2026-09-01T09:14:22.000Z'
                  metadata:
                    vendor_id: V-4471
                  createdAt: '2026-09-01T09:14:22.000Z'
                  updatedAt: '2026-09-02T11:02:41.000Z'
        '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
        '404':
          description: Not found — no such payer name on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                message: Payer name not found
components:
  schemas:
    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

````