NearPay API Documentation

https://docs.nearpay.io/sa/en
Admin
NearPay API documentation for integrating Tap to Pay on Phone payment processing into Android...
Tokens:155,283
Snippets:803
Trust Score:7.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Nearpay Web SDK

Source: https://docs.nearpay.io/sa/en/remote-integration/web-sdk

Install the Nearpay Web SDK package using npm.

```bash
npm i @nearpaydev/web-sdk

```

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

### Session Details Response Example

Source: https://docs.nearpay.io/sa/en/api-endpoints/merchants-api

This is an example of a successful response when retrieving session details. It includes comprehensive information about the session and its associated transaction.

```json
{
    "session": {
        "id": "dc17169c-060a-4547-b22f-6a5b3bafed2f",
        "status": "closed",
        "type": "purchase",
        "client_id": "a265c70b-a543-4817-ad70-1088f10e1ecd",
        "merchant_id": null,
        "amount": "10000",
        "expired_at": "1689501262198",
        "reference_id": null,
        "created_at": "2023-07-16T09:44:22.197Z",
        "updated_at": "2023-07-16T09:49:39.139Z",
        "transaction": {
            "id": "61391",
            "uuid": "652ab0e8-e6dc-4148-96de-b78a75317dbe",
            "amount_authorized": "10000",
            "transaction_currency_code": "682",
            "cardholder_verification_result": "00",
            "lat": "24.8037328",
            "lon": "46.6051575",
            "transaction_type": "00",
            "card_scheme_id": "P1",
            "system_trace_audit_number": "000063",
            "is_approved": true,
            "is_reversed": false,
            "is_reconcilied": true,
            "device_id": "7a80765d-9c52-4942-bebc-d55a3e7241c8",
            "user_id": "d40b80fe-2372-4317-823e-4430d3e22bcd",
            "merchant_id": "eaa09f58-4d53-49ca-a44f-0e27fcbb1ff5",
            "customer_reference_number": null,
            "pos_confirmed": true,
            "created_at": "2023-07-16T09:49:39.069Z",
            "updated_at": "2023-07-20T07:57:05.839Z",
            "receipts": [
                {
                    "id": "48e8b5fd-335d-4d28-95e6-063093292602",
                    "merchant": {
                        "id": "100000000000001",
                        "name": {
                            "arabic": "NearPay Merchant Arabic",
                            "english": "NearPay Merchant"
                        },
                        "address": {
                            "arabic": "4321",
                            "english": "KAFD"
                        },
                        "category_code": "0763"
                    },
                    "type": "purchase",
                    "start_date": "16/07/2023",
                    "start_time": "12:49:39",
                    "card_scheme_sponsor": "INMA",
                    "tid": "0200120000001200",
                    "system_trace_audit_number": "000063",
                    "pos_software_version_number": "1.0.0",
                    "retrieval_reference_number": "613910000000",
                    "card_scheme": {
                        "name": {
                            "english": "mada",
                            "arabic": "مدى"
                        },
                        "id": "P1"
                    },
                    "transaction_type": {
                        "name": {
                            "arabic": "شراء",
                            "english": "PURCHASE"
                        },
                        "id": "00"
                    },
                    "pan": "4323 28** **** 7404",
                    "card_expiration": "26/09",
                    "amount_authorized": {
                        "label": {
                            "arabic": "مبلغ الشراء",
                            "english": "PURCHASE AMOUNT"
                        },
                        "value": "100.00"
                    },
                    "amount_other": {
                        "label": {
                            "arabic": "مبلغ النقد",
                            "english": "NAQD AMOUNT"
                        },
                        "value": "0.00"
                    },
                    "currency": {
                        "arabic": "ر.س",
                        "english": "SAR"
                    },
                    "status_message": {
                        "arabic": "مقبولة",
                        "english": "Approved"
                    },
                    "is_approved": true,
                    "is_refunded": false,
                    "is_reversed": false,
                    "approval_code": {
                        "value": "713010",
                        "label": {
                            "arabic": "رمز الموافقة",
                            "english": "Approval Code"
                        }
                    },
                    "verification_method": {
                        "english": "NO VERIFICATION REQUIRED",
                        "arabic": "لا يتطلب التحقق"
                    },
                    "end_date": "16/07/2023",
                    "end_time": "12:49:39",
                    "receipt_line_one": {
                        "arabic": "",
                        "english": ""
                    },
                    "receipt_line_two": {
                        "arabic": "",
                        "english": ""
                    },
                    "thanks_message": {
                        "arabic": "شكرا لاستخدامكم مدى",
                        "english": "Thank you for using mada"
                    }
                }
            ]
        }
    }
}
```

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

