# 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.nearvault.com/checkout.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.