🚀 TemanQRIS API Documentation

RESTful API untuk mengkonversi QRIS statis menjadi QRIS dinamis dengan nominal custom, fee, dan payment link yang bisa di-share.

Base URL: https://temanqris.com/api/qris

Authentication

Semua API endpoint memerlukan autentikasi. Gunakan API Key yang bisa Anda dapatkan dari Dashboard Settings.

API Key (Recommended)

Untuk integrasi eksternal dan server-to-server

X-API-Key: YOUR_API_KEY

Bearer Token

Untuk akses dari dashboard frontend

Authorization: Bearer YOUR_JWT_TOKEN
Keamanan API Key
Jangan pernah expose API Key di frontend atau commit ke repository. Gunakan environment variables.

Quick Start

Tiga langkah untuk mulai menggunakan TemanQRIS API:

1

Upload QRIS Statis

Upload gambar atau string QRIS statis Anda (sekali saja)

2

Generate QRIS Dinamis

Buat QRIS dengan nominal kapan saja

3

Share atau Embed

Gunakan payment link atau embed widget

Rate Limits

Batas request harian berdasarkan tier akun:

Tier Daily Limit Stored QRIS Features
Free 100 requests/day 1 QRIS Basic features
Premium 1000 requests/day Unlimited* All features + Priority support
Gunakan endpoint GET /api/qris/usage untuk monitoring penggunaan API real-time.

Upload Static QRIS

Upload QRIS statis Anda. Ini hanya perlu dilakukan SEKALI saja.

Penting!

Upload QRIS statis hanya diperlukan sekali saat pertama kali setup. Setelah berhasil upload, Anda bisa langsung menggunakan endpoint /generate untuk membuat QRIS dinamis tanpa perlu upload ulang. Gunakan endpoint /my-qris untuk mengecek apakah Anda sudah pernah upload QRIS.

POST /upload Upload QRIS image or string (one-time only)

Option 1: Upload Image

Upload file gambar QRIS (jpg, png, webp)

# Upload image file
curl -X POST https://temanqris.com/api/qris/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "qris_image=@/path/to/qris.png"

Option 2: Upload String

Jika sudah punya QRIS string (hasil decode)

# Upload QRIS string
curl -X POST https://temanqris.com/api/qris/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qris_string": "00020101021126670016COM.NOBUBANK.WWW..."
  }'

Response

200 OK 
{
  "success": true,
  "message": "QRIS uploaded successfully",
  "qris_id": 123,
  "merchant": {
    "name": "TOKO EXAMPLE",
    "city": "JAKARTA"
  }
}

Check QRIS Status

Cek apakah Anda sudah pernah upload QRIS statis. Gunakan sebelum memanggil /upload untuk menghindari upload yang tidak perlu.

GET /my-qris Check if QRIS has been uploaded

Request

# Check QRIS status
curl -X GET https://temanqris.com/api/qris/my-qris \
  -H "X-API-Key: YOUR_API_KEY"

Response (QRIS exists)

200 OK 
{
  "has_qris": true,
  "qris": {
    "id": 123,
    "merchant_name": "TOKO EXAMPLE",
    "merchant_city": "JAKARTA",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Response (No QRIS yet)

200 OK 
{
  "has_qris": false,
  "message": "No QRIS found. Please upload your static QRIS first (only needed once)."
}

Generate Dynamic QRIS

Endpoint utama untuk membuat QRIS dinamis dengan nominal transaksi.

POST /generate Generate QRIS with amount

Request Body

Field Type Description
amount number required Nominal transaksi (contoh: 50000)
fee_type string optional "rupiah" atau "percent"
fee_value number optional Nilai fee yang ditambahkan
qris_id number optional ID QRIS spesifik (jika punya multiple)

Example Request

# Generate QRIS Rp 50.000 + fee Rp 1.000
curl -X POST https://temanqris.com/api/qris/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "fee_type": "rupiah",
    "fee_value": 1000
  }'

Response

200 OK 
{
  "success": true,
  "qris": "00020101021226...",
  "qr_image": "data:image/png;base64,...",
  "amount": 50000,
  "fee": { "type": "rupiah", "value": 1000 },
  "expires_at": "2025-12-25T10:00:00.000Z"
}
Field qr_image berisi Base64 image yang bisa langsung ditampilkan dengan <img src="...">

Render QR Image

Generate gambar QR code dari string QRIS.

POST /render Render QR from string 
curl -X POST https://temanqris.com/api/qris/render \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qris_string": "00020101021126..."
  }'

Response

{
  "qr_image": "data:image/png;base64,iVBOR..."
}

Check Order Status

Cek status pembayaran order/payment link via API. Berguna untuk integrasi backend-to-backend.

GET /orders/:orderId Check single order status

Request

# Check specific order by order_id
curl -X GET https://temanqris.com/api/qris/orders/ORD-ABC123 \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK 
{
  "success": true,
  "order": {
    "order_id": "ORD-ABC123",
    "title": "Pembayaran Invoice #001",
    "amount": 50000,
    "total_amount": 51000,
    "status": "paid",
    "is_paid": true,
    "is_expired": false,
    "created_at": "2024-01-15T10:30:00Z",
    "paid_at": "2024-01-15T10:35:00Z"
  }
}
GET /orders List all orders with pagination

Query Parameters

Parameter Type Description
status string Filter by status: pending, paid, expired, cancelled
limit number Max results (default: 20)
offset number Offset for pagination

Request

# Get all paid orders
curl -X GET "https://temanqris.com/api/qris/orders?status=paid&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK 
{
  "success": true,
  "orders": [
    {
      "order_id": "ORD-ABC123",
      "title": "Invoice #001",
      "amount": 50000,
      "status": "paid",
      "is_paid": true
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 10,
    "offset": 0
  }
}

API Usage Statistics

Monitor penggunaan API dan sisa limit Anda.

GET /usage Get usage statistics 
curl https://temanqris.com/api/qris/usage \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "tier": "free",
  "daily_limit": 100,
  "usage": {
    "today": {
      "total": 15,
      "remaining": 85,
      "by_endpoint": [
        { "endpoint": "/qris/generate", "request_count": 10 },
        { "endpoint": "/qris/payment-link", "request_count": 5 }
      ]
    },
    "this_month": {
      "total": 250,
      "by_endpoint": [...]
    }
  }
}