### List Subscriptions Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a GET request to the /subscriptions endpoint to retrieve a list of all subscriptions.

```http
GET
/subscriptions
```

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

### Reconciliation Response Example

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a successful 200 OK response when retrieving reconciliation data. It includes POS totals, host totals, and terminal information.

```JSON
{
    "reconciliations": {
        "id": "04299703-aaaf-4220-b967-2417cb65d2f2",
        "stan": "111111",
        "pos_totals": [
            {
                "schema_acquirer": "GN",
                "schema_sponsor": "ANBB",
                "debit_count": 0,
                "debit_amount": 0,
                "credit_count": 0,
                "credit_amount": 0,
                "cash_back_amount": 0,
                "cash_advance_amount": 0,
                "authorization_count": 0
            },
            {
                "schema_acquirer": "P1",
                "schema_sponsor": "ANBB",
                "debit_count": 0,
                "debit_amount": 0,
                "credit_count": 0,
                "credit_amount": 0,
                "cash_back_amount": 0,
                "cash_advance_amount": 0,
                "authorization_count": 0
            }
        ],
        "host_totals": [
            {
                "schema_acquirer": "GN",
                "schema_sponsor": "ANBB",
                "debit_count": 0,
                "debit_amount": 0,
                "credit_count": 0,
                "credit_amount": 0,
                "cash_back_amount": 0,
                "cash_advance_amount": 0,
                "authorization_count": 0
            },
            {
                "schema_acquirer": "P1",
                "schema_sponsor": "ANBB",
                "debit_count": 0,
                "debit_amount": 0,
                "credit_count": 0,
                "credit_amount": 0,
                "cash_back_amount": 0,
                "cash_advance_amount": 0,
                "authorization_count": 0
            }
        ],
        "action_code": "500",
        "is_balanced": true,
        "request_id": "04299703-aaaf-4220-b967-2417cb65d2f2",
        "region": "jed",
        "created_at": "2025-09-25T11:27:00.492Z",
        "updated_at": "2025-09-25T11:27:00.695Z",
        "terminal": {
            "id": "e1e913d6-0558-44d6-9f34-ea2f125eeefa",
            "trsm": "FF1BCA",
            "card_acceptor_id": "111111111111",
            "card_acceptor_terminal_id": "1111111111",
            "acquirer_institution_identification_code": "111111",
            "created_at": "2024-06-30T11:22:31.787Z"
        },
        "receipt": {
            "id": "a88f40ad-3f35-445c-915c-dcb4621f77a4",
            "data": {
                "id": "a88f40ad-3f35-445c-915c-dcb4621f77a4",
                "date": "25/09/2025",
                "stan": "111111",
                "time": "14:27:00",
                "details": {
                    "total": {
                        "count": 0,
                        "label": {
                            "arabic": "المجموع",
                            "english": "Total"
                        },
                        "total": "0.00"
                    },
                    "refund": {
                        "count": 0,
                        "label": {
                            "arabic": "المستردة",
                            "english": "Refund"
                        },
                        "total": "0.00"
                    },
                    "purchase": {
                        "count": 0,
                        "label": {
                            "arabic": "الشراء",
                            "english": "Purchase"
                        },
                        "total": "0.00"
                    }
                },
                "qr_code": "https://api.nearpay.io/pos/ui/reconciliation_receipt/a88f40ad-3f35-445c-915c-dcb4621f77a4",
                "schemes": [
                    {
                        "pos": {
                            "debit": {
                                "count": 0,
                                "label": {
                                    "arabic": "مدين",
                                    "english": "Debit"
                                },
                                "total": "0.00"
                            },
                            "total": {
                                "count": 0,
                                "label": {
                                    "arabic": "المجموع",
                                    "english": "Total"
                                },
                                "total": "0.00"
                            },
                            "credit": {
                                "count": 0,
                                "label": {
                                    "arabic": "دائن",
                                    "english": "Credit"
                                },
                                "total": "0.00"
                            }
                        },
                        "host": {
                            "debit": {
                                "count": 0,
                                "label": {

```

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

