IskaPay API

https://wallet.iskapay.com/api/docs
Admin
IskaPay API provides an easy-to-integrate, simple, fast, and reliable QRIS payment gateway solution,...
Tokens:4,267
Snippets:14
Trust Score:4.4
Update:11 months ago
Show doc for...
Tokens:
Raw
### Iskapay Payment Integration (PHP)

Source: https://wallet.iskapay.com/api/docs/index

This PHP snippet illustrates how to integrate with the Iskapay API. It includes functions for creating payments, retrieving payment status using a merchant order ID, and setting up a webhook endpoint. The example assumes you have a database connection object (`$db`) available for persisting payment information. Ensure the 'Iskapay.php' class is included.

```php
<?php
// 1. Import Class
require_once 'Iskapay.php';

// 2. Initialize Client
$iskapay = new Iskapay('isk_your_api_key_here');

// 3. Create Payment (AUTO-GENERATE merchant_order_id)
function createPayment($iskapay, $db) {
    try {
        $payment = $iskapay->createPayment([
            'amount' => 50000,
            'customer_name' => 'John Doe',
            'customer_email' => 'john@example.com',
            'customer_phone' => '08123456789',
            'description' => 'Pembayaran Order #123',
            'callback_url' => 'https://yourapp.com/webhook.php'
        ]);

        // ✅ SIMPAN merchant_order_id ke database!
        $orderId = $payment['data']['merchant_order_id'];
        $db->query(
            "INSERT INTO payments (order_id, payment_url, qr_code, amount, status) 
             VALUES (?, ?, ?, ?, 'pending')",
            [
                $orderId,
                $payment['data']['payment_url'],
                $payment['data']['qr_code'],
                $payment['data']['amount']
            ]
        );

        echo "Payment created!\n";
        echo "Order ID: {$orderId}\n";
        echo "Payment URL: {$payment['data']['payment_url']}\n";
        
        return $orderId; // Return untuk cek status nanti
        
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
        return null;
    }
}

// 4. Check Payment Status (gunakan orderId yang disimpan)
function checkPaymentStatus($iskapay, $db, $orderId) {
    try {
        $result = $iskapay->getPayment($orderId);
        
        echo "Status: {$result['data']['status']}\n";
        echo "Amount: {$result['data']['amount']}\n";
        
        // Update database
        if ($result['data']['status'] === 'completed') {
            $db->query(
                "UPDATE payments SET status = 'paid' WHERE order_id = ?",
                [$orderId]
            );
            echo "✅ Payment completed!\n";
        }
        
        return $result['data'];
        
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
        return null;
    }
}

// 5. Handle Webhook (webhook.php)

```

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

### Iskapay Payment Integration (JavaScript)

Source: https://wallet.iskapay.com/api/docs/index

This snippet demonstrates how to integrate with the Iskapay API using Node.js. It covers initializing the client, creating a payment (with auto-generated or custom order IDs), checking payment status, and handling webhook notifications for payment events. Ensure you have the 'axios' package installed. The webhook handler includes signature verification for security.

```javascript
// 1. Install & Import
// npm install axios
const Iskapay = require('./Iskapay');

// 2. Initialize Client
const client = new Iskapay('isk_your_api_key_here');

// 3. Create Payment (AUTO-GENERATE merchant_order_id)
async function createPayment() {
  try {
    const payment = await client.createPayment({
      amount: 50000,
      customerName: 'John Doe',
      customerEmail: 'john@example.com',
      customerPhone: '08123456789',
      description: 'Pembayaran Order #123',
      callbackUrl: 'https://yourapp.com/webhook'
    });

    // ✅ SIMPAN merchant_order_id ke database!
    const orderId = payment.data.merchant_order_id;
    await saveToDatabase({
      order_id: orderId,
      payment_url: payment.data.payment_url,
      qr_code: payment.data.qr_code,
      amount: payment.data.amount,
      status: 'pending'
    });

    console.log('Payment created!');
    console.log('Order ID:', orderId);
    console.log('Payment URL:', payment.data.payment_url);
    
    return orderId; // Return untuk cek status nanti
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// 4. Check Payment Status (gunakan orderId yang disimpan)
async function checkPaymentStatus(orderId) {
  try {
    const result = await client.getPayment(orderId);
    
    console.log('Status:', result.data.status);
    console.log('Amount:', result.data.amount);
    
    // Update database
    if (result.data.status === 'completed') {
      await updateDatabase(orderId, { status: 'paid' });
      console.log('✅ Payment completed!');
    }
    
    return result.data;
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// 5. Handle Webhook
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', async (req, res) => {
  const payload = req.body;
  const signature = req.headers['x-signature'];
  
  // Verify webhook
  if (!client.verifyWebhook(payload, signature, 'your_secret')) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  const orderId = payload.payment.merchant_order_id;
  console.log('Webhook received:', orderId, payload.event);
  
  if (payload.event === 'payment.completed') {
    await updateDatabase(orderId, { 
      status: 'paid',
      paid_at: payload.payment.paid_at 
    });
  }
  
  res.json({ success: true });
});

app.listen(3000, () => console.log('Server running'));

// Usage:
const orderId = await createPayment();
// Simpan orderId, lalu gunakan untuk cek status:
await checkPaymentStatus(orderId);

```

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

