# Checkout

## 1. Create Session.

First you need to create a session from your backend using the API key generated through the dashboard, a session must have one of two types, `add_card` or `payment`.

{% tabs %}
{% tab title="Add Card" %}

####

{% hint style="info" %}

#### Add Card

the `add_card` session is used to store a customer card, a unique `customerId` is required for `add_card` session type, while creating a new session, using this `Id`, you can get the corresponding customer cards when calling the `getSession()` method in the SDK
{% endhint %}

**Request**

```bash
curl --location --request POST 'https://sandbox.nearpay.io/checkout/sessions' \
--header 'Authorization: RoD43N1tjJs221nM37LR72Kf7IHG3uDYJAF4pu2HlrBkj9oxGdiUBO1sBGYN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "add_card",
    "customer": {
        "id": "${UUID}",
        "name": "", // optional
        "email": "", // optional
        "mobile": "+966XXXXXXXXX" // optional
    }
}'
```

**Response**

```json
{
    "type": "payment",
    "status": "ready",
    "amount": 15000,
    "currency": "SAR",
    "callback_url": "https://google.com.sa",
    "extrernal_customer": {
        "id": "cc0a7499-0a7f-4616-b5ef-585dfb7e6978"
    },
    "customer": {
        "id": "dab4d476-6061-42e1-b0ce-d8a6e65b0e25",
        "name": null,
        "email": null,
        "mobile": null,
        "customer_id": "${UUID}",
        "created_at": "2022-05-30T11:39:11.734Z",
        "updated_at": "2022-05-30T11:39:11.734Z",
        "cards": [
            {
                "id": "${UUID}",
                "type": "card",
                "number": "4242",
                "year": "32",
                "month": "02",
                "name": "ABDULELAH OMER",
                "brand": "visa",
                "external_customer_id": "${UUID}",
                "card_hash": "8942bb738d827fc64466b2e02f900adec7c90e74b2a522bc35da313729eca665",
                "created_at": "2022-05-30T11:46:52.752Z",
                "updated_at": "2022-05-30T11:46:52.752Z"
            }
        ]
    },
    "client": {
        "id": "${UUID}"
    },
    "reference_id": null,
    "id": "${UUID}",
    "created_at": "2022-05-30T11:48:23.482Z",
    "updated_at": "2022-05-30T11:48:23.482Z"
}
```

{% endtab %}

{% tab title="Payment" %}
{% hint style="info" %}
**Payment**

contrary to the add\_card session, the payment session is used to process a payment request only.
{% endhint %}

**Request**

```bash
curl --location --request POST 'https://sandbox.nearpay.io/checkout/sessions' \
--header 'Authorization: RoD43N1tjJs221nM37LR72Kf7IHG3uDYJAF4pu2HlrBkj9oxGdiUBO1sBGYN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "payment",
    "amount": 15000,
    "currency": "SAR",
    "callback_url": "https://[my_callback_url]",
    "customer": {
        "id": "${UUID}"
        "name": "", // optional
        "email": "", // optional
        "mobile": "+966XXXXXXXXX" // optional
    }
}'
```

**Response**

```json
{
    "type": "payment",
    "status": "ready",
    "amount": 15000,
    "currency": "SAR",
    "callback_url": "https://google.com.sa",
    "extrernal_customer": {
        "id": "cc0a7499-0a7f-4616-b5ef-585dfb7e6978"
    },
    "customer": {
        "id": "dab4d476-6061-42e1-b0ce-d8a6e65b0e25",
        "name": null,
        "email": null,
        "mobile": null,
        "customer_id": "${UUID}",
        "created_at": "2022-05-30T11:39:11.734Z",
        "updated_at": "2022-05-30T11:39:11.734Z",
        "cards": [
            {
                "id": "${UUID}",
                "type": "card",
                "number": "4242",
                "year": "32",
                "month": "02",
                "name": "ABDULELAH OMER",
                "brand": "visa",
                "external_customer_id": "${UUID}",
                "card_hash": "8942bb738d827fc64466b2e02f900adec7c90e74b2a522bc35da313729eca665",
                "created_at": "2022-05-30T11:46:52.752Z",
                "updated_at": "2022-05-30T11:46:52.752Z"
            }
        ]
    },
    "client": {
        "id": "${UUID}"
    },
    "reference_id": null,
    "id": "${UUID}",
    "created_at": "2022-05-30T11:48:23.482Z",
    "updated_at": "2022-05-30T11:48:23.482Z"
}
```

