### Install NICEPAY PHP SDK with Composer

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Installs the NICEPAY PHP SDK using Composer, the dependency manager for PHP. This is the recommended method for adding the library to your project.

```bash
composer require nicepay/php-nicepay
```

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

### Install NICEPAY PHP via Composer

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Commands to install the NICEPAY PHP library into your project using Composer.

```json
{
  "require": {
        "nicepay/nicepay-php": "dev-master"
    },
  "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/nicepay-dev/php-nicepay"
        }
    ]
}
```

```bash
composer require nicepay/php-nicepay
```

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

### Manual Installation via GitHub Composer Configuration

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Provides the Composer configuration for manual installation of the NICEPAY PHP SDK directly from its GitHub repository. This is an alternative to using the Packagist repository.

```json
{
  "require": {
    "nicepay/nicepay-php": "dev-master"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/nicepay-dev/php-nicepay"
    }
  ]
}
```

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

### Check Environment Variable in PHP

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

This example demonstrates how to check if a specific environment variable is set, in this case, 'APP_ENV'. This is useful for conditionally executing code based on the application's environment, such as differentiating between local development and production.

```php
if (getenv('APP_ENV') === 'local') {
    echo "Running in local environment";
}
```

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

### SNAP API - Get Access Token

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Requests an access token from the SNAP API, which is required for authenticating subsequent API calls.

```APIDOC
## SNAP API Services - Get Access Token

Request an access token from the SNAP API for authenticating subsequent API calls. The token is required for all SNAP API operations.

### Method

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\Snap;
use Nicepay\data\model\AccessToken;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAInJe1G22R2fMchIE6BjtYRqyMj6lurP/zq6vy79WaiGKt0Fxs4q3Ab4ifmOXd97ynS5f0JRfIqakXDcV/e2rx9bFdsS2HORY7o5At7D5E3tkyNM9smI/7dk8d3O0fyeZyrmPMySghzgkR3oMEDW1TCD5q63Hh/oq0LKZ/4Jjcb9AgMBAAECgYA4Boz2NPsjaE+9uFECrohoR2NNFVe4Msr8/mIuoSWLuMJFDMxBmHvO+dBggNr6vEMeIy7zsF6LnT32PiImv0mFRY5fRD5iLAAlIdh8ux9NXDIHgyera/PW4nyMaz2uC67MRm7uhCTKfDAJK7LXqrNVDlIBFdweH5uzmrPBn77foQJBAMPCnCzR9vIfqbk7gQaA0hVnXL3qBQPMmHaeIk0BMAfXTVq37PUfryo+80XXgEP1mN/e7f10GDUPFiVw6Wfwz38CQQC0L+xoxraftGnwFcVN1cK/MwqGS+DYNXnddo7Hu3+RShUjCz5E5NzVWH5yHu0E0Zt3sdYD2t7u7HSr9wn96OeDAkEApzB6eb0JD1kDd3PeilNTGXyhtIE9rzT5sbT0zpeJEelL44LaGa/pxkblNm0K2v/ShMC8uY6Bbi9oVqnMbj04uQJAJDIgTmfkla5bPZRR/zG6nkf1jEa/0w7i/R7szaiXlqsIFfMTPimvRtgxBmG6ASbOETxTHpEgCWTMhyLoCe54WwJATmPDSXk4APUQNvX5rr5OSfGWEOo67cKBvp5Wst+tpvc6AbIJeiRFlKF4fXYTb6HtiuulgwQNePuvlzlt2Q8hqQ==')
    ->setClientSecret('33F49GnCMS1mFYlGXisbUDzVf2ATWCl9k3R++d5hDd3Frmuos/XLx8XhXpe+LDYAbpGKZYSwtlyyLOtS/8aD7A==')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("uniqueId" . time())
    ->setTimestamp($timestamp)
    ->build();

$tokenBody = AccessToken::builder()
    ->setGrantType('client_credentials')
    ->setAdditionalInfo([])
    ->build();

$snap = new Snap($config);

try {
    $response = $snap->requestSnapAccessToken($tokenBody);
    $accessToken = $response->getAccessToken();
    echo "Access Token: " . $accessToken;
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}
```
```

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

### Cancel or Refund Transaction (V2 API) - PHP

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

This example shows how to cancel or refund a transaction using the Nicepay V2 API. It requires the transaction ID, amount, and a cancel type (e.g., full cancel). The API call returns a result code and message indicating the success or failure of the operation.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\v2\V2VAService;
use Nicepay\data\model\Cancel;
use Nicepay\utils\Helper;

$timestamp = Helper::getFormattedTimestampV2();
$iMid = "IONPAYTEST";
$merchantKey = "YOUR_MERCHANT_KEY";
$tXid = "IONPAYTEST02202410010000000001";
$amount = "10000";

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->build();

$parameter = Cancel::builder()
    ->setTimeStamp($timestamp)
    ->setTXid($tXid)
    ->setIMid($iMid)
    ->setPayMethod("02")
    ->setCancelType("1") // 1 = Full cancel
    ->setAmt($amount)
    ->setMerchantToken($timestamp, $iMid, $tXid, $amount, $merchantKey)
    ->build();

$v2VaService = new V2VAService($config);
$response = $v2VaService->cancel($parameter);

echo "Cancel Status: " . $response->getResultCd();
echo "Message: " . $response->getResultMsg();

```

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

