Dokumentasi API

Pengenalan API Kropay

Kropay menyediakan API RESTful terpadu untuk memudahkan para merchant mengintegrasikan pembayaran QRIS Dinamis ke website, e-commerce, atau aplikasi kasir secara instan.

Langkah Cepat Memulai:
1. Lakukan pendaftaran akun merchant di Kropay.
2. Masuk ke dashboard dan buka tab Pengaturan.
3. Dapatkan API Key / Client ID Anda.
4. Gunakan API Key tersebut di header setiap HTTP request.

Base URL

https://kropay.krispediadigital.my.id

Kredensial API Anda

Gunakan kunci di bawah ini untuk otentikasi. Jaga kerahasiaannya.

API Key / Client ID

Secret Key (Untuk Callback)

Jangan pernah memberikan kredensial Anda kepada pihak lain demi alasan keamanan.

Pembuatan QRIS

Endpoint ini digunakan untuk membuat transaksi pembayaran QRIS baru berdasarkan parameter nominal yang dikirimkan.

POST https://kropay.krispediadigital.my.id/api/v1/payment/create

HTTP Headers

X-API-KEY: YOUR_API_KEY

Content-Type: application/json

Parameter Request (JSON)

Field	Tipe	Wajib	Keterangan
merchant_ref	String	Ya	ID unik transaksi dari sistem Anda (Maks. 100 karakter).
amount	Integer	Ya	Nominal pembayaran (Minimal Rp 10).
customer_name	String	Tidak	Nama pembeli/pelanggan.
customer_email	String	Tidak	Email pelanggan.
expired_in	Integer	Tidak	Kedaluwarsa QRIS dalam hitungan detik (Min: 300, default: 3600).

Response JSON (Success 201)

{
  "success": true,
  "reference": "PG-20260529A1B2",
  "merchant_ref": "ORDER-12345",
  "amount": 10000,
  "fee": 20,
  "unique_code": 20,
  "total_amount": 10020,
  "status": "pending",
  "expired_at": "2026-05-30 15:30:00",
  "qris_string": "00020101021226580011ID.CO.QREN.WWW0118...",
  "qris_image": "https://kropay.krispediadigital.my.id/api/v1/qris/PG-20260529A1B2.svg"
}

Code Example

<?php
$apiKey = "YOUR_API_KEY";
$url = "https://kropay.krispediadigital.my.id/api/v1/payment/create";

