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

# Direct Integration

> Initiate a checkout transaction and obtain the payment provider redirection URL.

An API endpoint used to initiate a checkout transaction and obtain the secure payment provider redirection URL.

## Request

### Headers

<ParamField header="Abp-TenantId" type="string" required>
  Your unique Merchant ID assigned by CommercePay.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your API credentials used for authentication (typically a Bearer token).
</ParamField>

<ParamField header="cap-signature" type="string" required>
  A unique security hash used to verify the integrity of the request body. See [Generate Signature](/docs/generate-signature) for how to generate this.
</ParamField>

### Body

<Note>
  Omitting `channelId` routes the customer to CommercePay's hosted payment page instead, where they pick their own payment method. If you'd rather let CommercePay handle channel selection this way, see [Hosted Session Checkout](/api-reference/initial-session).
</Note>

<ParamField body="channelId" type="integer">
  An identifier that represents the CommercePay payment channel. Refer to the `id` from the response of the [Get Channel List](/api-reference/get-tenant-channels-by-country) endpoint. This parameter can be omitted if you choose to utilize the CommercePay Hosted Payment Web interface.
</ParamField>

<ParamField body="providerChannelId" type="string">
  An identifier that represents the specific upstream payment provider sub-channel (e.g., a bank code for online banking). This becomes **mandatory** if the chosen channel configuration has `isProviderHostChannel: true`. Obtain valid values from the [Get Provider Channels](/api-reference/get-provider-channels) endpoint.
</ParamField>

<ParamField body="currencyCode" type="string" required>
  Currency code formatted to standard 3-letter ISO 4217 specifications (e.g., `MYR`).
</ParamField>

<ParamField body="amount" type="int64" required>
  The transaction payment value. This field exclusively accepts integer units where the final decimals are represented as whole values (e.g., an amount value of `1000` translates to `10.00` in the system backend).
</ParamField>

<ParamField body="referenceCode" type="string" required>
  The merchant-side unique order reference or invoice tracking sequence code. Maximum length: 50.
</ParamField>

<ParamField body="ipAddress" type="string" required>
  The customer's valid IP address captured directly by the merchant server. Maximum length: 50.
</ParamField>

<ParamField body="returnUrl" type="string" required>
  The synchronous return URL where the customer's browser is forwarded automatically after completing payment checkout steps. Maximum length: 500.
</ParamField>

<ParamField body="timestamp" type="int64" required>
  Numeric timestamp in milliseconds representing request validation freshness (e.g., generated via `new Date().getTime()`).
</ParamField>

<ParamField body="description" type="string">
  Text description summarized for transaction tracing logs. Maximum length: 100.
</ParamField>

<ParamField body="callbackUrl" type="string">
  Target address utilized for asynchronous host-to-host webhook payment status change push actions. Maximum length: 500.
</ParamField>

### Request Payload Sample

```json Payload theme={null}
{
  "channelId": 2,
  "providerChannelId": "TEST0021",
  "currencyCode": "MYR",
  "amount": 1000,
  "referenceCode": "INV-2026-00941",
  "ipAddress": "172.56.21.89",
  "returnUrl": "https://yourmerchantstore.com/checkout/result",
  "callbackUrl": "https://yourmerchantstore.com/api/webhook",
  "description": "Order checkout payment item description",
  "timestamp": 1774845600000
}
```

## Response

### Body

<ResponseField name="currencyCode" type="string">
  Currency code with a 3-letter ISO 4217 standard code (e.g., `MYR`). Maximum length: 3.
</ResponseField>

<ResponseField name="amount" type="int64">
  The transaction payment value returned in pure integer units (e.g., `1000` is equivalent to `10.00` for the backend processing rules).
</ResponseField>

<ResponseField name="transactionNumber" type="string">
  Unique CAP Transaction Number mapped internally for auditing. Maximum length: 24.
</ResponseField>

<ResponseField name="channelId" type="integer">
  The primary identity mapping identifier. Corresponds to the entry endpoints defined in [Get Channel List](/api-reference/get-tenant-channels-by-country).
</ResponseField>

<ResponseField name="redirectionType" type="integer">
  Defines the browser execution pathway. `1` = UrlRedirection, `2` = Script execution redirection.
</ResponseField>

<ResponseField name="redirectUrl" type="string">
  The secure target destination link utilized to send the consumer browser to the payment selection page.
</ResponseField>

<ResponseField name="clientScript" type="string">
  Customized script sequence injected onto client browsers to force payment redirection behaviors.
</ResponseField>

<ResponseField name="transactionExpired" type="string">
  Expiration threshold deadline represented as an ISO 8601 date-time timestamp block.
</ResponseField>

### Response Payload Sample

```json Response_2XX theme={null}
{
  "result": {
    "currencyCode": "MYR",
    "amount": 1000,
    "transactionNumber": "200F75CD1F0053299EB260528",
    "channelId": 2,
    "redirectionType": 1,
    "redirectUrl": "{URL}",
    "clientScript": null,
    "transactionExpired": "2026-05-28T16:39:00.000Z"
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}
```

## Error Responses

| Code | Message              |
| ---- | -------------------- |
| 1    | `Invalid Signature.` |

```json Response_400 theme={null}
{
  "result": null,
  "targetUrl": null,
  "success": false,
  "error": {
    "code": 1,
    "message": "Invalid Signature."
  },
  "unAuthorizedRequest": true,
  "__abp": true
}
```