Developers
Product docs
Back to reference
POST/payments/initiate
Payments

Initiate payment

Creates a payment through the payment orchestrator. business_id is derived from authentication context and must not be sent.

Access tierauthenticatedRate limitpay_apiIdempotencyheader:Idempotency-KeyAuthenticationBearerAuth
SourceLuxApi/Modules/PayAPI/Controllers/PaymentController.php::initiateLuxPayProjects @ 146e98baa44e

Parameters

X-Request-IDheader
stringOptional

Client correlation identifier. LuxPay may generate one when omitted.

Example: req_01J...
Idempotency-Keyheader
stringRequired

Unique key for safely retrying this mutation. Reuse only for the same logical request.

Example: pay_01JABC...

Request body

InitiatePaymentRequestRequired
amount
number
Example: 1250.5
currency
string
Example: YER
payment_method
string
Example: wallet
payment_channel
string
Example: pos
provider
string | null
metadata
object | null

JSON example

{
  "amount": 1250.5,
  "currency": "YER",
  "payment_method": "wallet",
  "payment_channel": "pos",
  "provider": "string",
  "metadata": {}
}

Code examples

The displayed sandbox host is a placeholder until an official host is provisioned. Never paste a production token into a public browser.
curl --request POST \
  --url 'https://sandbox-api.luxpay.example/v1/payments/initiate' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: pay_01JABC...' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1250.5,
  "currency": "YER",
  "payment_method": "wallet",
  "payment_channel": "pos",
  "provider": "string",
  "metadata": {}
}'

Responses

200Duplicate replay of a previously successful request.
success
boolean
Example: true
data
PaymentResult
{
  "success": true,
  "data": {
    "success": false,
    "transaction_id": "string",
    "status": "string",
    "provider": "string",
    "provider_ref": "string",
    "amount": 1,
    "currency": "string",
    "fee_amount": 1,
    "net_amount": 1,
    "message": "string",
    "error_code": "string",
    "is_duplicate": false,
    "metadata": {}
  }
}
201Successful response.
success
boolean
Example: true
data
PaymentResult
{
  "success": true,
  "data": {
    "success": false,
    "transaction_id": "string",
    "status": "string",
    "provider": "string",
    "provider_ref": "string",
    "amount": 1,
    "currency": "string",
    "fee_amount": 1,
    "net_amount": 1,
    "message": "string",
    "error_code": "string",
    "is_duplicate": false,
    "metadata": {}
  }
}
400
401
403
404
409
422
429
500
OpenAPI JSONOpenAPI YAMLPostman collection