### Initialize NICEPAY Client Configuration in PHP

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Demonstrates how to initialize the NICEPAY client configuration using a fluent builder pattern. It includes setting production/sandbox mode, API keys, partner ID, and retry mechanisms.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\utils\Helper;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false) // Set to true for production
    ->setPrivateKey('YOUR_PRIVATE_KEY_STRING')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('YOUR_PARTNER_ID')
    ->setExternalID("uniqueExternalId123")
    ->setTimestamp($timestamp)
    ->isRetryFlag(true) // Enable automatic retries
    ->setRetryCount(3) // Number of retry attempts
    ->build();

```

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

### Client Initialization

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Configuring the NICEPAY client with credentials and environment settings.

```APIDOC
## Client Initialization

### Description
Initialize the NICEPAY configuration object required for all API service calls.

### Method
N/A (Builder Pattern)

### Parameters
- **isProduction** (boolean) - Required - Set to true for production, false for sandbox.
- **privateKey** (string) - Required - Your merchant private key.
- **clientSecret** (string) - Required - Your merchant client secret.
- **partnerId** (string) - Required - Your unique partner ID.

### Request Example
```php
$config = NICEPay::builder()
            ->setIsProduction(false)
            ->setPrivateKey('YOUR_PRIVATE_KEY')
            ->setClientSecret('YOUR_CLIENT_SECRET')
            ->setPartnerId('YOUR_PARTNER_ID')
            ->build();
```
```

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

### Initialize NICEPAY Client Configuration

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Configures the NICEPAY client with credentials, production status, and retry settings.

```php
$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
            ->setIsProduction(false)
            ->setPrivateKey('MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAInJe1G22R2fMchIE6BjtYRqyMj6lurP/zq6vy79WaiGKt0Fxs4q3Ab4ifmOXd97ynS5f0JRfIqakXDcV/e2rx9bFdsS2HORY7o5At7D5E3tkyNM9smI/7dk8d3O0fyeZyrmPMySghzgkR3oMEDW1TCD5q63Hh/oq0LKZ/4Jjcb9AgMBAAECgYA4Boz2NPsjaE+9uFECrohoR2NNFVe4Msr8/mIuoSWLuMJFDMxBmHvO+dBggNr6vEMeIy7zsF6LnT32PiImv0mFRY5fRD5iLAAlIdh8ux9NXDIHgyera/PW4nyMaz2uC67MRm7uhCTKfDAJK7LXqrNVDlIBFdweH5uzmrPBn77foQJBAMPCnCzR9vIfqbk7gQaA0hVnXL3qBQPMmHaeIk0BMAfXTVq37PUfryo+80XXgEP1mN/e7f10GDUPFiVw6Wfwz38CQQC0L+xoxraftGnwFcVN1cK/MwqGS+DYNXnddo7Hu3+RShUjCz5E5NzVWH5yHu0E0Zt3sdYD2t7u7HSr9wn96OeDAkEApzB6eb0JD1kDd3PeilNTGXyhtIE9rzT5sbT0zpeJEelL44LaGa/pxkblNm0K2v/ShMC8uY6Bbi9oVqnMbj04uQJAJDIgTmfkla5bPZRR/zG6nkf1jEa/0w7i/R7szaiXlqsIFfMTPimvRtgxBmG6ASbOETxTHpEgCWTMhyLoCe54WwJATmPDSXk4APUQNvX5rr5OSfGWEOo67cKBvp5Wst+tpvc6AbIJeiRFlKF4fXYTb6HtiuulgwQNePuvlzlt2Q8hqQ==')
            ->setClientSecret('33F49GnCMS1mFYlGXisbUDzVf2ATWCl9k3R++d5hDd3Frmuos/XLx8XhXpe+LDYAbpGKZYSwtlyyLOtS/8aD7A==')
            ->setPartnerId('IONPAYTEST')
            ->setExternalID("randUniqueId1234")
            ->setTimestamp($timestamp)
            ->isRetryFlag(true)
            ->setRetryCount(4)
            ->build();
