### Create Session API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Creates a session to hold transaction card information. This is the first step in the Direct Integration process.

```APIDOC
## POST /merchant/{MerchantId}/session/

### Description
Creates a session to hold transaction card information. This is the first step in the Direct Integration process.

### Method
POST

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/session/`

### Parameters
#### Path Parameters
- **MerchantId** (string) - Required - The ID of the merchant.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **session.id** (string) - The unique identifier for the created session.

#### Response Example
```json
{
  "session": {
    "id": "SESSION0002695081404E6099215K60"
  }
}
```
```

--------------------------------

### POST /token - Generate Token

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

Generates a token for a previously collected card information within a payment session.

```APIDOC
## POST /token

### Description
Generates a token for a previously collected card information within a payment session.

### Method
POST

### Endpoint
https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/token

### Parameters
#### Request Body
- **session** (object) - Required - Contains the session ID.
  - **id** (string) - Required - The session.id value generated in the first step.
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **type** (string) - Required - The type of source of funds, e.g., "CARD".

### Request Example
```json
{
	"session": {
		"id": "{{SessionId}}"
	},
	"sourceOfFunds": {
		"type": "CARD"
	}
}
```

### Response
#### Success Response (200)
- **token** (string) - The token number referencing the saved card. This value should be stored for future payments.

#### Response Example
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/tokenize-api.json).
```

--------------------------------

### PUT /order/{orderId}/transaction/{transactionId} - Authenticate Payer with 3DS

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

Authenticates the payer using 3D Secure after the initiation step.

```APIDOC
## PUT /order/{orderId}/transaction/{transactionId} - Authenticate Payer with 3DS

### Description
Authenticates the payer using 3D Secure. This step follows the initiation of authentication and returns an HTML content to be displayed to the user for the 3DS interaction.

### Method
PUT

### Endpoint
https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/TxnID_{{AttemptNum}}

### Parameters
#### Request Body
- **apiOperation** (string) - Required - The operation to perform, set to "AUTHENTICATE_PAYER".
- **authentication** (object) - Required - Authentication details.
  - **redirectResponseUrl** (string) - Required - The URL to redirect the user to after authentication.
- **correlationId** (string) - Required - A unique identifier for the request.
- **device** (object) - Required - Device information.
  - **browser** (string) - Required - The user's browser, e.g., "MOZILLA".
  - **browserDetails** (object) - Required - Detailed browser information.
    - **3DSecureChallengeWindowSize** (string) - Required - The size of the 3DS challenge window, e.g., "FULL_SCREEN".
    - **acceptHeaders** (string) - Required - Accepted headers, e.g., "application/json".
    - **colorDepth** (integer) - Required - Color depth of the screen.
    - **javaEnabled** (boolean) - Required - Indicates if Java is enabled.
    - **language** (string) - Required - The language of the browser, e.g., "en-US".
    - **screenHeight** (integer) - Required - Screen height.
    - **screenWidth** (integer) - Required - Screen width.
    - **timeZone** (integer) - Required - Time zone offset.
  - **ipAddress** (string) - Required - The IP address of the device.
- **order** (object) - Required - Order details.
  - **amount** (string) - Required - The transaction amount.
  - **currency** (string) - Required - The transaction currency, e.g., "SAR".
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **token** (string) - Required - The previously generated token.

### Request Example
```json
{
	"apiOperation": "AUTHENTICATE_PAYER",
	"authentication":{
		"redirectResponseUrl":	"https://localhost:8000/"
	},
	"correlationId":"test",
	"device": {
		    "browser": "MOZILLA",
		    "browserDetails": {
				"3DSecureChallengeWindowSize": "FULL_SCREEN",
			    "acceptHeaders": "application/json",
			    "colorDepth": 24,
			    "javaEnabled": true,
			    "language": "en-US",
			    "screenHeight": 640,
			    "screenWidth": 480,
			    "timeZone": 273
		    },
	   "ipAddress": "127.0.0.1"
	},
	"order":{
		"amount":"1.00",
	    	"currency":"SAR"
	},
	"sourceOfFunds": {
		"token":"{{Token}}"
	}
}
```

### Response
#### Success Response (200)
- **authentication.redirectHtml** (string) - HTML content containing the 3DS interaction page. This HTML needs to be displayed to the user.