### Create Subscription Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a POST request to the /subscriptions endpoint to create a new subscription. Requires 'tid' and 'plan_id'.

```json
{
  	"tid":	"85999666",
  	"plan_id":	"9803ca1b-69b8-447c-a774-db917be6b666"
}
```

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

### List Terminals Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/merchants-api

Example request to list all terminals associated with the merchant.

```http
GET
/terminals
```

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

### Create Purchase Transaction Job

Source: https://docs.nearpay.io/sa/en/remote-integration/web-sdk

Initiate a purchase transaction job and listen for its state changes. The transaction can then be started.

```javascript
// will generate a purchase transaction job with 1 SR
const transactionJob = await terminl.purchase({ amount: 100 });

transactionJob.stateListener((state) => console.log(state));

const result = await transactionJob.start();

```

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

### Verify Keystore with keytool

Source: https://docs.nearpay.io/sa/en/guides/generating-keystore-pem-certificate

Use this command to list the contents of an existing keystore file. It helps verify if you have the correct password and can access the keys within.

```bash
keytool -list -keystore /path/to/your.keystore

```

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

### List Messages Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a GET request to the /messages endpoint to retrieve a list of messages.

```http
GET
/messages
```

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

### Create Subscription Response (200 OK)

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a successful response after creating a subscription, including the new subscription's ID.

```json
{
  "message":	"Subscription	created	successfully",
  "subscription":	{
    "id":	"9803ca1b-69b8-447c-a774-db917be6b668"
  }
}
```

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

### Find Message Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a GET request to the /messages/{id} endpoint to retrieve a specific message by its ID.

```http
GET
/messages/{id}
```

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

### Configure NearPay SDK with Sandbox Environment

Source: https://docs.nearpay.io/sa/en/guides/faq

Initialize the NearPay SDK for use with the sandbox environment. Ensure you have the necessary context, JWT, and locale.

```kotlin
val nearpay = NearPay(this, jwt, Locale.getDefault(), Environments.SANDBOX)
```

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

### Get Transaction Failure Model

Source: https://docs.nearpay.io/sa/en/guides/terminal-sdk-models

Represents a general failure when attempting to get transaction information. Includes an error message.

```kotlin
@Serializable
sealed class GetIntentFailure {

    @Serializable
    data class GeneralFailure(
        @SerialName("message")
        val message: String
    ) : GetIntentFailure()
}
```

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

### List Subscriptions Response (200 OK)

Source: https://docs.nearpay.io/sa/en/api-endpoints/pos-api

Example of a successful response from the /subscriptions endpoint, containing a list of subscriptions and pagination details.