```

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

### Initiate E-Wallet Payment

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

This snippet demonstrates how to initialize the Nicepay configuration and execute an E-Wallet payment request. It requires setting up merchant credentials and transaction parameters such as amount, currency, and callback URLs.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\SnapEwalletService;
use Nicepay\data\model\Ewallet;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('YOUR_PRIVATE_KEY')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("ewallet" . time())
    ->setTimestamp($timestamp)
    ->build();

$parameter = Ewallet::builder()
    ->partnerReferenceNo("ordNo" . time())
    ->merchantId("IONPAYTEST")
    ->subMerchantId("")
    ->externalStoreId("")
    ->validUpTo("2024-12-31T23:59:59+07:00")
    ->pointOfInitiation("app")
    ->amount("10000.00", "IDR")
    ->urlParam([
        ["https://yoursite.com/success", "PAY_RETURN", "N"],
        ["https://yoursite.com/notification", "PAY_NOTIFY", "N"]
    ])
    ->addInfoMitraCd("OVOE")
    ->addInfoGoodsNm("Product Purchase")
    ->addInfoBillingNm("John Doe")
    ->addInfoBillingPhone("08123456789")
    ->addInfoCallBackUrl("https://yoursite.com/callback")
    ->addInfoDbProcessUrl("https://yoursite.com/notification")
    ->build();

$accessToken = "YOUR_ACCESS_TOKEN";
$ewalletService = new SnapEwalletService($config);

try {
    $response = $ewalletService->paymentEwallet($parameter, $accessToken);
    echo "Payment URL: " . $response->getWebRedirectUrl();
    echo "Reference No: " . $response->getReferenceNo();
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}
```

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

### Client Configuration

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Initializes the NICEPAY client with merchant credentials, supporting sandbox/production environments and retry mechanisms.

```APIDOC
## Client Configuration

Initialize the NICEPAY client configuration with your merchant credentials obtained from the NICEPAY Dashboard. The configuration supports sandbox/production switching, retry mechanisms, and authentication credentials.

### Method

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\utils\Helper;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false) // Set to true for production
    ->setPrivateKey('YOUR_PRIVATE_KEY_STRING')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('YOUR_PARTNER_ID')
    ->setExternalID("uniqueExternalId123")
    ->setTimestamp($timestamp)
    ->isRetryFlag(true) // Enable automatic retries
    ->setRetryCount(3) // Number of retry attempts
    ->build();
```
```

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

### Generate Virtual Account (SNAP API)

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Demonstrates how to build a Virtual Account request parameter using the SNAP API builder and execute the registration via SnapVAService. Requires a valid access token and configuration object.

```php
$parameter = VirtualAccount::builder()
            ->setPartnerServiceId("")
            ->setCustomerNo("")
            ->setVirtualAccountNo("")
            ->setVirtualAccountName("Nicepay PHP Test")
            ->setTrxId("ordNo" . $timestamp)
            ->setTotalAmount('10000.00', 'IDR')
            ->setAdditionalInfo([
                'bankCd' => 'BMRI',
                'goodsNm' => 'Test',
                'dbProcessUrl' => 'https://nicepay.co.id/',
            ])
            ->build();

        $accessToken = "";
        $snapVAService = new SnapVAService($config);

        try {
        $response = $snapVAService->generateVA($parameter, $accessToken);
        } catch (NicepayError $e) {
            $this->fail("Exception thrown: " . $e->getMessage());
        }