#### Response Example
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/authenticate-payer-api.json).
```

--------------------------------

### PUT /order/{orderId}/transaction/{transactionId} - Initiate 3DS Authentication

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

Initiates the 3D Secure (3DS) authentication process for a transaction.

```APIDOC
## PUT /order/{orderId}/transaction/{transactionId} - Initiate 3DS Authentication

### Description
Initiates the 3D Secure (3DS) authentication process for a transaction. This step can be skipped if 3DS authentication is not required.

### Method
PUT

### Endpoint
https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/TxnID_{{AttemptNum}}

### Parameters
#### Request Body
- **apiOperation** (string) - Required - The operation to perform, set to "INITIATE_AUTHENTICATION".
- **authentication** (object) - Required - Details for authentication.
  - **acceptVersions** (string) - Required - Accepted 3DS versions, e.g., "3DS1,3DS2".
  - **channel** (string) - Required - The authentication channel, e.g., "PAYER_BROWSER".
  - **purpose** (string) - Required - The purpose of the authentication, e.g., "PAYMENT_TRANSACTION".
- **correlationId** (string) - Required - A unique identifier for the request.
- **order** (object) - Required - Order details.
  - **reference** (string) - Required - The order reference.
  - **currency** (string) - Required - The transaction currency, e.g., "SAR".
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **token** (string) - Required - The previously generated token.
- **transaction** (object) - Required - Transaction details.
  - **reference** (string) - Required - The transaction reference.

### Request Example
```json
{
	"apiOperation":"INITIATE_AUTHENTICATION",
	"authentication":{
	    "acceptVersions":"3DS1,3DS2",
	    "channel":"PAYER_BROWSER",
	    "purpose":"PAYMENT_TRANSACTION"
	},
	"correlationId":"test",
	"order":{
		"reference": "OrdRef_{{AttemptNum}}",
    	"currency":"SAR"
	},
	"sourceOfFunds": {
		"token":"{{Token}}"
	},
	"transaction": {
		"reference": "TrxRef_{{AttemptNum}}"
	}
}
```

### Response
#### Success Response (200)
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/initiate-authentication-api.json).
```

--------------------------------

### Initiate 3DS Authentication Request (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

This snippet demonstrates initiating 3DS authentication for a transaction using a previously generated token. It includes API operation details, authentication parameters, order information, and the source of funds token.

```javascript
{
	"apiOperation":"INITIATE_AUTHENTICATION",
	"authentication":{
	    "acceptVersions":"3DS1,3DS2",
	    "channel":"PAYER_BROWSER",
	    "purpose":"PAYMENT_TRANSACTION"
	},
	"correlationId":"test",
	"order":{
	    "reference": "OrdRef_{{AttemptNum}}",
    	    "currency":"SAR"
	},
	"sourceOfFunds": {
	    "token":"{{Token}}"
	},
	"transaction": {
	    "reference": "TrxRef_{{AttemptNum}}"
	}
}
```

--------------------------------

### Token Generation Request (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

This snippet shows how to generate a payment token by sending a POST request with session and source of funds information. It requires a valid SessionId and specifies the source of funds as CARD.

```javascript
{
	"session": {
		"id": "{{SessionId}}" // This is the session.id value that was generated in the first step 
	},
	"sourceOfFunds": {
		"type": "CARD"
	}
}
```

--------------------------------

### Import Checkout.js Library

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

Include the Checkout.js library in your HTML to enable payment page functionality. This script is loaded from the provided bank URL and requires specifying the API version.

```html
<script src="https://<Bank URL>/checkout/version/<API Version>/checkout.js">
</script>
```

--------------------------------

### PAY API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Makes a payment transaction after the payer authentication is complete.

```APIDOC
## PUT /api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/1

### Description
Initiates a payment transaction after the payer has been successfully authenticated.

### Method
PUT

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/1`

### Parameters

#### Request Body
- **apiOperation** (string) - Required - The operation to perform, value must be 'PAY'.
- **authentication** (object) - Required - Authentication details.
  - **transactionId** (string) - Required - The transaction ID obtained from the authentication step.
- **order** (object) - Required - Order details.
  - **amount** (number) - Required - The order amount.
  - **currency** (string) - Required - The currency of the order (e.g., 'SAR').
  - **reference** (string) - Required - The order reference.
- **transaction** (object) - Required - Transaction details.
  - **reference** (string) - Required - The transaction reference.
- **session** (object) - Required - Session information.
  - **id** (string) - Required - The session ID.
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **type** (string) - Required - The type of source of funds (e.g., 'CARD').

### Request Example
```json
{
	"apiOperation": "PAY",
	"authentication":{
		"transactionId": "TxnID_{{AttemptNum}}"
	},
	"order": {
		"amount": 1.00,
		"currency": "SAR",
		"reference": "OrdRef_{{AttemptNum}}"
	},
	"transaction": {
		"reference": "TrxRef_{{AttemptNum}}"
    	},
	"session": {
		"id": "{{SessionId}}"
	},
	"sourceOfFunds": {
		"type": "CARD"
	}
}
```

### Response
#### Success Response (200)
- **acquirerCode** (string) - The acquirer code for the transaction, indicating a successful payment.

#### Response Example
A sample of a successful payment response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/pay-api.json).
```

