Get beneficiary

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.lumepay.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "Lumepay API MCP server": {
    "url": "https://docs.lumepay.com/mcp"
  }
}

GET /api/v1/beneficiaries/{beneficiaryId}

Returns a confirmed beneficiary belonging to the authenticated API key owner.

Headers

X-API-KEY string Required

Public API key issued from the Lumepay API key management flow.
X-API-SECRET string Required

API secret paired with the public API key.

Path parameters

beneficiaryId string Required

Beneficiary id returned by the beneficiary list endpoint.

Responses

200 application/json

Beneficiary returned successfully
Hide response attributes Show response attributes object
- id string
  
  Beneficiary id used by external beneficiary endpoints.
- currency string
  
  Saved beneficiary currency.
- nickname string
  
  Beneficiary nickname.
- withdrawFormDetails object
  
  Saved withdrawal form details for the beneficiary.
  
  Additional properties are allowed.
  
  Hide withdrawFormDetails attributes Show withdrawFormDetails attributes object
  
  pojo boolean
  
  int boolean
  
  double boolean
  
  bigDecimal boolean
  
  bigInteger boolean
  
  nodeType string
  
  Values are ARRAY, BINARY, BOOLEAN, MISSING, NULL, NUMBER, OBJECT, POJO, or STRING.
  
  long boolean
  
  floatingPointNumber boolean
  
  integralNumber boolean
  
  valueNode boolean
  
  missingNode boolean
  
  string boolean
  
  boolean boolean
  
  textual boolean Deprecated
  
  short boolean
  
  container boolean
  
  object boolean
  
  binary boolean
  
  number boolean
  
  array boolean
  
  empty boolean
  
  null boolean
  
  float boolean
  
  embeddedValue boolean
- createdAt string(date-time)
  
  Beneficiary creation timestamp.
404 application/json

Resource was not found for the authenticated API key owner
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
403 application/json

Authenticated API key is not allowed to perform this action
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
500 application/json

Unexpected server error
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
401 application/json

API key authentication failed
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
400 application/json

Request validation failed
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string

GET /api/v1/beneficiaries/{beneficiaryId}

curl \
 --request GET 'http://api.example.com/api/v1/beneficiaries/ben_7K9Q2M' \
 --header "X-API-KEY: string" \
 --header "X-API-SECRET: string"

Response examples (200)

{
  "id": "ben_7K9Q2M",
  "currency": "ZAR",
  "nickname": "FNB Savings",
  "withdrawFormDetails": {
    "bankName": "FNB",
    "accountNumber": "1234567890",
    "accountHolderName": "Jane Example"
  },
  "createdAt": "2026-05-11T10:15:30Z"
}

Response examples (404)

{
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 404,
  "message": "Resource was not found for the authenticated API key owner",
  "requestId": "req_01HY0000000000000000000000",
  "httpStatus": 404
}

Response examples (403)

{
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 403,
  "message": "Authenticated API key is not allowed to perform this action",
  "requestId": "req_01HY0000000000000000000000",
  "httpStatus": 403
}

Response examples (500)

{
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 500,
  "message": "Unexpected server error",
  "requestId": "req_01HY0000000000000000000000",
  "httpStatus": 500
}

Response examples (401)

{
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 401,
  "message": "API key authentication failed",
  "requestId": "req_01HY0000000000000000000000",
  "httpStatus": 401
}

Response examples (400)

{
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 400,
  "message": "Request validation failed",
  "requestId": "req_01HY0000000000000000000000",
  "httpStatus": 400
}