```

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

### Generate Virtual Account (V2 Non-Snap)

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Demonstrates the legacy V2 Virtual Account registration process. It involves configuring the NICEPay environment, building the request with specific billing and transaction details, and calling the V2VAService.

```php
$timestamp = Helper::getFormattedTimestampV2();
        
        $config = NICEPay::builder()
            ->setIsProduction(false)
            ->setRetryFlag(true)
            ->setRetryCount(4)
            ->build();

        $reffNo = "ordNo".$timestamp;
        $amount = "100";
        $virtualAccountBuilder = VirtualAccount::builder();

        $parameter = $virtualAccountBuilder
            ->setTimeStamp($timestamp)
            ->setIMid("IONPAYTEST")
            ->setPayMethod("02")
            ->setCurrency("IDR")
            ->setBankCd("CENA")
            ->setAmt("100")
            ->setReferenceNo($reffNo)
            ->setMerchantToken($timestamp, "IONPAYTEST", $reffNo, $amount, "")
            ->setVacctValidDt("20251004")
            ->setVacctValidTm("101010")
            ->setMerFixAcctId("")
            ->setDbProcessUrl("https://webhook.site/7c2d47f6-557b-4b85-b91a-ad3b6182b10c")
            ->setGoodsNm("Test VA V2 PHP")
            ->setCartData("{}")
            ->setBillingNm("Nicepay php native")
            ->setBillingPhone("081534567890")
            ->setBillingEmail("nicepay@example.com")
            ->setBillingAddr("Jln. Raya Kasablanka Kav.88")
            ->setBillingCity("South Jakarta")
            ->setBillingState("DKI Jakarta")
            ->setBillingPostCd("15119")
            ->setBillingCountry("Indonesia")
            ->build();
                
        $v2VaService = new V2VAService($config);

        try {
        $response = $v2VaService->registration($parameter);

        } catch (NicepayError $e) {
            $this->assertTrue(true, "Exmessage: ception thrown: " . $e->getMessage());
        }
```

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

### Load Environment Variables in PHP

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

This code snippet shows how to load environment variables from a .env file at the beginning of your PHP project. It utilizes the EnvLoader class from the Nicepay library. This is crucial for managing configuration settings in local development.

```php
use Nicepay\utils\EnvLoader;

EnvLoader::load(__DIR__ . '/.env');
```

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

### Process V2 Card Payment with 3DS Authentication

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

This snippet demonstrates the two-step V2 card payment process: registering the transaction to obtain a tXid, and executing the payment. It includes 3DS authentication handling by rendering the returned HTML response.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\v2\V2CardService;
use Nicepay\data\model\Card;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedTimestampV2();
$iMid = "IONPAYTEST";
$merchantKey = "YOUR_MERCHANT_KEY";
$referenceNo = "ordNo" . $timestamp;
$amount = "10000";

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->build();

$registParam = Card::builder()
    ->timeStamp($timestamp)
    ->iMid($iMid)
    ->payMethod("01")
    ->currency("IDR")
    ->amt($amount)
    ->referenceNo($referenceNo)
    ->merchantToken($timestamp, $iMid, $referenceNo, $amount, $merchantKey)
    ->goodsNm("Product Purchase")
    ->billingNm("John Doe")
    ->billingPhone("08123456789")
    ->billingEmail("john@example.com")
    ->billingAddr("Jl. Test No. 123")
    ->billingCity("Jakarta")
    ->billingState("DKI Jakarta")
    ->billingPostCd("12345")
    ->billingCountry("Indonesia")
    ->dbProcessUrl("https://yoursite.com/notification")
    ->callBackUrl("https://yoursite.com/callback")
    ->instmntType("1")
    ->instmntMon("1")
    ->recurrOpt("0")
    ->build();

$cardService = new V2CardService($config);

try {
    $regResponse = $cardService->registration($registParam);
    $tXid = $regResponse->getTXid();

    $paymentParam = Card::builder()
        ->timeStamp($timestamp)
        ->tXid($tXid)
        ->referenceNo($referenceNo)
        ->merchantToken($timestamp, $iMid, $referenceNo, $amount, $merchantKey)
        ->cardNo("5123450000000008")
        ->cardExpYymm("2908")
        ->cardCvv("100")
        ->cardHolderNm("John Doe")
        ->callBackUrl("https://yoursite.com/callback")
        ->build();

    $paymentResponse = $cardService->payment($paymentParam);
    echo $paymentResponse;
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}
```

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

