> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Payment Session

> Resolve the active provider and generate a hosted payment session (Netopia adapter).

## Method

`POST` `/v1/payments/start`

## Body Parameters

<ParamField name="provider" type="string">Provider hint (defaults to workspace preferred provider, currently `netopia`).</ParamField>
<ParamField name="bookingId" type="uuid">Existing booking to charge (required if `wizardSessionId` omitted).</ParamField>
<ParamField name="wizardSessionId" type="uuid">Wizard session to charge (required if `bookingId` omitted).</ParamField>
<ParamField name="amount" type="number" required>Amount to authorize/capture.</ParamField>
<ParamField name="currency" type="string" required>ISO 4217 currency (e.g. `RON`).</ParamField>
<ParamField name="billing" type="object" required>Billing contact details forwarded to the provider.</ParamField>
<ParamField name="shipping" type="object">Shipping/contact info (optional).</ParamField>
<ParamField name="products" type="array">Line items used by the provider receipt.</ParamField>
<ParamField name="redirectUrl" type="string">Override redirect target (defaults to environment base URL).</ParamField>

## Headers

<ParamField header="Authorization" type="string">Bearer token (workspace API key).</ParamField>
<ParamField header="content-type" type="string">`application/json`</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voyantcloud.com/v1/payments/start \
    -H "Authorization: Bearer $VOYANT_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "bookingId": "4a9a807e-5c7c-4f57-8e6d-2c6f1b1c5d10",
      "amount": 8450,
      "currency": "RON",
      "billing": {
        "email": "ana@example.com",
        "firstName": "Ana",
        "lastName": "Ionescu"
      },
      "products": [
        { "name": "Summer Cruise", "price": 8450, "qty": 1 }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.voyantcloud.com/v1/payments/start", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      wizardSessionId: "b1f7f7a0-220c-4f89-9d6d-0c0ae943a99d",
      amount: 4200,
      currency: "EUR",
      billing: { email: "ana@example.com" },
      products: [{ name: "Deposit", price: 4200, qty: 1 }],
    }),
  })
  const session = await res.json()
  ```

  ```python Python theme={null}
  import os, requests

  payload = {
    "bookingId": "4a9a807e-5c7c-4f57-8e6d-2c6f1b1c5d10",
    "amount": 8450,
    "currency": "RON",
    "billing": {"email": "ana@example.com"},
    "products": [{"name": "Summer Cruise", "price": 8450, "qty": 1}]
  }

  resp = requests.post(
    "https://api.voyantcloud.com/v1/payments/start",
    headers={
      "Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}",
      "content-type": "application/json",
    },
    json=payload,
  )
  session = resp.json()
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "url": "https://secure.mobilpay.ro/pay?orderId=ORDER-20250301-0001",
    "orderId": "ORDER-20250301-0001",
    "provider": "netopia"
  }
  ```

  ```json 404 Not Found theme={null}
  { "error": "Payment account not found for provider netopia", "requestId": "req_789" }
  ```
</ResponseExample>

<Tip>The API uses the encrypted payment account matching the workspace + provider. For Netopia it also injects the notify URL (<code>/v1/integrations/netopia/notify</code>) and returns the hosted payment URL you must redirect the customer to.</Tip>