--------------------------------

### Configure Payment Page

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

This section details how to configure the client-side payment page using Checkout.js. It includes importing the library, configuring session details, merchant information, display controls, and options for displaying the payment page.

```APIDOC
## Configure Payment Page

### Description
Configure the client-side payment page by importing the Checkout.js library and calling `Checkout.configure()`. This allows you to set the appearance, logo, and page elements.

### Method
JavaScript

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Configuration Object
- **merchant** (string) - Required - Your merchant ID.
- **session** (object) - Required - Session details.
  - **id** (string) - Required - The session ID generated in the previous step.
- **interaction** (object) - Required - Controls how the payment page appears.
  - **merchant** (object) - Required - Merchant details displayed to the customer.
    - **name** (string) - Required - Your merchant name.
    - **email** (string) - Required - Merchant email address.
    - **phone** (string) - Required - Merchant phone number.
    - **logo** (string) - Required - URL of the merchant logo.
    - **url** (string) - Required - Merchant website URL.
    - **address** (object) - Required - Merchant address details.
      - **line1** (string) - Required - First line of the merchant address.
      - **line2** (string) - Optional - Second line of the merchant address.
  - **displayControl** (object) - Optional - Controls the visibility of various elements on the checkout page.
    - **billingAddress** (string) - Optional - Controls billing address display ('HIDE', 'MANDATORY', 'OPTIONAL', 'READ_ONLY').
    - **customerEmail** (string) - Optional - Controls customer email display ('HIDE', 'MANDATORY', 'OPTIONAL', 'READ_ONLY').
    - **orderSummary** (string) - Optional - Controls order summary display ('HIDE', 'SHOW', 'SHOW_PARTIAL').
    - **paymentConfirmation** (string) - Optional - Controls payment confirmation display ('HIDE', 'SHOW').
    - **shipping** (string) - Optional - Controls shipping address display ('HIDE', 'READ_ONLY').

### Request Example
```javascript
Checkout.configure({
    merchant: '<Merchant ID>',
    session: {
        id: "SESSION0002561575526H6901242G59"
    },
    interaction: {
        merchant: {
            name: 'Merchant Name',
            email: "info@merchant.com",
            phone: "+9661234567890",
            logo: "https://ap-gateway.mastercard.com/api/documentation/resource/footer.png",
            url: "https://www.mastercard.com",
            address: {
                line1: 'Jeddah',
                line2: 'Saudi Arabia'
            }
        },
        displayControl: {
            billingAddress: "HIDE",
            customerEmail: "HIDE",
            orderSummary: "SHOW",
            paymentConfirmation: "HIDE",
            shipping: "HIDE"
        }
    }
});
```

### Displaying the Payment Page
- `Checkout.showLightbox()`: Displays the payment page in a modal.
- `Checkout.showPaymentPage()`: Redirects to the payment page.
```

--------------------------------

### Retrieve Order Result using API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

Fetch the status of an order by making a GET request to the specified API endpoint. This requires Basic HTTP authentication and returns order details including the transaction status.

```http
GET  https://<Bank URL>/api/rest/version/<API Version>/merchant/<Merchant ID>/order/<Order Id>

```

--------------------------------

### Initiate 3DS Authentication API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Initiates the 3D Secure (3DS) authentication process for a transaction. This step is optional if 3DS is not required.

```APIDOC
## PUT /order/{OrderId}/transaction/{TransactionId}

### Description
Initiates the 3D Secure (3DS) authentication process for a transaction. This step is optional if 3DS is not required.

### Method
PUT

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/TxnID_{{AttemptNum}}`

### Parameters
#### Path Parameters
- **MerchantId** (string) - Required - The ID of the merchant.
- **AttemptNum** (string) - Required - A number representing the transaction attempt.