### Request SNAP API Access Token in PHP

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Shows how to request an access token from the NICEPAY SNAP API using the configured client. This token is necessary for authenticating subsequent API calls to the SNAP service.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\Snap;
use Nicepay\data\model\AccessToken;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAInJe1G22R2fMchIE6BjtYRqyMj6lurP/zq6vy79WaiGKt0Fxs4q3Ab4ifmOXd97ynS5f0JRfIqakXDcV/e2rx9bFdsS2HORY7o5At7D5E3tkyNM9smI/7dk8d3O0fyeZyrmPMySghzgkR3oMEDW1TCD5q63Hh/oq0LKZ/4Jjcb9AgMBAAECgYA4Boz2NPsjaE+9uFECrohoR2NNFVe4Msr8/mIuoSWLuMJFDMxBmHvO+dBggNr6vEMeIy7zsF6LnT32PiImv0mFRY5fRD5iLAAlIdh8ux9NXDIHgyera/PW4nyMaz2uC67MRm7uhCTKfDAJK7LXqrNVDlIBFdweH5uzmrPBn77foQJBAMPCnCzR9vIfqbk7gQaA0hVnXL3qBQPMmHaeIk0BMAfXTVq37PUfryo+80XXgEP1mN/e7f10GDUPFiVw6Wfwz38CQQC0L+xoxraftGnwFcVN1cK/MwqGS+DYNXnddo7Hu3+RShUjCz5E5NzVWH5yHu0E0Zt3sdYD2t7u7HSr9wn96OeDAkEApzB6eb0JD1kDd3PeilNTGXyhtIE9rzT5sbT0zpeJEelL44LaGa/pxkblNm0K2v/ShMC8uY6Bbi9oVqnMbj04uQJAJDIgTmfkla5bPZRR/zG6nkf1jEa/0w7i/R7szaiXlqsIFfMTPimvRtgxBmG6ASbOETxTHpEgCWTMhyLoCe54WwJATmPDSXk4APUQNvX5rr5OSfGWEOo67cKBvp5Wst+tpvc6AbIJeiRFlKF4fXYTb6HtiuulgwQNePuvlzlt2Q8hqQ==')
    ->setClientSecret('33F49GnCMS1mFYlGXisbUDzVf2ATWCl9k3R++d5hDd3Frmuos/XLx8XhXpe+LDYAbpGKZYSwtlyyLOtS/8aD7A==')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("uniqueId" . time())
    ->setTimestamp($timestamp)
    ->build();

$tokenBody = AccessToken::builder()
    ->setGrantType('client_credentials')
    ->setAdditionalInfo([])
    ->build();

$snap = new Snap($config);

try {
    $response = $snap->requestSnapAccessToken($tokenBody);
    $accessToken = $response->getAccessToken();
    echo "Access Token: " . $accessToken;
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}

```

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

### POST /snap/v1/generate-va

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Generates a Virtual Account using the Nicepay SNAP service.

```APIDOC
## POST /snap/v1/generate-va

### Description
Generates a new Virtual Account payment request using the SNAP protocol.

### Method
POST

### Endpoint
/snap/v1/generate-va

### Parameters
#### Request Body
- **partnerServiceId** (string) - Required - The service ID assigned to the partner.
- **customerNo** (string) - Required - Unique customer identifier.
- **virtualAccountNo** (string) - Required - Desired VA number.
- **virtualAccountName** (string) - Required - Name associated with the VA.
- **trxId** (string) - Required - Unique transaction ID.
- **totalAmount** (object) - Required - Amount and currency code.
- **additionalInfo** (object) - Optional - Extra data including bank code and process URL.

### Request Example
{
  "partnerServiceId": "",
  "customerNo": "",
  "virtualAccountNo": "",
  "virtualAccountName": "Nicepay PHP Test",
  "trxId": "ordNo123456789",
  "totalAmount": {"value": "10000.00", "currency": "IDR"}
}

### Response
#### Success Response (200)
- **responseCode** (string) - Success status code.
- **virtualAccountNo** (string) - The generated VA number.
```

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

### POST /snap/v1/ewallet/payment

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Initiates an e-wallet payment transaction for various providers.

```APIDOC
## POST /snap/v1/ewallet/payment

### Description
Initiates a new e-wallet payment transaction. This endpoint generates a redirect URL for the customer to complete the payment.

### Method
POST

### Endpoint
/snap/v1/ewallet/payment

