Create beneficiary withdrawal | Lumetrade Staging API documentation

Create beneficiary withdrawal Run in API Explorer

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

Standard setup for AI tools providing an mcp.json file

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

POST /api/v1/beneficiaries/withdrawals

Creates a withdrawal using the saved details from the beneficiary identified in the body. 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 Lumetrade API key management flow.
X-API-SECRET string Required

API secret paired with the public API key.

Body Required

request object Required

Request to create a withdrawal from a beneficiary.
Hide request attributes Show request attributes object
- beneficiaryId string
  
  Beneficiary id returned by the beneficiary endpoints.
- 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

beneficiaryId string

Beneficiary id returned by the beneficiary endpoints.
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
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
429 application/json

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

POST /api/v1/beneficiaries/withdrawals

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

curl \
 --request POST 'https://api.staging.lumetrade.com/api/v1/beneficiaries/withdrawals' \
 --header "Content-Type: application/json" \
 --header "X-API-KEY: string" \
 --header "X-API-SECRET: string" \
 --data '{"beneficiaryId":"ben_7K9Q2M","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
{
  "beneficiaryId": "ben_7K9Q2M",
  "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,
  "errors": [],
  "timestamp": "2026-01-01T00:00:00Z",
  "code": 400,
  "message": "Request validation failed",
  "requestId": "req_01HY0000000000000000000000"
}

Response examples (404)

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

Response examples (403)

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

Response examples (429)

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

Response examples (401)

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

Response examples (500)

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