```json
{
  "subscriptions" :
    [
      {
        "id":	"49231a7c-92fb-4107-b13e-f95f754c9144",
				"tid":	"85210596",
				"platform_id":	"cac3f41d-ef6b-403f-b1be-85508313ca5d",
				"registered_by":	"client_sdk",
				"cancelled_by":	"client_sdk",
				"cancellation_reason":	null,
				"cancelled_at":	"2026-05-03T09:41:18.180Z",
				"created_at":	"2026-05-03T09:36:51.349Z",
				"updated_at":	"2026-05-03T09:41:18.181Z",
				"plan":	{
					"id":	"d5dc03a6-2b31-44db-bdd7-1b99d5b2dc8e",
					"name":	"Nearpay",
					"platform_id":	"cac3f41d-ef6b-403f-b1be-85508313ca5d",
					"client_id":	"4d0c0ffc-0677-436f-a080-d1ce7a0dadee",
					"gateway_type":	"private",
					"created_at":	"2024-12-19T09:45:58.529Z",
					"updated_at":	"2024-12-19T09:45:58.529Z"
				},
				"last_transaction":	null
			}
	  ],
	  "pages":	{
			"current":	1
	  }
}
```

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

### Disconnect Terminal Request

Source: https://docs.nearpay.io/sa/en/api-endpoints/merchants-api

Example request to disconnect a specific terminal.

```http
PUT
/terminals/{terminal_id}/disconnect
```

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

### Generate New Release Keystore with keytool

Source: https://docs.nearpay.io/sa/en/guides/generating-keystore-pem-certificate

This command generates a new Java KeyStore file for release signing. Ensure you securely store the generated keystore file and its passwords.

```bash
keytool -genkeypair -v \
    -keystore my-release.keystore \
    -alias my-key-alias \
    -keyalg RSA \
    -keysize 2048 \
    -validity 9125

```

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

### Refund Request Example

Source: https://docs.nearpay.io/sa/en/remote-integration/proxy-with-http

Send a POST request to the /refund endpoint with the transaction details to initiate a refund. Ensure all required fields like amount and original transaction UUID are provided.

```json
{
  "amount": 700,
  "original_transaction_uuid":"7038ae84-9b33-4585-814e-e2243bd3c3a5",
  "jobId":"8758f786-2376-4bc8-801c-16e0c96266c3",
  "customer_reference_number":"1234"
}
```

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

### Get Terminal Object

Source: https://docs.nearpay.io/sa/en/remote-integration/web-sdk

Obtain the Terminal object from the session to handle queries and transactions.

```javascript
const terminal = await session.getTerminal();

```

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

### Initialize TerminalSDK

Source: https://docs.nearpay.io/sa/en/guides/quick-start

Create a single instance of TerminalSDK, initializing it with essential configurations like activity context, environment, and country. Wrap initialization in a try-catch block to handle potential exceptions.

```kotlin
// initializing the terminalSDK may throw an exception, so wrap it in a try-catch block
try {
    val nearpay = TerminalSDK.Builder()
        .activity(this)  // Sets the activity context
        .environment(SdkEnvironment.SANDBOX)  // Choose SANDBOX or PRODUCTION or INTERNAL
        .googleCloudProjectNumber(12345678)  // Set Google Cloud project number
        .huaweiSafetyDetectApiKey("your_api_key")  // Set Huawei API key
        .uiDockPosition(UiDockPosition.BOTTOM_CENTER) // Optional: set the location of the Tap to Pay modal 
        .country(Country.SA)  // Set country SA, TR, USA, KEN , 
        .build()
    } catch (e: Throwable) {
        Timber.e("Error initializing TerminalSDK: $e")
    }


```

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

### Disconnect Terminal Response (200 OK)

Source: https://docs.nearpay.io/sa/en/api-endpoints/merchants-api

Example successful response after disconnecting a terminal.

```json
{
    "message": "Terminal disconnected successfully!"
}
```

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

### Build Signed APK with Gradle

Source: https://docs.nearpay.io/sa/en/guides/generating-keystore-pem-certificate

Use this command to assemble a signed APK for your Android application. The output APK will be located in the specified directory.

```bash
cd android
./gradlew assembleDebug

```

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

### Send Transaction Request

Source: https://docs.nearpay.io/sa/en/remote-integration/proxy-with-http

Example of a POST request to the /reverse endpoint with a transaction UUID.

```HTTP
POST
/reverse
```
{
  "transaction_uuid":"1b29d05f-d187-47cf-b684-3f21881a0d2a"
}

