API

Initiate payment

Start a payment on the Payment Engine.

Request

POST /merchant/initiate-payment

Header	Required	Description
`X-API-KEY`	Yes	Merchant API key
`Content-Type`	Yes	`application/json`

Body fields

Field	Type	Required	Notes
`amount`	number	Yes	Must be > 0
`currency`	string	No	Default `BHD`. Allowed `BHD` or `USD`. Benefit requires `BHD`
`payment_provider`	string	Yes	`benefit`, `benefit_web_checkout`, `mastercard`, `apple-pay`
`additional_data`	object	No	Opaque metadata
`integration_type`	string	No	Apple Pay: `web` or `native_ios`
`merchant_reference`	string	No	Especially useful for native Apple Pay
`payment_method`	string	No	If set, must be `apple_pay`
`success_url`	string	No	HTTPS override
`fail_url`	string	No	HTTPS override

Example

curl -X POST https://merchant.venpays.com/merchant/initiate-payment \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $VENPAYS_KEY" \
  -d '{
    "amount": 10.000,
    "currency": "BHD",
    "payment_provider": "mastercard",
    "success_url": "https://example.com/paid",
    "fail_url": "https://example.com/failed"
  }'

Responses

Hosted providers (`mastercard`, `benefit`, `benefit_web_checkout`, Apple Pay web)

Typical shape:

{
  "payment_url": "https://merchant.venpays.com/mastercard/payment?payment_id=...",
  "track_id": "11111111-2222-3333-4444-555555555555",
  "success": true
}

Exact field set follows PaymentInitiatorOutput in the engine.

Native Apple Pay (`integration_type: "native_ios"`)

{
  "track_id": "...",
  "native_session_token": "...",
  "expires_at": "2026-07-26T12:00:00.000Z",
  "amount": "10.000",
  "currency": "BHD",
  "merchant_reference": "optional-reference",
  "apple_pay": {
    "merchant_identifier": "merchant.com.example",
    "merchant_display_name": "Example Merchant",
    "country_code": "BH",
    "currency_code": "BHD",
    "supported_networks": ["visa", "masterCard"],
    "merchant_capabilities": ["threeDSecure"]
  },
  "success": true
}

Return this payload to your iOS app. Never initiate from the device with X-API-KEY.

Errors

Common: 400 validation / connector / key issues, 401 missing key, 500 server error.