$payload = [
    'merchant_ref' => 'ORDER-' . time(),
    'amount' => 10000,
    'customer_name' => 'Krisdi'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

const apiKey = "YOUR_API_KEY";
const url = "https://kropay.krispediadigital.my.id/api/v1/payment/create";

const payload = {
  merchant_ref: `ORDER-${Date.now()}`,
  amount: 10000,
  customer_name: "Krisdi"
};

fetch(url, {
  method: "POST",
  headers: {
    "X-API-KEY": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

curl -X POST "https://kropay.krispediadigital.my.id/api/v1/payment/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "ORDER-12345",
    "amount": 10000,
    "customer_name": "Krisdi"
  }'

Cek Status Transaksi

Gunakan API ini untuk melakukan pengecekan status transaksi pembayaran QRIS secara manual / real-time dari server Anda.

GET https://kropay.krispediadigital.my.id/api/v1/payment/status/{reference}

HTTP Headers

X-API-KEY: YOUR_API_KEY

Content-Type: application/json

Parameter URL

Parameter	Tipe	Wajib	Keterangan
{reference}	String	Ya	Nomor referensi unik transaksi Kropay (contoh: `PG-20260529A1B2`).

Response JSON (Success 200 OK)

{
  "success": true,
  "reference": "PG-20260529A1B2",
  "merchant_ref": "ORDER-12345",
  "amount": 10000,
  "fee": 20, // Potongan biaya MDR 0.2%
  "total_amount": 10020,
  "net_amount": 10000, // Dana bersih yang diterima merchant
  "status": "success", // pending, success, failed, expired
  "created_at": "2026-05-29 15:00:00",
  "paid_at": "2026-05-29 15:30:00"
}

Code Example

<?php
$apiKey = "YOUR_API_KEY";
$reference = "PG-20260529A1B2";
$url = "https://kropay.krispediadigital.my.id/api/v1/payment/status/" . $reference;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

const apiKey = "YOUR_API_KEY";
const reference = "PG-20260529A1B2";
const url = `https://kropay.krispediadigital.my.id/api/v1/payment/status/${reference}`;

fetch(url, {
  method: "GET",
  headers: {
    "X-API-KEY": apiKey,
    "Content-Type": "application/json"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

curl -X GET "https://kropay.krispediadigital.my.id/api/v1/payment/status/PG-20260529A1B2" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Cek Profile

Gunakan API ini untuk mendapatkan informasi dasar profile Anda seperti nama dan sisa saldo (balance) saat ini.

GET https://kropay.krispediadigital.my.id/api/v1/profile

HTTP Headers

X-API-KEY: YOUR_API_KEY

Content-Type: application/json

Response JSON (Success 200 OK)

{
  "success": true,
  "nama": "Nama Anda",
  "balance": 150000
}

Code Example

<?php
$apiKey = "YOUR_API_KEY";
$url = "https://kropay.krispediadigital.my.id/api/v1/profile";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

const apiKey = "YOUR_API_KEY";
const url = "https://kropay.krispediadigital.my.id/api/v1/profile";

fetch(url, {
  method: "GET",
  headers: {
    "X-API-KEY": apiKey,
    "Content-Type": "application/json"
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

curl -X GET "https://kropay.krispediadigital.my.id/api/v1/profile" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Callback / Webhook

Ketika transaksi QRIS berhasil dibayar oleh pelanggan, server Kropay akan mengirimkan callback request POST otomatis ke URL yang telah Anda atur di dashboard.

Payload Callback (HTTP POST - JSON)

{
  "reference": "PG-20260529A1B2",
  "merchant_ref": "ORDER-12345",
  "amount": 10000,
  "fee": 20, // Potongan fee MDR 0.2%
  "unique_code": 20,
  "total_amount": 10020,
  "status": "paid",
  "expired_at": "2026-05-30 15:30:00",
  "paid_at": "2026-05-29 15:30:00"
}

Verifikasi Keamanan (X-Signature Header)

Setiap callback dari Kropay menyertakan header X-Signature. Gunakan Secret Key Anda untuk memverifikasi bahwa request benar-benar berasal dari server Kropay dan bukan dari pihak ketiga yang mencoba memanipulasi data.

X-Signature: HMAC-SHA256(rawPayload, secretKey)

// Header dikirim bersama setiap callback POST request

⚠️ Penting: Selalu verifikasi X-Signature sebelum memproses callback. Tolak request jika signature tidak cocok. Secret Key Anda ada di panel Kredensial API.

Respon yang Diharapkan:
Server merchant harus membalas dengan status HTTP 200 OK dan body JSON {"success": true}. Jika server merchant memberikan respon selain itu (atau timeout), server Kropay akan melakukan percobaan callback ulang secara berkala.

Handler Example

<?php
// Secret Key dari Dashboard Anda
$secretKey = "YOUR_SECRET_KEY";

// Baca raw payload dari Kropay
$rawInput = file_get_contents('php://input');
$payload = json_decode($rawInput, true);

// Ambil signature dari header request
$receivedSig = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Hitung ulang signature dengan secret key Anda
$expectedSig = hash_hmac('sha256', $rawInput, $secretKey);

// ✅ Verifikasi: Tolak jika signature tidak cocok
if (!hash_equals($expectedSig, $receivedSig)) {
    http_response_code(403);
    echo json_encode(['success' => false, 'message' => 'Invalid signature']);
    exit;
}

// ✅ Proses pembayaran
$status = $payload['status'];
$merchantRef = $payload['merchant_ref'];

if ($status === 'paid') {
    // TODO: Update status order di DB Anda
}

header('Content-Type: application/json');
echo json_encode(['success' => true]);
exit;

const express = require('express');
const crypto = require('crypto');
const app = express();

// Secret Key dari Dashboard Anda
const SECRET_KEY = "YOUR_SECRET_KEY";

// Gunakan raw body parser untuk verifikasi HMAC
app.use(express.raw({ type: 'application/json' }));

app.post('/api/callback', (req, res) => {
  const rawBody = req.body.toString();
  const receivedSig = req.headers['x-signature'];

  // ✅ Verifikasi Signature
  const expectedSig = crypto
    .createHmac('sha256', SECRET_KEY)
    .update(rawBody)
    .digest('hex');

  if (receivedSig !== expectedSig) {
    return res.status(403).json({ success: false, message: 'Invalid signature' });
  }

  const { merchant_ref, status } = JSON.parse(rawBody);

  if (status === 'paid') {
    // TODO: Update order status di database Anda
  }

  res.status(200).json({ success: true });
});

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

# Simulasi callback dari Kropay (untuk testing lokal)
# Hitung HMAC-SHA256 dari payload menggunakan Secret Key

PAYLOAD='{"reference":"PG-20260529A1B2","merchant_ref":"ORDER-12345","amount":10000,"fee":20,"unique_code":20,"total_amount":10020,"status":"paid","paid_at":"2026-05-29 15:30:00"}'

SECRET="YOUR_SECRET_KEY"

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://websiteanda.com/api/callback" \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d "$PAYLOAD"