### Get Payment Statistics (cURL)

Source: https://wallet.iskapay.com/api/docs/index

Retrieves statistical data about payments, such as total payments and success rate. Requires an API Key for authentication.

```curl
curl -X GET https://wallet.iskapay.com/api/gateway/payments/statistics \
  -H "X-API-Key: isk_your_api_key_here"
```

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

### Create QRIS Payment (JavaScript, PHP)

Source: https://wallet.iskapay.com/api/docs/index

Creates a new QRIS payment with minimal required fields. Accepts amount and customer name. Returns payment details including a merchant order ID that should be stored for future reference.

```javascript
const payment = await client.createPayment({
  amount: 50000,
  customerName: 'John Doe'
});

// Simpan order ID
const orderId = payment.data.merchant_order_id;
```

```php
$payment = $iskapay->createPayment([
  'amount' => 50000,
  'customer_name' => 'John Doe'
]);

// Simpan order ID
$orderId = $payment['data']['merchant_order_id'];
```

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

### Create IskaPay Payment Request

Source: https://wallet.iskapay.com/api/docs/index

Makes HTTP request to create new QRIS payment with IskaPay API. Requires minimum amount and customer name parameters. Returns payment details including QR code URL and merchant order ID for tracking.

```bash
curl -X POST https://wallet.iskapay.com/api/gateway/payments \
  -H "X-API-Key: isk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "customer_name": "John Doe"
  }'
```

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

### Webhook Handling

Source: https://wallet.iskapay.com/api/docs/index

This section describes how to handle incoming webhooks from Iskapay, including signature verification and processing payment status updates.

```APIDOC
## Webhook Handling

### Description
Handles incoming webhook notifications from Iskapay regarding payment status changes. It is essential to verify the webhook signature to ensure the request's authenticity before processing the payload.

### Method
POST

### Endpoint
(Your configured callback URL)

### Parameters
#### Request Body
- **payment** (object) - Contains payment details.
  - **merchant_order_id** (string) - The merchant order ID associated with the payment.
  - **paid_at** (string) - Timestamp when the payment was completed.
- **event** (string) - The type of event that occurred (e.g., 'payment.completed').

### Request Example (Payload)
```json
{
  "payment": {
    "merchant_order_id": "INV-1-20250112-ABCD",
    "paid_at": "2025-01-12T09:30:00.000000Z"
  },
  "event": "payment.completed"
}
```

### Request Headers
- **X-SIGNATURE** (string) - The signature of the webhook request for verification.

### Verification Process
1. Retrieve the raw request payload.
2. Get the `X-SIGNATURE` header value.
3. Use your `secret` key and the payload to compute the expected signature.
4. Compare the computed signature with the `X-SIGNATURE` header. If they do not match, return a 401 Unauthorized response.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates successful processing of the webhook.

#### Error Response (401)
- **error** (string) - Indicates an invalid signature.

#### Response Example (Success)
```json
{
  "success": true
}
```

### Usage Notes
- **DO**: Save `merchant_order_id` to your database.
- **DO**: Use webhooks for status updates.
- **DO**: Verify webhook signatures.
- **DON'T**: Poll for status too frequently.
- **DON'T**: Expose API keys on the client-side.
- **DON'T**: Skip webhook verification.
- **DON'T**: Forget to handle expired payments.
```

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

### POST /payments

Source: https://wallet.iskapay.com/api/docs/index

Creates a new QRIS payment. The system automatically generates a `merchant_order_id` and QR code. It's crucial to save the returned `merchant_order_id` for future status checks.

