Create beneficiary withdrawal

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.staging.lumepay.com/mcp

Standard setup for AI tools providing an mcp.json file

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

POST /api/v1/withdrawals/beneficiaries/{beneficiaryId}

Creates a withdrawal using only the saved details from an existing confirmed beneficiary. Call GET /api/v1/payment-reasons, then submit its id and required text fields together in the flat paymentReasons object.

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

Body Required

request object Required

Request to create a withdrawal from the beneficiary identified in the request path.
Hide request attributes Show request attributes object
- amount number Required
  
  Withdrawal amount in the beneficiary currency.
- paymentReasons object
  
  Flat payment reason object. Include paymentReasonId and values keyed by requiredTextFields from GET /api/v1/payment-reasons.
  Hide paymentReasons attribute Show paymentReasons attribute object
  
  * object Additional properties

Body Required

amount number Required

Withdrawal amount in the beneficiary currency.
paymentReasons object

Flat payment reason object. Include paymentReasonId and values keyed by requiredTextFields from GET /api/v1/payment-reasons.
Hide paymentReasons attribute Show paymentReasons attribute object
- * object Additional properties

Responses

201 application/json

Withdrawal created successfully
Hide response attributes Show response attributes object
- transactionId string
  
  Created withdrawal transaction id.
- status string
  
  Created withdrawal status.
  
  Values are PENDING, ACCEPTED, AWAITING_CONFIRMATION, PROCESSING, COMPLIANCE_PENDING, COMPLETED, FAILED, CANCELLED, or REVERSED.
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
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
429 application/json

Cloudflare API rate limit exceeded
Hide response attributes Show response attributes object
- error 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

POST /api/v1/withdrawals/beneficiaries/{beneficiaryId}

curl \
 --request POST 'https://api.staging.lumepay.com/api/v1/withdrawals/beneficiaries/ben_7K9Q2M' \
 --header "Content-Type: multipart/form-data" \
 --header "X-API-KEY: string" \
 --header "X-API-SECRET: string" \
 --form 'request={"amount":101,"paymentReasons":{"paymentReasonId":18,"regulatoryBodyName":"Financial Sector Conduct Authority","licenceRegistrationReference":"FSP-123456"}}'

curl \
 --request POST 'https://api.staging.lumepay.com/api/v1/withdrawals/beneficiaries/ben_7K9Q2M' \
 --header "Content-Type: application/json" \
 --header "X-API-KEY: string" \
 --header "X-API-SECRET: string" \
 --data '{"amount":101,"paymentReasons":{"paymentReasonId":18,"regulatoryBodyName":"Financial Sector Conduct Authority","licenceRegistrationReference":"FSP-123456"}}'

Request examples

# Headers
X-API-KEY: string
X-API-SECRET: string

# Payload
{
  "amount": 101,
  "paymentReasons": {
    "paymentReasonId": 18,
    "regulatoryBodyName": "Financial Sector Conduct Authority",
    "licenceRegistrationReference": "FSP-123456"
  }
}

Response examples (201)

{
  "transactionId": "WD5M8Q1P",
  "status": "PENDING"
}

Response examples (400)

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

Response examples (404)

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

Response examples (429)

{
  "error": "rate_limit_exceeded",
  "message": "API rate limit exceeded"
}

Response examples (403)

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

Response examples (500)

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

Response examples (401)

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