<commit_before>KonnectedPay JavaScript SDK
===========================

Installation
------------

1. Check the [latest release](https://github.com/Nexstream/KonnectedPayJS/releases).
2. Download the `konnectedpay.js` or `konnectedpay.min.js` file from the latest release.
3. Add this file to your project.
4. Add this file to your HTML pages:

    ```html
        <script src="konnectedpay.js"></script>
    ```
5. Start using the [API](#api)


<a name="api"></a>
API
---

### requestPayment

```javascript
KonnectedPay.requestPayment({
    merchantId: "your konnectedpay merchant id",     // From your KonnectedPay account.
    clientSecret: "your konnectedpay client secret", // From your KonnectedPay account.
    amount: 1234.56,
    transId: "your unique transaction id",
    currencyCode: "MYR",
    fullName: "payer's full name",
    email: "payer's email address",
    userId: "your internal user ID",
    returnUrl: "http://return-to-this-url/when/payment/done/or/failed",
    responseMethod: "GET" | "POST" | "HASH" | undefined,
    rememberCard: true, // OPTIONAL. Set to false if you do NOT want to
        // remember the user's card (see Retrieving Tokenised Payment Method).
}, "_blank")
```

If `returnUrl` is not provided, the payment page will close itself after payment
completion (useful if the 2nd argument is "_blank").

If the 2nd argument is not provided, the user will be sent to the payment page
in the same window/tab. If it is set to "_blank", a new window/tab will be
opened.

Response methods (if `responseMethod` is not provided, we default to "GET"):

- GET: Payment status will be returned to your returnUrl via GET parameters.
- POST: Payment status will be POST'ed to your returnUrl.
- HASH: Payment status will be returned to your returnUrl via Hash parameters.
    e,g, "http://my-return-url/payment-received#PAYMENT_RESULTS"

Any GET/HASH parameters which already exists in your returnUrl will be
maintained - KonnectedPay's response fields are added after any existing
parameters.

**Errors:**

- This function throws JS Error objects if there are any missing/invalid fields.

**Returns:**

This function does not return anything.


### getPaymentResults

Check and retrieve KonnectedPay payment results.

```javascript
KonnectedPay.getPaymentResults("GET")
KonnectedPay.getPaymentResults("HASH")
```

**Errors:**

If a result parameter is found but the value is invalid, a JS Error object is
thrown.

**Returns:**

Returns null if there are no payment results available, the results object if a
valid result is found.


### getTokens

Get a list of remembered payment methods

```javascript
KonnectedPay.getTokens(clientSecret, userId, function (successful, tokens) {
    if(successful) {
        // Successfully retrieved tokens.
        // `tokens` parameter is an array of tokens.
    } else {
        // Failed to retrieve tokens.
        // `tokens` parameter is the error message.<commit_msg>Added description of results object format to README<commit_after>KonnectedPay JavaScript SDK
===========================

Installation
------------

1. Check the [latest release](https://github.com/Nexstream/KonnectedPayJS/releases).
2. Download the `konnectedpay.js` or `konnectedpay.min.js` file from the latest release.
3. Add this file to your project.
4. Add this file to your HTML pages:

    ```html
        <script src="konnectedpay.js"></script>
    ```
5. Start using the [API](#api)


<a name="api"></a>
API
---

### requestPayment

```javascript
KonnectedPay.requestPayment({
    merchantId: "your konnectedpay merchant id",     // From your KonnectedPay account.
    clientSecret: "your konnectedpay client secret", // From your KonnectedPay account.
    amount: 1234.56,
    transId: "your unique transaction id",
    currencyCode: "MYR",
    fullName: "payer's <NAME>",
    email: "payer's email address",
    userId: "your internal user ID",
    returnUrl: "http://return-to-this-url/when/payment/done/or/failed",
    responseMethod: "GET" | "POST" | "HASH" | undefined,
    rememberCard: true, // OPTIONAL. Set to false if you do NOT want to
        // remember the user's card (see Retrieving Tokenised Payment Method).
}, "_blank")
```

If `returnUrl` is not provided, the payment page will close itself after payment
completion (useful if the 2nd argument is "_blank").

If the 2nd argument is not provided, the user will be sent to the payment page
in the same window/tab. If it is set to "_blank", a new window/tab will be
opened.

Response methods (if `responseMethod` is not provided, we default to "GET"):

- GET: Payment status will be returned to your returnUrl via GET parameters.
- POST: Payment status will be POST'ed to your returnUrl.
- HASH: Payment status will be returned to your returnUrl via Hash parameters.
    e,g, "http://my-return-url/payment-received#PAYMENT_RESULTS"

Any GET/HASH parameters which already exists in your returnUrl will be
maintained - KonnectedPay's response fields are added after any existing
parameters.

**Errors:**

- This function throws JS Error objects if there are any missing/invalid fields.

**Returns:**

This function does not return anything.


### getPaymentResults

Check and retrieve KonnectedPay payment results.

```javascript
KonnectedPay.getPaymentResults("GET")
KonnectedPay.getPaymentResults("HASH")
```

**Errors:**

If a result parameter is found but the value is invalid, a JS Error object is
thrown.

**Returns:**

Returns null if there are no payment results available, the results object if a
valid result is found.

Results object has this format:

```
{
    "amount": "1.00",
    "status": "S",
    "code": "0",
    "desc": "No error",
    "tranId": "PY130516085834-233100"
}
```


### getTokens

Get a list of remembered payment methods

```javascript
KonnectedPay.getTokens(clientSecret, userId, function (successful, tokens) {
    if(successful) {
        // Successfully retrieved tokens.
        // `tokens` parameter is an array of tokens.
    } else {
        // Failed to retrieve tokens.
        // `tokens` parameter is the error message.
{'fraction_non_alphanumeric': 0.11414473684210526, 'fraction_numerical': 0.007894736842105263, 'mean_word_length': 3.747072599531616, 'pattern_counts': {'":': 5, '<': 12, '<?xml version=': 0, '>': 12, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1234142', 'n_tokens_mistral': 1786, 'n_tokens_neox': 1719, 'n_words': 703}