### Parameters
#### Request Body
- **partnerReferenceNo** (string) - Required - Unique order number generated by the merchant.
- **amount** (object) - Required - Transaction amount and currency (e.g., 10000.00, IDR).
- **mitraCd** (string) - Required - E-wallet provider code (e.g., OVOE).
- **urlParam** (array) - Required - Callback and notification URLs.

### Request Example
{
  "partnerReferenceNo": "ordNo12345",
  "amount": {"value": "10000.00", "currency": "IDR"},
  "mitraCd": "OVOE"
}

### Response
#### Success Response (200)
- **webRedirectUrl** (string) - URL to redirect the user for payment completion.
- **referenceNo** (string) - Unique Nicepay reference number.

#### Response Example
{
  "webRedirectUrl": "https://nicepay.co.id/redirect/example",
  "referenceNo": "IONPAYTEST052024..."
}
```

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

### Generate Virtual Account via Nicepay PHP SDK

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Creates a new virtual account for bank transfers. Requires configuration with API credentials and a valid access token to process the request.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\SnapVAService;
use Nicepay\data\model\VirtualAccount;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('YOUR_PRIVATE_KEY')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("ordNo" . time())
    ->setTimestamp($timestamp)
    ->build();

$parameter = VirtualAccount::builder()
    ->setPartnerServiceId("")
    ->setCustomerNo("")
    ->setVirtualAccountNo("")
    ->setVirtualAccountName("John Doe")
    ->setTrxId("ordNo" . $timestamp)
    ->setTotalAmount('10000.00', 'IDR')
    ->setAdditionalInfo([
        'bankCd' => 'BMRI',
        'goodsNm' => 'Product Purchase',
        'dbProcessUrl' => 'https://yoursite.com/notification',
    ])
    ->build();

$accessToken = "YOUR_ACCESS_TOKEN";
$snapVAService = new SnapVAService($config);

try {
    $response = $snapVAService->generateVA($parameter, $accessToken);
    echo "VA Number: " . $response->getVirtualAccountNo();
    echo "Response Code: " . $response->getResponseCode();
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}
```

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

### PHP NICEPay Card Payment Initiation

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Initiates a payment card transaction using the NICEPay PHP SDK. This involves configuring the SDK, building payment parameters with card details, and executing the payment service. The response may contain HTML for 3DS authentication.

```php
$config = NICEPay::builder()
    ->setIsProduction(false) // Dev
    ->build();

$parameter = Card::builder()
->timeStamp($timestamp)
->iMid($iMid)
->tXid($tXid) // tXid transaction to do payment process
->referenceNo($referenceNo)
->merchantToken($timestamp, $iMid, $referenceNo, $amount, $merchantKey)
->cardNo(TestConst::$CARD_NO) // CARD DATA
->cardExpYymm(TestConst::$CARD_EXP_YYMM) // CARD DATA 
->cardCvv(TestConst::$CARD_CVV) // CARD DATA
->cardHolderNm("Nicepay test")
->callBackUrl("https://x.com")
->build();

try {

    $cardService = new V2CardService($config);
    $response = $cardService->payment($parameter);

} catch (Exception $exception) {
    
}
```

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

### Verify SHA256 RSA Signature in PHP

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

This snippet demonstrates how to verify a SHA256 RSA signature using the Nicepay Helper class. It takes the data string, public key, and signature string as input and returns a boolean indicating whether the signature is valid. Ensure the Helper class is imported.

```php
use Nicepay\utils\Helper;

$signatureString = "VoxMPjbcV9pro4YyHGQgoRj4rDVJgYk2Ecxn+95B90w47Wnabtco35BfhGpR7a5RukUNnAdeOEBNczSFk4B9uYyu3jc+ceX+Dvz5OYSgSnw5CiMHtGiVnTAqCM/yHZ2MRpIEqekBc4BWMLVtexSWp0YEJjLyo9dZPrSkSbyLVuD7jkUbvmEpVdvK0uK15xb8jueCcDA6LYVXHkq/OMggS1/5mrLNriBhCGLuR7M7hBUJbhpOXSJJEy7XyfItTBA+3MRC2FLcvUpMDrn/wz1uH1+b9A6FP7mG0bRSBOm2BTLyf+xJR5+cdd88RhF70tNQdQxhqr4okVo3IFqlCz2FFg==";
$dataString = "TNICEVA023|2024-08-19T17:12:40+07:00";
$publicKeyString = TestConst::$PUBLIC_KEY;

$isVerify = Helper::verifySHA256RSA($dataString, $publicKeyString, $signatureString);
```

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