```
```

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

### Initiate Purchase Transaction with NearPay SDK

Source: https://docs.nearpay.io/sa/en/guides/quick-start

Use this snippet to initiate a purchase transaction. Ensure you manage unique intent UUIDs for each transaction. The `readCardListener` handles card reading events, and `sendTransactionListener` manages the transaction's success or failure.

```kotlin
var amount = 100
    var intentUuid = UUID.randomUUID().toString() // the intent UUID should be unique for each transaction and managed by the developer to communicate with the SDK
    var customerReferenceNumber = "" // [optional] any number you want to add as a refrence

    terminal.purchase(
        amount = amount,
        scheme = null, // eg.PaymentScheme.VISA, specifying this as null will allow all schemes to be accepted
        intentUUID = transactionUUID,
        customerReferenceNumber = customerReferenceNumber,
        readCardListener = object : ReadCardListener {
            override fun onReaderDismissed() {
                // Reader dismissed by user
                Log.d("ReadCard", "Reader dismissed by user")
            }

            override fun onReadCardSuccess() {
                // Card read successfully
                Log.d("ReadCard", "Card read successfully")
            }

            // Called when the card reading process fails - issues with the specific card or its interaction
            // Examples: card removed too quickly, unreadable card, wrong card orientation
            override fun onReadCardFailure(readCardFailure: ReadCardFailure) {
                // Handle card read failure
                Log.d("ReadCard", "Card read failure: $readCardFailure")
            }

            override fun onReaderDisplayed() {
                Log.d("ReaderCard", "Reader Displayed")
            }

            override fun onReaderClosed() {
                Log.d("ReaderCard", "Reading Closed")
            }

            override fun onReaderWaiting() {
                // Reader waiting for card
                Log.d("ReadCard", "Reader waiting for card")
            }

            override fun onReaderReading() {
                // Reading card in progress
                Log.d("ReadCard", "Reading card in progress")
            }

            override fun onReaderRetry() {
                // Reader retry needed
                Log.d("ReadCard", "Reader retry needed")
            }

            override fun onPinEntering() {
                // PIN entry in progress
                Log.d("ReadCard", "PIN entry in progress")
            }

            override fun onReaderFinished() {
                // Card read completed
                Log.d("ReadCard", "Card read completed")
            }
            override fun onReadingStarted() {
                // Card read started
                Log.d("ReadCard", "Card read started")
            }

            // Called when the card reader device itself encounters an error
            // Examples: hardware malfunction, connection issues, device not ready
            override fun onReaderError(error: String?) {
                // Handle reader error
                Log.d("ReadCard", "Reader error: $error")
            }
        },
        sendTransactionListener = object : SendTransactionListener {
            override fun onSendTransactionCompleted(purchaseResponse: PurchaseResponse) {
                // Handle completed transaction

                //PurchaseResponse will return all transaction with same intent id "transactionUUID"

                //purchaseResponse.status
                //will return the status of last transaction of the same intent id 
                //If the value is "declined", that means the transaction is not completed successfully 
                //If it is "approved", that means the transaction is completed successfully 

                //Also you can get the boolean status from last receipt using 
                //purchaseResponse.getLastReceipt().getMadaReceipt().isApproved
                //And the value will be true or false


                Log.d("Transaction", "Transaction completed: $purchaseResponse")
                // To get the approved receipt based on the country you can got it like :
                // purchaseResponse.getLastReceipt().getMadaReceipt() for Saudi Arabia
                // purchaseResponse.getLastReceipt().getEPXReceipt() for USA
                // purchaseResponse.getLastReceipt().getBKMReceipt() for Turkey
            }

            override fun onSendTransactionFailure(failure: SendTransactionFailure) {
                // Handle transaction failure
                Log.d("Transaction", "Transaction failure: $failure")
            }
        }
    )

```

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

### Get Intent by ID

Source: https://docs.nearpay.io/sa/en/api-endpoints/merchants-api

