### 3D Get Token Integration

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/3d-get-token.md

This section outlines the process for obtaining a token using the 3D Get Token integration. It includes production and sandbox endpoints, mandatory request parameters with their details and examples, and the structure of the response parameters.

```APIDOC
## 3D Get Token Integration

This integration method is used to obtain a token for future payments. It is not a traditional RESTful API.

### Endpoints

- **Production URL Endpoint:** `https://app.senangpay.my/tokenization/{merchant_id}` (GET/POST)
- **Sandbox URL Endpoint:** `https://sandbox.senangpay.my/tokenization/{merchant_id}` (GET/POST)

### Request Parameters (All Mandatory)

- **order_id** (string) - Required - Used by your system to track the request and response. It can be any value.
- **name** (string) - Required - Your customer’s name. Maximum length is 100 characters. Example: `Micheal Solomon`
- **email** (string) - Required - Your customer’s e-mail. Example: `michael@theboringcompany.com`
- **phone** (string) - Required - Your customer’s phone number. Example: `+60123456789`
- **hash** (string) - Required - This hash confirms you are an active senangPay merchant. Generate it using HMAC SHA256 with your senangPay secret key.

#### Hash Generation Example (PHP)

```php
$merchant_id = '123456789';
$secret_key = '34-9887';
$order_id = 'abc654321'; // Your order ID
$string_to_hash = $merchant_id . $order_id;
$final_hash = hash_hmac('SHA256', $string_to_hash, $secret_key);
```

### Response Parameters

- **status** (string) - Token creation status. `1` if successful, `0` if failed.
- **order_id** (string) - The order ID provided earlier.
- **token** (string) - Generated if card validation succeeds, used for future payments. If validation fails, the token value is `0`.
- **cc_num** (string) - Last four digits of the card, displayed as `XXXXXXXXXXXX1118`. If validation fails, the value is `0000`.
- **cc_type** (string) - Indicates the card type, either `vs` for Visa or `mc` for Mastercard. If validation fails, the value is `xx`.
- **msg** (string) - Card validation status message. Provides different messages to detail success or failure reasons.
- **hash** (string) - Generated by senangPay to verify the response. Use HMAC SHA256 with your secret key to validate it.

#### Hash Validation Example (PHP)

```php
$secret_key = '34-9887';
$order_id = urldecode($_GET['order_id']);
$status_id = urldecode($_GET['status_id']);
$token = urldecode($_GET['token']);
$cc_num = urldecode($_GET['cc_num']);
$cc_type = urldecode($_GET['cc_type']);
$msg = urldecode($_GET['msg']);
$string_to_hash = $merchant_id . $order_id . $status_id . $token . $cc_num . $cc_type . $msg;
$hash = hash_hmac('sha256', $string_to_hash, $secret_key);
```

### Callback

The Callback URL is an optional feature used as an alternative notification to the merchant backend in case of a transaction flow breakdown. It is recommended to ensure data integrity. The callback process sends the same parameters as the return URL. The callback URL must print out a simple 'OK' response. senangPay will fire the callback one minute after validation is done.
```

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

### Generate Request Hash (PHP)

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/3d-get-token.md

Example of how to generate the HMAC SHA256 hash for the request parameters using PHP. This hash is required to authenticate your requests.

```php
$merchant_id = '123456789';
$secret_key = '34-9887';
$order_id = 'abc654321'; // Your order ID
$string_to_hash = $merchant_id . $order_id;
$final_hash = hash_hmac('SHA256', $string_to_hash, $secret_key);
```

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

### Validate Response Hash (PHP)

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/3d-get-token.md

Example of how to validate the HMAC SHA256 hash received in the API response using PHP. This ensures the integrity of the data sent back by senangPay.

```php
$secret_key = '34-9887';
$order_id = urldecode($_GET['order_id']);
$status_id = urldecode($_GET['status_id']);
$token = urldecode($_GET['token']);
$cc_num = urldecode($_GET['cc_num']);
$cc_type = urldecode($_GET['cc_type']);
$msg = urldecode($_GET['msg']);
$string_to_hash = $merchant_id . $order_id . $status_id . $token . $cc_num . $cc_type . $msg;
$hash = hash_hmac('sha256', $string_to_hash, $secret_key);
```

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

### Validate Payment Token

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/secure-payments-via-tokenisation-api-with-verified-cards.md

This endpoint validates a payment token generated by the Get Token API. It confirms the card associated with the token has been successfully verified.

```APIDOC
## POST /apiv1/validate_token