### Utilize Helper Functions for API Operations

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

The Helper class provides essential utilities for timestamp generation, merchant token creation, RSA signature verification, and key formatting. These functions are critical for maintaining security and compliance across API requests and webhook callbacks.

```php
<?php
use Nicepay\utils\Helper;

$snapTimestamp = Helper::getFormattedDate();
$v2Timestamp = Helper::getFormattedTimestampV2();

$tokenString = $timestamp . $iMid . $referenceNo . $amount . $merchantKey;
$merchantToken = Helper::generateMerchantToken($tokenString);

$futureTimestamp = Helper::getCustomTimeStamp('YmdHis', 30);

$signatureString = "RECEIVED_SIGNATURE";
$dataString = "PARTNER_ID|TIMESTAMP";
$publicKeyString = "YOUR_PUBLIC_KEY";

$isValid = Helper::verifySHA256RSA($dataString, $publicKeyString, $signatureString);
if ($isValid) {
    echo "Signature is valid";
} else {
    echo "Invalid signature";
}

$privateKeyPEM = Helper::getKey("YOUR_PRIVATE_KEY_BASE64");
```

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

### Manage Payout Status (Approve, Cancel, Reject)

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Handles lifecycle management for pending payout requests. This snippet demonstrates how to approve, cancel, or reject a transaction using the original reference numbers.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\SnapPayoutService;
use Nicepay\Data\Model\Payout;
use Nicepay\data\model\Cancel;
use Nicepay\utils\Helper;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('YOUR_PRIVATE_KEY')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("payoutAction" . time())
    ->setTimestamp($timestamp)
    ->build();

$accessToken = "YOUR_ACCESS_TOKEN";
$payoutService = new SnapPayoutService($config);

$approveParam = Payout::builder()
    ->merchantId("IONPAYTEST")
    ->originalReferenceNo("IONPAYTEST08202410010000000001")
    ->originalPartnerReferenceNo("payout20241001")
    ->build();

$approveResponse = $payoutService->approve($approveParam, $accessToken);
echo "Approve Status: " . $approveResponse->getResponseCode();

$cancelParam = Cancel::builder()
    ->setMerchantId("IONPAYTEST")
    ->setOriginalReferenceNo("IONPAYTEST08202410010000000001")
    ->setOriginalPartnerReferenceNo("payout20241001")
    ->build();

$cancelResponse = $payoutService->cancel($cancelParam, $accessToken);
echo "Cancel Status: " . $cancelResponse->getResponseCode();

$rejectResponse = $payoutService->reject($cancelParam, $accessToken);
echo "Reject Status: " . $rejectResponse->getResponseCode();
```

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

### POST /v2/generate-va

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Generates a Virtual Account using the Nicepay V2 (Non-Snap) service.

```APIDOC
## POST /v2/generate-va

### Description
Registers a Virtual Account using the legacy Nicepay V2 API.

### Method
POST

### Endpoint
/v2/generate-va

### Parameters
#### Request Body
- **timeStamp** (string) - Required - ISO formatted timestamp.
- **iMid** (string) - Required - Merchant ID.
- **payMethod** (string) - Required - Payment method code.
- **amt** (string) - Required - Transaction amount.
- **referenceNo** (string) - Required - Unique merchant reference number.
- **merchantToken** (string) - Required - Security token generated from transaction details.

### Request Example
{
  "iMid": "IONPAYTEST",
  "payMethod": "02",
  "amt": "100",
  "referenceNo": "ordNo123456789",
  "goodsNm": "Test VA V2 PHP"
}

### Response
#### Success Response (200)
- **resultCd** (string) - Result code indicating success.
- **resultMsg** (string) - Result message.
```

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

### POST /snap/v1/ewallet/inquiry

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Checks the current status of an existing e-wallet transaction.

```APIDOC
## POST /snap/v1/ewallet/inquiry

### Description
Retrieves the current status of a transaction using the original reference numbers.

### Method
POST

### Endpoint
/snap/v1/ewallet/inquiry

### Parameters
#### Request Body
- **originalPartnerReferenceNo** (string) - Required - The original order number.
- **originalReferenceNo** (string) - Required - The original Nicepay reference number.