Retrieves the details of a specific payment intent using its unique ID.

```APIDOC
## GET /intents/{id}

### Description
Retrieves the details of a specific payment intent using its unique ID.

### Method
GET

### Endpoint
/intents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the intent.

### Response
#### Success Response (200)
- **details** (object) - Contains the details of the payment intent.
  - **intent_id** (string) - The unique identifier of the intent.
  - **reference_id** (string) - The reference ID for the intent.
  - **type** (string) - The type of the intent (e.g., 'purchase').
  - **status** (string) - The current status of the intent (e.g., 'approved').
  - **amount** (string) - The amount associated with the intent.
  - **pin_required** (boolean) - Indicates if a PIN is required.
  - **created_at** (string) - The timestamp when the intent was created.
  - **completed_at** (string) - The timestamp when the intent was completed.
  - **canceled_at** (string) - The timestamp when the intent was canceled (null if not canceled).
  - **group_receipts_url** (string) - URL to group receipts for the intent.
  - **transactions** (array) - A list of transactions associated with the intent.

#### Response Example
```json
{
    "details": {
        "intent_id": "9b3c8f2a-1d4e-4c7b-8a6f-2e5d9c0b1a3f",
        "reference_id": "INV-100245",
        "type": "purchase",
        "status": "approved",
        "amount": "800",
        "pin_required": false,
        "created_at": "2025-09-25T14:09:41.815Z",
        "completed_at": "2025-09-25T14:09:42.023Z",
        "canceled_at": null,
        "group_receipts_url": "https://api.nearpay.io/ui/group-receipts/9b3c8f2a-1d4e-4c7b-8a6f-2e5d9c0b1a3f",
        "transactions": [
            {
                "id": "dfe2ca83-3e7e-4221-a7cf-723cd1dabcdb",
                "status": "approved",
                "card": {
                    "pan": "1111 11** **** 1111",
                    "exp": "29/04"
                },
                "performance": [
                    {
                        "type": "api_start",
                        "time_stamp": 1758809381815
                    },
                    {
                        "type": "api_end",
                        "time_stamp": 1758809381978
                    }
                ],
                "pin_required": false,
                "reference_id": "INV-100245",
                "amount": "800",
                "amount_other": "0",
                "created_at": "2025-09-25T14:09:41.815Z",
                "events": [
                    {
                        "rrn": "527309006786",
                        "stan": "111111",
                        "type": "purchase",
                        "status": "approved",
                        "receipt": {
                            "standard": "nearpay",
                            "id": "48861c15-ac34-4f13-992f-e91b825d8d77",
                            "data": {
                                "id": "48861c15-ac34-4f13-992f-e91b825d8d77",
                                "tid": "1820066901300001",
                                "pan": "1111 11** **** 1111",
                                "type": "purchase",
                                "currency": {
                                    "arabic": "",
                                    "english": "SAR"
                                },
                                "merchant": {
                                    "id": "111111111111",
                                    "name": {
                                        "arabic": "نيرباي",
                                        "english": "Nearpay"
                                    },
                                    "category_code": "5812"
                                },
                                "card_scheme": {
                                    "id": "P1",
                                    "name": {
                                        "key": "mada",
                                        "arabic": "مدى",
                                        "english": "mada"
                                    }
                                },
                                "is_approved": true,
                                "approval_code": {
                                    "label": {
                                        "arabic": "رمز الموافقة",
                                        "english": "Approval Code"
                                    },
                                    "value": "474747"
                                },
                                "transaction_type": {
                                    "id": "00",
                                    "name": {
                                        "arabic": "شراء",
                                        "english": "PURCHASE"
                                    }
                                },
                                "transaction_uuid": "dfe2ca83-3e7e-4221-a7cf-723cd1dabcdb",
                                "amount_authorized": {
                                    "label": {
                                        "arabic": "مبلغ الشراء",
                                        "english": "PURCHASE AMOUNT"
                                    },
                                    "value": "8.00"
                                },
                                "system_trace_audit_number": "111111",
                                "retrieval_reference_number": "527309006786"
                            }
                        }
                    }
                ]
            }
        ]
    }
}
```
```

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