### Description
Validates a payment token to confirm card verification status.

### Method
POST

### Endpoint
https://app.senangpay.my/apiv1/validate_token

### Parameters
#### Request Body
- **token** (string) - Required - Generated token from Get Token API.

### Request Example
{
  "token": "GENERATED_TOKEN_HERE"
}

### Response
#### Success Response (200)
- **status** (string) - Token validation result: '1' for success, '0' for failure.
- **msg** (string) - Message on token validation. e.g., "Card has been successfully verified".
- **token** (string) - The token from the Get Token API, unchanged.
```

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

### Update Token Status

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/secure-payments-via-tokenisation-api-with-verified-cards.md

This endpoint allows you to update the status of a generated token, enabling or disabling it for future use. It requires a valid token obtained from the Get Token API.

```APIDOC
## POST /apiv1/update_token_status

### Description
Updates the status (enable/disable) of a previously generated token.

### Method
POST

### Endpoint
/apiv1/update_token_status

### Parameters
#### Request Body
- **token** (string) - Required - Generated token from Get Token API.

### Request Example
{
  "token": "GENERATED_TOKEN_HERE"
}

### Response
#### Success Response (200)
- **msg** (string) - Message for the token status update.
- **token** (string) - The updated token identifier.
```

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

### Sample Response for Credit Card Payment

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/secure-payments-via-tokenisation-api-with-verified-cards.md

This is a sample JSON response received after a successful credit card payment transaction via the Tokenisation API. It includes transaction status, IDs, amount paid, a status message, and a hash for verification.

```javascript
{
   "status":1,
   "transaction_id":"14951544812820",
   "order_id":"1234",
   "amount_paid":1000,
   "msg":"Payment was successful",
   "hash":"99b6e99bb0aa663101b1e4f6f8d69c2efb41ef81a5a7aa030bf76a098a03d233"
}
```

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

### Pay with credit card using token

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/secure-payments-via-tokenisation-api-with-verified-cards.md

This API allows you to process payments by using a previously generated token for a customer's credit card. It requires customer and order details, along with the token and a security hash.

```APIDOC
## POST /apiv1/pay_cc

### Description
Processes a payment using a credit card token. This endpoint requires customer information, order details, a generated token, and a security hash for verification.

### Method
POST

### Endpoint
https://app.senangpay.my/apiv1/pay_cc

### Parameters
#### Request Body
- **name** (string) - Required - The customer's name. Maximum length is 100 characters.
- **email** (string) - Required - The customer's e-mail address.
- **detail** (string) - Required - Order details. Maximum length is 100 characters.
- **phone** (string) - Required - The customer's phone number.
- **order_id** (string) - Required - Your order ID. Can be a number or string. Other characters are invalid.
- **amount** (integer) - Required - Your order amount in integer format. Convert from decimals as necessary (e.g., RM 2.00 becomes 200).
- **token** (string) - Required - Generated token from the Get Token API.
- **hash** (string) - Required - A security hash generated using your secret key with the HMAC SHA256 algorithm. Format: `<your merchant id><name><email><phone><detail><order_id><amount>`.

### Response
#### Success Response (200)
- **status** (integer) - Transaction status. 1 for successful, 0 for failed.
- **transaction_id** (string) - Your transaction ID number.
- **order_id** (string) - Your original order ID.
- **amount_paid** (integer) - Amount transacted from the credit card in integer format.
- **msg** (string) - Transaction status message. "Payment was successful" for success, or an error message for failure.
- **hash** (string) - A security hash generated using your secret key with the HMAC SHA256 algorithm. Format: `<merchant_id><status_id><order_id><transaction_id><amount_paid><msg>`.

### Request Example
```json
{
  "name": "Abu Bin Ali",
  "email": "ahmad@google.com",
  "detail": "Order for product id #4",
  "phone": "0109876543",
  "order_id": "123",
  "amount": 200,
  "token": "generated_token_here",
  "hash": "calculated_hash_here"
}
```

