# Integration Guide

> 💡 **Tip**: Please follow the checklist below to ensure you have completed the full payment integration with PayKKa.


## Setting Up Your Sandbox Environment

### Create Sandbox Account

- Visit [Sandbox Login Page](https://portal-sandbox.paykka.com/login)
- Follow the prompts to complete account login or registration


### Complete Identity Verification and Merchant Onboarding

- Click on **KYC** -> **Identity Verification**, fill in the content and submit. No review is required to proceed to the next step **Add Merchant**.
- Go to the merchant list page, click **Add Merchant**
- Contact integration personnel for quick review and activation of required payment methods
- Click the **avatar** in the top right -> **Profile** -> **Security Settings** -> [**Payment Password**](https://portal-sandbox.paykka.com/user/payment-password?type=set) (Used for **refund** verification, please keep it safe)


### Configure Transaction Keys

> 💡 **Hint**: No configuration is required for platform-based customer access, you must contact PayKKa support for more details.


- Click the **avatar** in the top right -> **Settings** -> **Permissions & Security** -> [**Transaction Keys**](https://portal-sandbox.paykka.com/setting/transaction-password)
- Click the **Set** button, click **Add Transaction Key** (will require payment password input), generate a new public-private key pair


🔑 **Transaction Keys**

- Used for Open Platform API call identity and security authentication
- Please keep your private key secure to prevent leakage; PayKKa will not persist your private key
- Supports up to 2 key pairs simultaneously, can be manually rotated if needed to ensure transaction security


🔒 **PayKKa Public Key**

- Used for Open Platform API response and webhook request security authentication
- Must be kept secure to prevent leakage


## Integration

### Basic Preparation

- Build your application and integrate corresponding payment products based on business needs
- Ensure you can handle specific detailed scenarios after integration to maintain payment interaction flow and data consistency


**Currency Decimal Precision**: The `amount` field in PayKKa API must use the currency's **minimum unit** (ISO 4217 standard). For example, currencies like CNY, USD, EUR use 2 decimal places (100 = 1.00), while JPY uses 0 decimal places (100 = ¥100). Passing incorrect decimal precision may result in overcharges or undercharges. Refer to [Currency ISO Fraction Digits](/payments/docs/developer-resources/currency_fraction_digits) for the full reference table.

### Test Scenarios

**Recommended scenarios to verify**:

- Error or rejection handling
- 3DS authentication flow
- Local wallet display and redirect handling
- Webhook notification reception and response handling
- Refund and dispute handling
- Statement and report generation


### Transaction Verification

Please provide your outbound IP address as an IP whitelist before proceeding

#### Sandbox API Address

```bash
https://openapi-sandbox.paykka.com
```

#### Signature Calculation

Process requests and responses according to the authentication flow in [API Authentication](/payments/apis/introduction/api-certification).

#### API Integration

Integrate required interfaces according to the API documentation in [API Reference](/payments/apis/payments/openapi), and process based on response content.

#### Test Cards

```plaintext
# Visa
4242424242424242

# Mastercard
5555555555554444

# Discover
6011111111111117

# Diners Club
3056930009020004

# JCB
3566002020360505
```

## Production Preparation

Please provide your outbound IP address as an IP whitelist before proceeding

### Production Checklist

- Complete all test verifications
- Complete payment function activation in production environment
- Set correct payment password
- Configure correct transaction keys


### Production Environment Setup

> Choose the corresponding API address and account registration address based on your company's registration location


#### API Addresses

- **Asia Pacific**: `https://openapi.paykka.com`
- **Europe**: `https://openapi.eu.paykka.com`


#### Account Registration Addresses

- **Asia Pacific**: [https://portal.paykka.com](https://portal.paykka.com)
- **Europe**: [https://mps.eu.paykka.com](https://mps.eu.paykka.com)