### Initiate Purchase Request

Source: https://docs.nearpay.io/sa/en/remote-integration/proxy-with-http

Send a POST request to the /purchase endpoint with the transaction details to initiate a purchase. Ensure the amount is in the smallest currency unit (e.g., cents for USD, halalas for SAR).

```json
{
  "amount": 700,
  "jobId": "8758f786-2376-4bc8-801c-16e0c96266c3",
  "customer_reference_number": "1234"
}
```

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

### Successful Transaction Response

Source: https://docs.nearpay.io/sa/en/remote-integration/proxy-with-http

Example of a successful transaction response, including detailed receipt information.

```JSON
{
  "command": 3,
  "status": 1,
  "transactionReceipts": [
      {
          "id": "883aae30-956e-4759-b883-a22fe074e8c0",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "01/07/2025",
          "start_time": "11:47:36",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000601",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556933000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "شراء",
                  "english": "PURCHASE"
              },
              "id": "00"
          },
          "pan": "4829 15** **** 0935",
          "card_expiration": "29/03",
          "amount_authorized": {
              "label": {
                  "arabic": "مبلغ الشراء",
                  "english": "PURCHASE AMOUNT"
              },
              "value": "7.00"
          },
          "amount_other": {
              "label": {
                  "arabic": "مبلغ النقد",
                  "english": "NAQD AMOUNT"
              },
              "value": "0.00"
          },
          "currency": {
              "arabic": "ر.س",
              "english": "SAR"
          },
          "status_message": {
              "arabic": "مقبولة",
              "english": "Approved"
          },
          "is_approved": true,
          "is_refunded": false,
          "is_reversed": false,
          "approval_code": {
              "label": {
                  "arabic": "رمز الموافقة",
                  "english": "Approval Code"
              },
              "value": "647331"
          },
          "verification_method": {
              "arabic": "تم التحقق من هوية حامل الجهاز ",
              "english": "DEVICE OWNER IDENTITY VERIFIED"
          },
          "end_date": "01/07/2025",
          "end_time": "11:47:36",
          "receipt_line_one": {
              "arabic": "",
              "english": ""
          },
          "receipt_line_two": {
              "arabic": "",
              "english": ""
          },
          "thanks_message": {
              "arabic": "شكرا لاستخدامكم مدى",
              "english": "Thank you for using mada"
          },
          "save_receipt_message": {
              "arabic": "يرجى الاحتفاظ بالفاتورة",
              "english": "please retain receipt"
          },
          "entry_mode": "CONTACTLESS",
          "action_code": "000",
          "application_identifier": "A0000000031010",
          "terminal_verification_result": "2480400080",
          "transaction_state_information": "0000",
          "cardholader_verfication_result": "1F0000",
          "cryptogram_information_data": "80",
          "application_cryptogram": "D6D3ECDEAD65A792",
          "kernel_id": "03",
          "payment_account_reference": "V0010013021088567550590138607",
          "pan_suffix": "",
          "created_at": "",
          "updated_at": "",
          "qr_code": "https://sandbox-api.nearpay.io/ui/receipt/883aae30-956e-4759-b883-a22fe074e8c0",
          "transaction_uuid": "1b29d05f-d187-47cf-b684-3f21881a0d2a",
          "customer_reference_number": null,
          "vas_data": null
      },
      {
          "id": "13a0236f-de51-4a1d-a8c9-43adad100293",
          "merchant": {
              "id": "100000000000001",
              "name": {
                  "arabic": "NearPay Merchant Arabic",
                  "english": "NearPay Merchant"
              },
              "address": {
                  "arabic": "4321",
                  "english": "KAFD"
              },
              "category_code": "0763"
          },
          "start_date": "01/07/2025",
          "start_time": "11:48:14",
          "card_scheme_sponsor": "INMA",
          "tid": "0211263600112636",
          "system_trace_audit_number": "000602",
          "pos_software_version_number": "1.0.0",
          "retrieval_reference_number": "556933000000",
          "card_scheme": {
              "name": {
                  "arabic": "فيزا",
                  "english": "Visa"
              },
              "id": "VC"
          },
          "transaction_type": {
              "name": {
                  "arabic": "عملية معكوسة",
                  "english": "REVERSAL"
              },
              "id": "00"
          }
      }
  ]
}
```

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