### Response Example
```json
{
   "status":1,
   "transaction_id":"14951544812820",
   "order_id":"1234",
   "amount_paid":1000,
   "msg":"Payment was successful",
   "hash":"99b6e99bb0aa663101b1e4f6f8d69c2efb41ef81a5a7aa030bf76a098a03d233"
}
```
```

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

### Verify MD5 Hash

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/manual-integration-api-open-api/generate-secure-hash.md

Use this snippet to generate an MD5 hash from received parameters (Secret Key, status_id, order_id, transaction_id, msg) to verify data integrity. Compare this generated hash with the one sent by senangPay.

```php
md5($str) => 69686562c29ad3f7955b1843a5c275ca
```

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

### Generate MD5 Hash

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/manual-integration-api-open-api/generate-secure-hash.md

Use this snippet to generate an MD5 hash for a string composed of Secret Key, Detail, Amount, and Order ID. This is useful for creating secure request payloads.

```php
md5($str) => 0bde51ff340f110ab7331a902aa969e7
```

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

### POST /payment/{merchantID}

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/manual-integration-api-open-api/README.md

Initiates a payment transaction. This endpoint requires the merchant's ID in the path and a set of payment details in the request body to process a transaction.

```APIDOC
## POST /payment/{merchantID}

### Description
Initiates a payment transaction. This endpoint requires the merchant's ID in the path and a set of payment details in the request body to process a transaction.

### Method
POST

### Endpoint
/payment/{merchantID}

### Parameters
#### Path Parameters
- **merchantID** (string) - Required - The unique identifier for the merchant.

#### Request Body
- **detail** (string) - Required - Description displayed during payment (max 500 characters). Underscores (_) convert to spaces. Allowed characters: A-Z, a-z, 0-9, period (.), comma (,), dash (-), underscore (_).
- **amount** (number) - Required - The charge amount, formatted to 2 decimal places.
- **order_id** (string) - Required - Identifies the shopping cart on return after payment (max 100 characters). Allowed characters: A-Z, a-z, 0-9, dash (-).
- **hash** (string) - Required - Ensures data integrity between the merchant’s cart and senangPay.
- **name** (string) - Optional - Customer's name.
- **email** (string) - Optional - Customer's e-mail.
- **phone** (string) - Optional - Customer's phone number.
- **timeout** (integer) - Optional - Sets the payment timeout in seconds. Minimum is 60 seconds. Defaults to 60 seconds if below minimum. No timeout if omitted.

### Request Example
```json
{
  "detail": "Shopping_cart_id_30",
  "amount": 25.50,
  "order_id": "3432D4",
  "hash": "generated_hash_value",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "1234567890",
  "timeout": 480
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the payment initiation.
- **redirect_url** (string) - The URL to redirect the user to for completing the payment.

#### Response Example
```json
{
  "status": "success",
  "redirect_url": "https://sandbox.senangpay.my/payment/initjs/xxxxxxxxxxxxxxxx"
}
```
```

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

### POST /recurring/payment/{merchantID}

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/api-for-recurring-payment/README.md

Initiates a recurring payment transaction. This endpoint requires specific parameters to identify the order, recurring item, and ensure data integrity through a hash. Optional fields for customer name, email, and phone can also be provided.

```APIDOC
## POST /recurring/payment/{merchantID}

### Description
Initiates a recurring payment transaction. This endpoint requires specific parameters to identify the order, recurring item, and ensure data integrity through a hash. Optional fields for customer name, email, and phone can also be provided.

### Method
POST

### Endpoint
/recurring/payment/{merchantID}

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

#### Request Body
- **order_id** (string) - Required - Identifies the shopping cart. Maximum length is 100 characters. Allowed: A-Z, a-z, 0-9, and dash (-). Example: 3432D4.
- **recurring_id** (string) - Required - Identifies which recurring product/item senangPay processes.
- **hash** (string) - Required - Ensures data integrity between the merchant’s cart and senangPay.
- **name** (string) - Optional - Adds the customer's name automatically. This is optional and can be edited.
- **email** (string) - Optional - Populates the customer's e-mail for them. This is optional and can be edited.
- **phone** (string) - Optional - Inserts the customer's phone number. This is optional and adjustable by the customer.

### Request Example
{
  "order_id": "3432D4",
  "recurring_id": "recurring_item_123",
  "hash": "generated_hash_value",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "1234567890"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the transaction.
- **message** (string) - A message describing the result of the transaction.

#### Response Example
{
  "status": "success",
  "message": "Recurring payment initiated successfully."
}
```

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

### Verify SHA256 HMAC Hash

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/manual-integration-api-open-api/generate-secure-hash.md

This snippet shows how to generate a SHA256 HMAC hash from received parameters for verification. Compare the generated hash with the one provided by senangPay to ensure data has not been tampered with.

```php
hash_hmac(‘SHA256′, $str, ’53-784’) => 4ca7837c6c4ddb5f6ba573ea701235b2d04bc6400d32787539e07aaf319eb70f
```

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