### Request Example
{
  "originalPartnerReferenceNo": "ordNo20241001120000",
  "originalReferenceNo": "IONPAYTEST05202410010000000001"
}

### Response
#### Success Response (200)
- **latestTransactionStatus** (string) - The current status of the transaction.

#### Response Example
{
  "latestTransactionStatus": "00"
}
```

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

### POST /snap/v1/ewallet/refund

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Processes a refund for a previously successful e-wallet transaction.

```APIDOC
## POST /snap/v1/ewallet/refund

### Description
Processes a full or partial refund for a specific transaction.

### Method
POST

### Endpoint
/snap/v1/ewallet/refund

### Parameters
#### Request Body
- **originalPartnerReferenceNo** (string) - Required - Original order number.
- **refundAmount** (object) - Required - Amount to be refunded.
- **refundType** (string) - Required - 1 for full refund, 2 for partial.

### Request Example
{
  "originalPartnerReferenceNo": "ordNo20241001120000",
  "refundAmount": {"value": "5000.00", "currency": "IDR"},
  "refundType": "1"
}

### Response
#### Success Response (200)
- **responseCode** (string) - Status code indicating result of the refund request.

#### Response Example
{
  "responseCode": "2001100"
}
```

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

### POST /snap/v1/access-token

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Retrieves an access token required for authenticating subsequent requests to the NICEPAY SNAP API.

```APIDOC
## POST /snap/v1/access-token

### Description
Retrieves an access token using client credentials to authorize API requests.

### Method
POST

### Endpoint
/snap/v1/access-token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be 'client_credentials'
- **additional_info** (array) - Optional - Additional metadata for the request

### Request Example
{
  "grant_type": "client_credentials",
  "additional_info": []
}

### Response
#### Success Response (200)
- **access_token** (string) - The generated OAuth2 access token

#### Response Example
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Register SNAP Payout Request

Source: https://context7.com/nicepay-dev/php-nicepay/llms.txt

Registers a new payout disbursement request to a beneficiary bank account. It requires a configured Nicepay instance and a Payout model populated with beneficiary and transaction details.

```php
<?php
use Nicepay\common\NICEPay;
use Nicepay\service\snap\SnapPayoutService;
use Nicepay\Data\Model\Payout;
use Nicepay\utils\Helper;
use Nicepay\common\NicepayError;

$timestamp = Helper::getFormattedDate();

$config = NICEPay::builder()
    ->setIsProduction(false)
    ->setPrivateKey('YOUR_PRIVATE_KEY')
    ->setClientSecret('YOUR_CLIENT_SECRET')
    ->setPartnerId('IONPAYTEST')
    ->setExternalID("payout" . time())
    ->setTimestamp($timestamp)
    ->build();

$parameter = Payout::builder()
    ->merchantId("IONPAYTEST")
    ->beneficiaryAccountNo("1234567890")
    ->beneficiaryName("John Doe")
    ->beneficiaryPhone("08123456789")
    ->beneficiaryCustomerResidence("1")
    ->beneficiaryCustomerType("1")
    ->beneficiaryPostalCode("12345")
    ->payoutMethod("0")
    ->beneficiaryBankCode("BNIA")
    ->amount("100000.00", "IDR")
    ->partnerReferenceNo("payout" . time())
    ->description("Disbursement payment")
    ->deliveryName("John Doe")
    ->deliveryId("1234567890")
    ->reservedDt("")
    ->reservedTm("")
    ->build();

$accessToken = "YOUR_ACCESS_TOKEN";
$payoutService = new SnapPayoutService($config);

try {
    $response = $payoutService->registration($parameter, $accessToken);
    echo "Payout Reference: " . $response->getReferenceNo();
    echo "Status: " . $response->getResponseCode();
} catch (NicepayError $e) {
    echo "Error: " . $e->getMessage();
}
```

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

### Request SNAP Access Token

Source: https://github.com/nicepay-dev/php-nicepay/blob/master/README.md

Retrieves an access token using the SNAP API client.

```php
$tokenBody = AccessToken::builder()
            ->setGrantType('client_credentials')
            ->setAdditionalInfo([])
            ->build();

        $snap = new Snap($config);

        try {
            $response = $snap->requestSnapAccessToken($tokenBody);
            $accessToken = $response->getAccessToken();  
        } catch (NicepayError $e) {
            $this->fail("Exception thrown: " . $e->getMessage());
        }
```