#### Query Parameters
None

#### Request Body
- **apiOperation** (string) - Required - Must be set to `INITIATE_AUTHENTICATION`.
- **authentication.acceptVersions** (string) - Required - Specifies the accepted 3DS versions (e.g., `3DS1,3DS2`).
- **authentication.channel** (string) - Required - The channel for authentication (e.g., `PAYER_BROWSER`).
- **authentication.purpose** (string) - Required - The purpose of the authentication (e.g., `PAYMENT_TRANSACTION`).
- **correlationId** (string) - Required - A unique identifier for the request.
- **order.reference** (string) - Required - The merchant's order reference.
- **order.currency** (string) - Required - The transaction currency (e.g., `SAR`).
- **session.id** (string) - Required - The ID of the session containing card information.
- **transaction.reference** (string) - Required - The merchant's transaction reference.

### Request Example
```json
{
  "apiOperation": "INITIATE_AUTHENTICATION",
  "authentication": {
    "acceptVersions": "3DS1,3DS2",
    "channel": "PAYER_BROWSER",
    "purpose": "PAYMENT_TRANSACTION"
  },
  "correlationId": "test",
  "order": {
    "reference": "OrdRef_{{AttemptNum}}",
    "currency": "SAR"
  },
  "session": {
    "id": "{{SessionId}}"
  },
  "transaction": {
    "reference": "TrxRef_{{AttemptNum}}"
  }
}
```

### Response
#### Success Response (200)
- **authentication.redirect.url** (string) - The URL to redirect the user for 3DS authentication.
- **authentication.transactionId** (string) - The 3DS transaction ID.

#### Response Example
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/initiate-authentication-api.json).
```

--------------------------------

### PUT /order/{orderId}/transaction/{transactionId} - Make Payment Transaction

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

Processes the final payment transaction after successful authentication.

```APIDOC
## PUT /order/{orderId}/transaction/{transactionId} - Make Payment Transaction

### Description
Processes the final payment transaction after the payer has been successfully authenticated via 3DS.

### Method
PUT

### Endpoint
https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/1

### Parameters
#### Request Body
- **apiOperation** (string) - Required - The operation to perform, set to "PAY".
- **authentication** (object) - Required - Authentication details.
  - **transactionId** (string) - Required - The ID of the completed authentication transaction.
- **order** (object) - Required - Order details.
  - **amount** (number) - Required - The transaction amount.
  - **currency** (string) - Required - The transaction currency, e.g., "SAR".
  - **reference** (string) - Required - The order reference.
- **transaction** (object) - Required - Transaction details.
  - **reference** (string) - Required - The transaction reference.
  - **source** (string) - Required - The transaction source, e.g., "INTERNET".
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **token** (string) - Required - The previously generated token.
  - **provided** (object) - Required - Provided details for the source of funds.
    - **card** (object) - Required - Card specific details.
      - **securityCode** (string) - Required - The security code (CVV) of the card.

### Request Example
```json
{
	"apiOperation": "PAY",
	"authentication":{
		"transactionId": "TxnID_{{AttemptNum}}"
	},
	"order": {
		"amount": 1.00,
		"currency": "SAR",
		"reference": "OrdRef_{{AttemptNum}}"
	},
	"transaction": {
		"reference": "TrxRef_{{AttemptNum}}",
		"source": "INTERNET"
    	},
	"sourceOfFunds": {
		"token":"{{Token}}",
		"provided": {
			"card": {
				"securityCode": "100"
			}
		}
	}
}
```

### Response
#### Success Response (200)
A successful payment is indicated by the presence of the `acquirerCode` for your transaction.

#### Response Example
A sample of a successful payment with token response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/pay-with-token-api.json).
```

--------------------------------

### Update Session API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Updates an existing session with the provided card details for the transaction.

```APIDOC
## PUT /session/{SessionId}

### Description
Updates an existing session with the provided card details for the transaction.