### Verify Secure Hash for Recurring Payment

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/api-for-recurring-payment/generate-secure-hash-recurring-payment.md

This PHP code demonstrates how to verify a secure hash received from senangPay for recurring payments. It uses the secret key, status ID, order ID, transaction ID, and message to generate a hash for comparison.

```php
$status_id = '1';
$order_id = '12';
$transaction_id = '14363538840';
$msg = 'Payment_was_successful';

$hash = hash(‘sha256’,$secret_key.$status_id.$order_id.$transaction_id.$msg);

?>
```

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

### Enable or Disable Credit Cards

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/tokenisation-api/secure-payments-via-tokenisation-api-with-verified-cards.md

This API allows merchants to enable or disable the status of credit cards associated with their account. This is useful for managing which cards can be used for future transactions.

```APIDOC
## POST /apiv1/update_token_status

### Description
Updates the status of credit cards, allowing merchants to enable or disable them for future use. Requires basic authorization.

### Method
POST

### Endpoint
https://app.senangpay.my/apiv1/update_token_status

### Parameters
#### Request Body
(Details for request body parameters such as token status, card identifiers, etc., are not provided in the source text and would need to be inferred or obtained from additional documentation.)

### Response
(Details for response parameters are not provided in the source text and would need to be inferred or obtained from additional documentation.)
```

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

### Generate SHA256 HMAC Hash

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/manual-integration-api-open-api/generate-secure-hash.md

This snippet demonstrates how to generate a SHA256 HMAC hash using a secret key. It's used for securing data transmission by hashing a specific string format.

```php
hash_hmac(‘SHA256′, $str, ’53-784’) => 74422328b44d30bf150fffbae89bbb42b885f9ac0960e2a3ddccc0cf9aa48e39
```

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

### Generate Secure Hash for Recurring Payment

Source: https://github.com/senangpay/api_catalog/blob/main/integration-api/api-for-recurring-payment/generate-secure-hash-recurring-payment.md

Use this PHP code to generate a secure hash for recurring payments. It concatenates the secret key, recurring ID, and order ID before hashing with SHA256.

```php
<?php
$secret_key = ‘21245-957’;
$recurring_id = ‘1234’;
$order_id = ’12’;

$hash = hash(‘sha256’,$secret_key.$recurring_id.$order_id);

?>
```

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

### OAuth2 Redirect Handler in Swagger UI

Source: https://github.com/senangpay/api_catalog/blob/main/swagger_temp/oauth2-redirect.html

This JavaScript code runs in a popup window to capture the OAuth2 redirect, extract authorization codes or tokens, and send them back to the main Swagger UI window. It handles different OAuth2 flows and validates the state parameter for security.

```javascript
'use strict';
function run () {
    var oauth2 = window.opener.swaggerUIRedirectOauth2;
    var sentState = oauth2.state;
    var redirectUrl = oauth2.redirectUrl;
    var isValid, qp, arr;

    if (/code|token|error/.test(window.location.hash)) {
        qp = window.location.hash.substring(1).replace('?', '&');
    } else {
        qp = location.search.substring(1);
    }

    arr = qp.split("&");
    arr.forEach(function (v,i,_arr) {
        _arr[i] = '"' + v.replace('=', '":"') + '"';
    });

    qp = qp ? JSON.parse('{' + arr.join() + '}', function (key, value) {
        return key === "" ? value : decodeURIComponent(value);
    } ) : {};

    isValid = qp.state === sentState;

    if (( oauth2.auth.schema.get("flow") === "accessCode" || oauth2.auth.schema.get("flow") === "authorizationCode" || oauth2.auth.schema.get("flow") === "authorization_code" ) && !oauth2.auth.code) {
        if (!isValid) {
            oauth2.errCb({ authId: oauth2.auth.name, source: "auth", level: "warning", message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
            });
        }

        if (qp.code) {
            delete oauth2.state;
            oauth2.auth.code = qp.code;
            oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
        } else {
            let oauthErrorMsg;
            if (qp.error) {
                oauthErrorMsg = "["+qp.error+"]: " + (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") + (qp.error_uri ? "More info: "+qp.error_uri : "");
            }
            oauth2.errCb({ authId: oauth2.auth.name, source: "auth", level: "error", message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
            });
        }
    } else {
        oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
    }

    window.close();
}

if (document.readyState !== 'loading') {
    run();
} else {
    document.addEventListener('DOMContentLoaded', function () {
        run();
    });
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.