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

# Initiate Session

> Initiate new session for a payment. This endpoint will help you get the `paymentURL` that you can use to redirect the customer to in order to complete the payment.

### Query Parameters

<ParamField body="apiKey" type="string" placeholder="API Key" required>
  The API Key of your account.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="CallBackUrl" type="string" required>
      The URL that will be used to redirect the customer after the payment process is done.
    </ResponseField>

    <ResponseField name="ErrorUrl" type="string" required>
      The URL that will be used to redirect the customer after the payment process is failed.
    </ResponseField>

    <ResponseField name="UserDefinedField" type="array" required>
      Any value you want to store with the invoice (you can get it later using the Payment Inquiry method). This can be a user identifier or a transaction Id in your system.
    </ResponseField>

    <ResponseField name="InvoiceValue" type="string" required>
      The total amount you want the customer to pay.
    </ResponseField>

    <ParamField body="Suppliers" type="array" required>
      <Expandable title="properties" defaultOpen={true}>
        <ResponseField name="SupplierCode" type="integer" required>
          Your Supplier Code (you'll get it after joining DashPay)

          Sample: `123`.
        </ResponseField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="test" type="boolean" initialValue={true}>
  Set this property to `true` to send the request to the development
  environment.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "test": false,
    "paymentURL": "https://dashu.sa/api/external/pay?hash=h3qds2paiy-fko9bgd0et-mj94pv32tn"
  }
  ```

  ```json Error theme={null}
  {
    "success": false,
    "code": 2,
    "message": "`CallBackUrl` is a required parameter."
  }
  ```
</ResponseExample>

### Response properties

{" "}

<ResponseField name="success" type="boolean" required>
  A boolean value indicates the response status.
</ResponseField>

<ResponseField name="test" type="boolean" required>
  A boolean value indicates the development environment status.
</ResponseField>

<ResponseField name="paymentURL" type="string" required>
  The payment URL that you'll use to redirect the cusotmer to complete the
  payment. It's a link for a hosted page that will provide multiple payment
  methods that can be choosed by the customer to pay the invoice.
</ResponseField>

## Error Codes

Here's a list of possible error codes of this endpoint.

| **Code** | **Description**                             |
| -------- | ------------------------------------------- |
| 1        | Missing or invalid api key                  |
| 2        | `CallBackUrl` is a required parameter.      |
| 3        | `UserDefinedField` is a required parameter. |
| 4        | `InvoiceValue` is a required parameter.     |
| 5        | `Suppliers` is a required parameter.        |
| 6        | `ErrorUrl` is a required parameter.         |
| 7        | `CallBackUrl` should be a valid URL.        |
| 8        | `UserDefinedField` should be an array.      |
| 9        | `InvoiceValue` should be greater than zero. |
| 10       | `Suppliers` should be an array.             |
| 11       | `ErrorUrl` should be a valid URL.           |