### Method
PUT

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/session/{{SessionId}}`

### Parameters
#### Path Parameters
- **MerchantId** (string) - Required - The ID of the merchant.
- **SessionId** (string) - Required - The ID of the session to update.

#### Query Parameters
None

#### Request Body
- **sourceOfFunds.provided.card.nameOnCard** (string) - Required - The name of the cardholder.
- **sourceOfFunds.provided.card.number** (string) - Required - The primary account number (PAN) of the card.
- **sourceOfFunds.provided.card.expiry.month** (string) - Required - The expiry month of the card (MM).
- **sourceOfFunds.provided.card.expiry.year** (string) - Required - The expiry year of the card (YY).
- **sourceOfFunds.provided.card.securityCode** (string) - Required - The security code (CVV) of the card.

### Request Example
```json
{
  "sourceOfFunds": {
    "provided": {
      "card": {
        "nameOnCard": "Nawaf",
        "number": "5123450000000008",
        "expiry": {
          "month": "05",
          "year": "21"
        },
        "securityCode": "100"
      }
    }
  }
}
```

### Response
#### Success Response (200)
This endpoint typically returns an empty body on success, or a minimal confirmation.

#### Response Example
(Empty or minimal confirmation)
```

--------------------------------

### AUTHENTICATE_PAYER API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Authenticates the payer using 3D Secure. This step is performed after the initial API request for the second step of the integration flow.

```APIDOC
## PUT /api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/TxnID_{{AttemptNum}}

### Description
Authenticates the payer with 3D Secure. This is typically done after an initial API request in a multi-step integration process.

### Method
PUT

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/order/OrdID_{{AttemptNum}}/transaction/TxnID_{{AttemptNum}}`

### Parameters

#### Request Body
- **apiOperation** (string) - Required - The operation to perform, value must be 'AUTHENTICATE_PAYER'.
- **authentication** (object) - Required - Contains details for authentication.
  - **redirectResponseUrl** (string) - Required - The URL where the merchant will be redirected after authentication.
- **correlationId** (string) - Required - A unique identifier for the transaction.
- **device** (object) - Required - Information about the device used for the transaction.
  - **browser** (string) - Required - The browser name (e.g., 'MOZILLA').
  - **browserDetails** (object) - Optional - Detailed browser information.
    - **3DSecureChallengeWindowSize** (string) - Optional - The size of the 3DSecure challenge window.
    - **acceptHeaders** (string) - Optional - The Accept headers for the request.
    - **colorDepth** (integer) - Optional - The color depth of the screen.
    - **javaEnabled** (boolean) - Optional - Indicates if Java is enabled.
    - **language** (string) - Optional - The language of the browser.
    - **screenHeight** (integer) - Optional - The screen height.
    - **screenWidth** (integer) - Optional - The screen width.
    - **timeZone** (integer) - Optional - The time zone offset.
  - **ipAddress** (string) - Required - The IP address of the device.
- **order** (object) - Required - Order details.
  - **amount** (string) - Required - The order amount.
  - **currency** (string) - Required - The currency of the order (e.g., 'SAR').
- **session** (object) - Required - Session information.
  - **id** (string) - Required - The session ID.

### Request Example
```json
{
	"apiOperation": "AUTHENTICATE_PAYER",
	"authentication":{
		"redirectResponseUrl":	"https://merchant.com/your-redirection-page"
	},
	"correlationId":"test",
	"device": {
		"browser": "MOZILLA",
	    "browserDetails": {
		    "3DSecureChallengeWindowSize": "FULL_SCREEN",
		    "acceptHeaders": "application/json",
		    "colorDepth": 24,
		    "javaEnabled": true,
		    "language": "en-US",
		    "screenHeight": 640,
		    "screenWidth": 480,
		    "timeZone": 273
	    },
		"ipAddress": "127.0.0.1"
	},
	"order":{
		"amount":"1.00",
	    "currency":"SAR"
	},
	"session": {
		"id": "{{SessionId}}"
	}
}
```

### Response
#### Success Response (200)
- **authentication.redirectHtml** (string) - HTML content for the 3DS interaction page. This HTML needs to be displayed to the user to complete the authentication.

#### Response Example
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/authenticate-payer-api.json).
```

--------------------------------

### Tokenizing Card Information

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

Tokenizes card information for future use, allowing customers to pay with saved cards without storing sensitive data directly.

```APIDOC
## POST /api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/token

### Description
Tokenizes the card information associated with a session or a completed payment. This allows for future payments using a saved card token, reducing PCI-compliance overhead.

### Method
POST

### Endpoint
`https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/token`

### Parameters

#### Request Body
- **session** (object) - Required - Session information.
  - **id** (string) - Required - The session ID generated in the first step of the integration.
- **sourceOfFunds** (object) - Required - Details about the source of funds.
  - **type** (string) - Required - The type of source of funds (e.g., 'CARD').

### Request Example
```json
{
	"session": {
		"id": "{{SessionId}}"
	},
	"sourceOfFunds": {
		"type": "CARD"
	}
}
```