{% endtab %}
{% endtabs %}

## 2. Install SDK.

Install the payment SDK using either `npm` or `yarn`

{% tabs %}
{% tab title="JavaScript ( Web )" %}

```bash
# npm
npm install @nearvault/payment-sdk
# or yarn
yarn add @nearvault/payment-sdk
```

{% endtab %}
{% endtabs %}

## 3. PaymentSDK.

Using the SDK, you can use a previously created session to add cards, create payments and fetch previous payments as well.

{% tabs %}
{% tab title="List Cards" %}
{% hint style="info" %}
**List Cards**

You can list the cards associated with the customer\_id, you can get details about your current session and the cards associated to the customer that owns the session by calling the `getSession()` method, this method will return a list of saved customer cards along with the session details
{% endhint %}

**Request**:

```javascript
import PaymentSDK from '@nearvault/payment-sdk';

let sessionId = "${sessionId}";

const nearVault = new PaymentSDK(sessionId);
let session = await nearVault.getSession();

```

**Session Object**:

```json
{
    "session": {
        "amount": 131,
        "currency": "SAR"
    },
    "cards": [
        {
            "id": "ec4a6b40-f5f5-48d7-a667-41efa053b719",
            "number": "4242",
            "year": "24",
            "month": "02",
            "name": "Hamzah AL Frahan",
            "brand": "visa"
        }
    ]
}
```

{% endtab %}

{% tab title="Add Card" %}
{% hint style="info" %}
**Add Card**

In order to add a captured card from the client, you should pass the card data to the `addCard()` method.
{% endhint %}

**Request**:

```javascript
import PaymentSDK from '@nearvault/payment-sdk';

let sessionId = "${sessionId}";
let card = {
    number: "4242424242424242",
    name: "card holader name",
    month: "12",
    year: "25",
    securityCode: "100"
}

const nearVault = new PaymentSDK(sessionId);
const addedCard = await nearVault.addCard(card);

if(result.status === 'success') // add to customer profile

```

**Response**

```json
{
    "id": "e7886343-cc95-4e46-919b-711817050222",
    "status": "success"
}
```

{% endtab %}

{% tab title="Create Payment" %}
{% hint style="info" %}

#### New Card

For the new cards, you can create a payment with them by calling the `pay` method and passing the card object.

**Note: cards are not saved when creating a payment directly with a new card.**
{% endhint %}

**Request**:

```javascript
import PaymentSDK from '@nearvault/payment-sdk';

let sessionId = "${sessionId}";
let card = {
    number: "4242424242424242",
    name: "card holader name",
    month: "12",
    year: "25",
    securityCode: "100"
}

const nearVault = new PaymentSDK(sessionId);
const payment = await nearVault.pay(card);

if(result.redirect_url) return window.location.assign(result.redirect_url);
else // send the tranasction id to your baceknd

```

**Response ( Redirect )**

```javascript
{
    "redirect_url": "https://3ds2-sandbox.ckotech.co/interceptor/3ds_btjobzgahssujesvievv7kibze",
    "message": "pending"
}
```

**Response ( Success )**

```javascript
{
    "message": "successed",
    "transaction_id": "53333bf2-b9a0-4505-bc1c-7cc5d81ea7fb"
}
```

{% endtab %}

{% tab title="Pay With Saved Card" %}
{% hint style="info" %}

#### Existing Card

To create a payment with an existing card, you have to get the card Id by one of the latter two steps, call the `payWithCard` method and pass the card Id as a parameter, e.g
{% endhint %}

**Request**

```javascript
import PaymentSDK from '@nearvault/payment-sdk';

let sessionId = "${sessionId}";
let cardId = "${cardId}";

const nearVault = new PaymentSDK(sessionId);
const result = await nearVault.payWithCard(cardId);

if(result.redirect_url) return window.location.assign(result.redirect_url);
else // send the tranasction id to your baceknd

```

**Response ( Redirect )**

```javascript
{
    "redirect_url": "https://3ds2-sandbox.ckotech.co/interceptor/3ds_btjobzgahssujesvievv7kibze",
    "message": "pending"
}
```

**Response ( Success )**

```javascript
{
    "message": "successed",
    "transaction_id": "53333bf2-b9a0-4505-bc1c-7cc5d81ea7fb"
}
```

{% endtab %}
{% endtabs %}