### Configure Gradle Signing (Groovy DSL)

Source: https://docs.nearpay.io/sa/en/guides/generating-keystore-pem-certificate

Configure signing settings for both debug and release builds using Groovy DSL in your `build.gradle` file. This includes specifying keystore paths, passwords, and aliases.

```groovy
android {
    signingConfigs {
        debug {
            // Android uses ~/.android/debug.keystore automatically.
            // Override here only if you need a custom debug keystore.
            storeFile     file("${System.getProperty("user.home")}/.android/debug.keystore")
            storePassword "android"
            keyAlias      "androiddebugkey"
            keyPassword   "android"
        }
        release {
            storeFile     file("my-release.keystore")   // relative to android/app/
            storePassword "your-keystore-password"
            keyAlias      "my-key-alias"
            keyPassword   "your-key-alias-password"
        }
    }
    buildTypes {
        debug {
            signingConfig signingConfigs.debug
        }
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
        }
    }
}

```

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

### High-Risk Transaction Blocking

Source: https://docs.nearpay.io/sa/en/radar-api/guide

Example of a transaction that triggers a block action due to high-risk indicators.

```APIDOC
## POST /payment/track/high-risk

### Description
Example of a transaction that triggers a block action due to high-risk indicators.

### Method
POST

### Endpoint
/payment/track/high-risk

### Request Body
- **event** (string) - Required - The type of event, e.g., "payment_requested".
- **event_timestamp** (number) - Required - Unix timestamp in milliseconds.
- **ip** (string) - Required - The IP address of the user.
- **device** (object) - Optional - Device details.
  - **id** (string) - Optional - Device ID.
  - **rooted** (boolean) - Optional - Indicates if the device is rooted.
  - **emulator** (boolean) - Optional - Indicates if the device is an emulator.
  - **hooked** (boolean) - Optional - Indicates if the device is hooked.
  - **malware** (boolean) - Optional - Indicates if malware is detected.
- **location** (object) - Optional - Location details.
  - **latitude** (number) - Optional - Latitude coordinate.
  - **longitude** (number) - Optional - Longitude coordinate.
  - **mocked** (boolean) - Optional - Indicates if the location is mocked.
- **request** (object) - Required - Transaction request details.
  - **amount** (number) - Required - Transaction amount.
  - **currency** (string) - Required - ISO 4217 currency code.
  - **channel** (string) - Required - Transaction channel (e.g., "e-commerce").
  - **card** (object) - Required - Card details.
    - **pan** (string) - Required - Primary Account Number (masked).
- **response** (object) - Required - Transaction response details.
  - **is_approved** (boolean) - Required - Indicates if the transaction was approved.
  - **response_code** (string) - Required - Response code.

### Response
#### Success Response (200)
- **action_id** (string) - Identifier for the action taken.
- **action** (string) - The action performed, e.g., "block".
- **state** (string) - The state of the transaction.

### Response Example
{
  "action_id": "unknown",
  "action": "block",
  "state": "unknown"
}
```

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

### Create USB POS Object

Source: https://docs.nearpay.io/sa/en/remote-integration/web-sdk

Initialize a USBPos object for connecting to a POS device via USB. This object should be instantiated once before creating a session.

```javascript
import { USBPos, Environments } from "@nearpaydev/web-sdk";

const pos = new USBPos({ environment: Environments.sandbox });

```
Tokens:
Raw