### Response
#### Success Response (200)
- **token** (string) - A token representing the saved card information. This token should be stored for future use.

#### Response Example
A sample response can be found [here](https://github.com/Mastercard-MEA/MPGS-Integration-Guides-and-Samples/blob/main/docs/response-sample/tokenize-api.json).
```

--------------------------------

### Create Checkout Session API

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

Performs a POST API call to create a checkout session for processing payments using the Hosted Checkout method.

```APIDOC
## POST /api/rest/version/<API Version>/merchant/<Merchant ID>/session/

### Description
Initiates a checkout session for processing payments. This is the first step in the Hosted Checkout integration.

### Method
POST

### Endpoint
`https://<Bank URL>/api/rest/version/<API Version>/merchant/<Merchant ID>/session/`

### Parameters
#### Path Parameters
- **API Version** (string) - The API version to use.
- **Merchant ID** (string) - Your unique Mastercard Gateway merchant ID.

#### Query Parameters
None

#### Request Body
- **apiOperation** (string) - Must be "CREATE_CHECKOUT_SESSION".
- **interaction** (object) - Contains details about the interaction.
  - **operation** (string) - The operation type. Accepted values: "PURCHASE", "AUTHORIZE", "VERIFY", "NONE".
  - **returnUrl** (string) - The URL where the customer will be redirected after payment.
- **order** (object) - Contains details about the order.
  - **amount** (number) - The total amount for the order.
  - **currency** (string) - The currency of the order in ISO 4217 alpha code (e.g., USD, SGD).
  - **id** (string) - A unique identifier for the order.
  - **reference** (string) - A reference identifier for the order.
  - **description** (string) - A brief description of the order.
- **transaction** (object) - Contains details about the transaction.
  - **reference** (string) - A unique reference identifier for the transaction attempt.

### Request Example
```json
{
	"apiOperation": "CREATE_CHECKOUT_SESSION",
	"interaction": {
		"operation": "PURCHASE",
		"returnUrl": "https://www.yourwebsite.com/someResultPage"
	},
	"order": {
		"amount": 1.00,
		"currency": "<Currency>",
		"id": "<Order Id>",
		"reference": "<Order Reference>",
		"description": "Shoes and flipflops"
	},
	"transaction": {
		"reference": "<Transaction Reference>"
	}
}
```

### Authorization
Basic HTTP authentication. Username: `merchant.<your gateway merchant ID>`. Password: Your API password obtained from the Merchant Administration portal.

### Response
#### Success Response (200)
- **merchant** (string) - The merchant ID.
- **result** (string) - Indicates the result of the operation, e.g., "SUCCESS".
- **session** (object) - Contains session details.
  - **id** (string) - The unique ID of the created session.
  - **updateStatus** (string) - The status of the session update.
  - **version** (string) - The session version.
- **successIndicator** (string) - An indicator for a successful operation.

#### Response Example
```json
{
    "merchant": "<Merchant ID>",
    "result": "SUCCESS",
    "session": {
        "id": "SESSION0002561575526H6901242G59",
        "updateStatus": "SUCCESS",
        "version": "0bd6923c01"
    },
    "successIndicator": "2a149e4aed1d4818"
}
```
```

--------------------------------

### Authenticate Payer with 3DS Request (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

This snippet shows the request to authenticate the payer using 3DS. It includes redirection URL, device browser details, order information, and the source of funds token. The response contains HTML to be displayed to the user for interaction with their bank.

```javascript
{
	"apiOperation": "AUTHENTICATE_PAYER",
	"authentication":{
		"redirectResponseUrl":	"https://localhost:8000/"
	},
	"correlationId":"test",
	"device": {
	    "browser": "MOZILLA",
	    "browserDetails": {
			"3DSecureChallengeWindowSize": "FULL_SCREEN",
		    "acceptHeaders": "application/json",
		    "colorDepth": 24,
		    "javaEnabled": true,
		    "language": "en-US",
		    "screenHeight": 640,
		    "screenWidth": 480,
		    "timeZone": 273
	    },
	   "ipAddress": "127.0.0.1"
	},
	"order":{
		"amount":"1.00",
	    	"currency":"SAR"
	},
	"sourceOfFunds": {
		"token":"{{Token}}"
	}
}
```

--------------------------------

### Configure Payment Page with Checkout.js

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

Configure the appearance and behavior of the payment page using the `Checkout.configure` method. This involves setting merchant details, session information, and display controls for billing address, customer email, and order summary.

```javascript
Checkout.configure({
                merchant: '<Merchant ID>',  // Your merchant Id
                session: {
                    id: "SESSION0002561575526H6901242G59",   // This is the session.id value that was generated in the first step
                },
                interaction: {
                    merchant: {
                        name: 'Merchant Name',	// This is your merchant name that will be display on the checkout page to your customer, typically it will be a brand name.
                        email: "info@merchant.com",	// The merchant email, the will be displayed on the checkout page.
                        phone: "+9661234567890",	// The merchant phone, the will be displayed on the checkout page.
                        logo: "https://ap-gateway.mastercard.com/api/documentation/resource/footer.png",   // The merchant logo on the checkout page.
                        url: "https://www.mastercard.com",  // the merchant website
                        address: {	// Merchant Address, the will be displayed on the checkout page.
                            line1: 'Jeddah',   									
                            line2: 'Saudi Arabia'    	     
                        }    
                    },
                    displayControl: {
                        billingAddress: "HIDE",		// Prompt the user to enter the billing address. Possible options are "HIDE", "MANDATORY", "OPTIONAL", or "READ_ONLY".
                        customerEmail: "HIDE",		// Prompt the user to enter their email. Possible options are "HIDE", "MANDATORY", "OPTIONAL", or "READ_ONLY".
                        orderSummary: "SHOW",		// Display the order summary to in the checkout page. Possible options are "HIDE", "SHOW", or "SHOW_PARTIAL".
                        paymentConfirmation: "HIDE",	// Prompt the user to confirm the payment before submitting. Possible options are "HIDE", or "SHOW".
                        shipping: "HIDE"		// Display the shipping address to the user. Possible options are "HIDE", or "READ_ONLY".
                    },
                },
            });

```

--------------------------------

### Create Checkout Session API Request (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

This snippet demonstrates the structure of a POST API request to create a checkout session. It includes essential parameters like operation, return URL, order details (amount, currency, ID, reference, description), and transaction reference. The request is authenticated using Basic HTTP authentication.

```javascript
{
	"apiOperation": "CREATE_CHECKOUT_SESSION",
	"interaction": {
		"operation": "PURCHASE",	// Other operations available are "AUTHORIZE", "VERIFY", and "NONE".
		"returnUrl": "https://www.yourwebsite.com/someResultPage"	// Page where the customer will be redirected to after payment
	},
	"order": {
		"amount": 1.00,	// The amount for the order
		"currency": "<Currency>",	// The currency in ISO 4217 alpha code, e.g. USD, SGD, AUD, SAR, AED etc..
		"id": "<Order Id>",	// An order is the array of transactions. This is the identifier for this order. Can be Any alphanumerical value you assign.
		"reference": "<Order Reference>",	// This is the reference for this order. Can be Any alphanumerical value you assign.
		"description": "Shoes and flipflops"
	},
	"transaction": {
		"reference": "<Transaction Reference>"	// The transaction reference for this attempt.
	}
}
```

--------------------------------

### Create Session API Request - Direct Integration

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

This snippet demonstrates the POST request to create a session for transaction processing. It requires the Merchant ID and API version. No request body is needed, and the response contains a Session ID that must be saved for subsequent steps.

```HTTP
POST	https://{{MsoUrl}}/api/rest/version/{{ApiVersion}}/merchant/{{MerchantId}}/session/

```

--------------------------------

### Make Payment Transaction Request (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/pay-with-token.md

This snippet shows the final payment request after successful 3DS authentication. It includes the 'PAY' API operation, transaction ID from authentication, order details, and the token with security code for the source of funds.

```javascript
{
	"apiOperation": "PAY",
	"authentication":{
		"transactionId": "TxnID_{{AttemptNum}}"
	},
	"order": {
		"amount": 1.00,
		"currency": "SAR",
		"reference": "OrdRef_{{AttemptNum}}"
	},
	"transaction": {
		"reference": "TrxRef_{{AttemptNum}}",
		"source": "INTERNET"
    	},
	"sourceOfFunds": {
		"token":"{{Token}}",
		"provided": {
			"card": {
				"securityCode": "100"
			}
		}
	}
}
```

--------------------------------

### Initiate 3DS Authentication - Direct Integration

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

This snippet demonstrates the initiation of 3D Secure (3DS) authentication for a transaction. It uses a PUT request to the order/transaction endpoint, specifying the operation as INITIATE_AUTHENTICATION and providing details about the authentication channel, purpose, order, and the session ID. This is a critical step for secure transactions, though it can be skipped if 3DS is not required.

```javascript
{
	"apiOperation":"INITIATE_AUTHENTICATION",
	"authentication":{
		"acceptVersions":"3DS1,3DS2",
	    "channel":"PAYER_BROWSER",
	    "purpose":"PAYMENT_TRANSACTION"
	},
	"correlationId":"test",
	"order":{
		"reference": "OrdRef_{{AttemptNum}}",
    	"currency":"SAR"
	},
	"session": {
		"id": "{{SessionId}}"
	},
	"transaction": {
		"reference": "TrxRef_{{AttemptNum}}"
	}
}

```

--------------------------------

### Authenticate Payer with 3DS API Request - JavaScript

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/direct.md

This snippet demonstrates the JSON body for the 'AUTHENTICATE_PAYER' API operation. It includes details for authentication, device information, order amount, and session ID. This request is part of the 3D Secure (3DS) authentication flow.

```javascript
{
	"apiOperation": "AUTHENTICATE_PAYER",
	"authentication":{
		"redirectResponseUrl":	"https://merchant.com/your-redirection-page"
	},
	"correlationId":"test",
	"device": {
		"browser": "MOZILLA",
	    "browserDetails": {
			"3DSecureChallengeWindowSize": "FULL_SCREEN",
		    "acceptHeaders": "application/json",
		    "colorDepth": 24,
		    "javaEnabled": true,
		    "language": "en-US",
		    "screenHeight": 640,
		    "screenWidth": 480,
		    "timeZone": 273
	    },
		"ipAddress": "127.0.0.1"
	},
	"order":{
		"amount":"1.00",
	    "currency":"SAR"
	},
	"session": {
		"id": "{{SessionId}}"
	}
}
```

--------------------------------

### Retrieve Order Result

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

After a user completes a payment, this endpoint allows you to retrieve the order status and details. It requires authentication and returns information about the transaction's success.

```APIDOC
## Retrieve Order Result

### Description
Retrieve the payment result after the user submits payment. This endpoint returns the order status, which can be used to confirm if the transaction was successful.

### Method
GET

### Endpoint
`https://<Bank URL>/api/rest/version/<API Version>/merchant/<Merchant ID>/order/<Order Id>`

### Parameters
#### Path Parameters
- **Bank URL** (string) - Required - The base URL of the bank's API.
- **API Version** (string) - Required - The API version to use.
- **Merchant ID** (string) - Required - Your merchant ID.
- **Order Id** (string) - Required - The ID of the order to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET https://<Bank URL>/api/rest/version/<API Version>/merchant/<Merchant ID>/order/<Order Id>
```

#### Authorization
Basic HTTP authentication.
- **Username**: `merchant.<your gateway merchant ID>`
- **Password**: Your API password (obtained from the Merchant Administration portal).

### Response
#### Success Response (200)
Returns an object containing the order status and transaction details.

#### Response Example
```json
{
  "status": "CAPTURED",
  "totalAuthorizedAmount": 8000,
  "totalCapturedAmount": 8000,
  "totalRefundedAmount": 0
}
```

**Note:** Look for the `status` field to confirm the order was successfully captured (e.g., "CAPTURED").
```

--------------------------------

### Create Checkout Session API Response (JavaScript)

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

This snippet shows a successful response from the Mastercard Gateway API after creating a checkout session. It includes the merchant ID, a success indicator, and crucial session details such as the session ID, update status, and version, which are needed for subsequent integration steps.

```javascript
{
    "merchant": "<Merchant ID>",
    "result": "SUCCESS",
    "session": {
        "id": "SESSION0002561575526H6901242G59",
        "updateStatus": "SUCCESS",
        "version": "0bd6923c01"
    },
    "successIndicator": "2a149e4aed1d4818"
}
```

--------------------------------

### Check Order Status from Response

Source: https://github.com/scriptpapi/mpgs-integration-guides-and-samples/blob/main/docs/hosted-checkout.md

Examine the 'status' field in the API response to confirm if the order was successfully captured. Key indicators include 'CAPTURED' status and matching authorized, captured, and refunded amounts.

```javascript
"status": "CAPTURED",
"totalAuthorizedAmount": 8000,
"totalCapturedAmount": 8000,
"totalRefundedAmount": 0

```