```APIDOC
## POST /payments

### Description
Creates a new QRIS payment. The system automatically generates a `merchant_order_id` and QR code. It's crucial to save the returned `merchant_order_id` for future status checks.

### Method
POST

### Endpoint
/payments

### Parameters
#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - Nominal pembayaran (min: 1000, max: 50000000)
- **customer_name** (string) - Required - Nama customer (max 100 char)
- **customer_email** (string) - Optional - Email customer untuk notifikasi
- **customer_phone** (string) - Optional - No telepon customer
- **description** (string) - Optional - Deskripsi pembayaran
- **callback_url** (string) - Optional - URL webhook untuk notifikasi status

### Request Example
```json
{
  "amount": 50000,
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "customer_phone": "08123456789",
  "description": "Pembayaran Order #123",
  "callback_url": "https://yourapp.com/webhook"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message confirming the payment creation.
- **data** (object) - Contains details about the created payment.
  - **payment_id** (integer) - The internal ID of the payment.
  - **merchant_order_id** (string) - The unique merchant order ID. **Save this!**
  - **amount** (number) - The payment amount.
  - **total_amount** (number) - The total amount including any fees.
  - **unique_amount** (number) - The unique portion of the amount, if applicable.
  - **status** (string) - The current status of the payment (e.g., 'pending').
  - **payment_method** (string) - The method used for payment (e.g., 'qris').
  - **qr_code** (string) - URL to the generated QR code.
  - **payment_url** (string) - Direct URL to the payment page.
  - **callback_url** (string) - The configured callback URL for webhooks.
  - **expired_at** (string) - The expiration timestamp for the payment.
  - **created_at** (string) - The timestamp when the payment was created.

#### Response Example
```json
{
  "success": true,
  "message": "Payment created successfully",
  "data": {
    "payment_id": 12345,
    "merchant_order_id": "INV-1-20250112-ABCD",
    "amount": 50000,
    "total_amount": 50123,
    "unique_amount": 123,
    "status": "pending",
    "payment_method": "qris",
    "qr_code": "https://yourdomain.com/storage/qr/INV-1-20250112-ABCD.png",
    "payment_url": "https://yourdomain.com/payment/INV-1-20250112-ABCD",
    "callback_url": "https://yourapp.com/webhook",
    "expired_at": "2025-01-12T10:00:00.000000Z",
    "created_at": "2025-01-12T09:00:00.000000Z"
  }
}
```

### cURL Example
```bash
curl -X POST https://wallet.iskapay.com/api/gateway/payments \
  -H "X-API-Key: isk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "customer_name": "John Doe"
  }'
```
```

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

### List All QRIS Payments (cURL)

Source: https://wallet.iskapay.com/api/docs/index

Retrieves a list of all QRIS payments. Supports optional filtering by status, date range, limit, and page number. Requires an API Key for authentication.

```curl
curl -G https://wallet.iskapay.com/api/gateway/payments \
  -H "X-API-Key: isk_your_api_key_here" \
  --data-urlencode "status=completed" \
  --data-urlencode "limit=20"
```

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

### Check Account Balance (cURL)

Source: https://wallet.iskapay.com/api/docs/index

Fetches the current balance of the user's account. Requires an API Key for authentication.

```curl
curl -X GET https://wallet.iskapay.com/api/gateway/balance \
  -H "X-API-Key: isk_your_api_key_here"
```

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

### Handle IskaPay Payment Database Update

Source: https://wallet.iskapay.com/api/docs/index

Updates local payment records when IskaPay webhook confirms successful payment. Uses prepared statements to prevent SQL injection. Requires active database connection and verified webhook payload.

```PHP
if ($payload['event'] === 'payment.completed') {
    $db->query(
        "UPDATE payments SET status = 'paid', paid_at = ? WHERE order_id = ?",
        [$payload['payment']['paid_at'], $orderId]
    );
}
```

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

### Check QRIS Payment Status (cURL)

Source: https://wallet.iskapay.com/api/docs/index

Retrieves the status of a QRIS payment using the stored merchant order ID. Requires an API Key for authentication. Returns payment details including amount, status, and time remaining.

```curl
curl -X GET https://wallet.iskapay.com/api/gateway/payments/INV-1-20250112-ABCD \
  -H "X-API-Key: isk_your_api_key_here"
```

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

### Verify IskaPay Webhook Signature

Source: https://wallet.iskapay.com/api/docs/index

Processes and verifies incoming webhooks from IskaPay payment system. Requires JSON payload parsing and HTTP signature verification. Returns 401 error for invalid signatures and logs payment events.

```PHP
$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Verify webhook
if (!$iskapay->verifyWebhook($payload, $signature, 'your_secret')) {
    http_response_code(401);
    exit(json_encode(['error' => 'Invalid signature']));
}

// Process webhook
$orderId = $payload['payment']['merchant_order_id'];
error_log("Webhook received: {$orderId} - {$payload['event']}");

if ($payload['event'] === 'payment.completed') {
    $db->query(
        "UPDATE payments SET status = 'paid', paid_at = ? WHERE order_id = ?",
        [$payload['payment']['paid_at'], $orderId]
    );
}

http_response_code(200);
echo json_encode(['success' => true]);
```

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

### Cancel QRIS Payment (cURL)

Source: https://wallet.iskapay.com/api/docs/index

Cancels a QRIS payment that is currently in a 'pending' state. Requires the merchant order ID and an API Key for authentication.

```curl
curl -X POST https://wallet.iskapay.com/api/gateway/payments/INV-1-20250112-ABCD/cancel \
  -H "X-API-Key: isk_your_api_key_here"
```
Tokens:
Raw