TemanQRIS - Bikin Payment Gateway Dan QRIS Generator Dinamis Cuma Seharga Es Teh!

Authentication

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

API Key

Gunakan API Key untuk semua request ke TemanQRIS API.

X-API-Key: YOUR_API_KEY

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	50 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

{
  "message": "QRIS uploaded successfully",
  "qris_string": "00020101021126...",
  "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,
    "qris_string": "00020101021126...",
    "merchant_name": "TOKO EXAMPLE",
    "merchant_city": "JAKARTA",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_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..."
}

Create Payment Link

Buat link pembayaran yang bisa di-share ke pelanggan.

POST /payment-link Create shareable payment link

Request Body

Field	Type	Description
`amount`	number required	Nominal pembayaran
`description`	string optional	Deskripsi pembayaran (e.g. "Order #123")

curl -X POST https://temanqris.com/api/qris/payment-link \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 75000,
    "description": "Pembayaran Order #12345"
  }'

Response

{
  "success": true,
  "payment_link": {
    "id": 456,
    "link_code": "ABC12345",
    "url": "/p/ABC12345",
    "amount": 75000,
    "expires_at": "2025-12-26T14:00:00.000Z"
  }
}

Link lengkap: https://temanqris.com/p/ABC12345 - Share ke pelanggan via WhatsApp, email, dll.

List Payment Links

Ambil daftar semua payment link Anda.

GET /payment-links Get all payment links

curl https://temanqris.com/api/qris/payment-links \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "payment_links": [
    {
      "id": 456,
      "link_code": "ABC12345",
      "url": "/p/ABC12345",
      "amount": 75000,
      "description": "Order #12345",
      "merchant_name": "TOKO EXAMPLE",
      "is_active": true,
      "view_count": 5,
      "expires_at": "2025-12-31T23:59:59Z",
      "created_at": "2025-12-24T10:00:00.000Z",
      "is_expired": false
    }
  ]
}

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

Order Status Definitions

Status	Description
pending	Menunggu pembayaran dari customer.
awaiting_confirmation	Pembayaran dikonfirmasi customer (widget), menunggu verifikasi.
paid	Pembayaran berhasil dan terverifikasi.
expired	Batas waktu pembayaran telah habis.
cancelled	Order dibatalkan.

{
  "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
  }
}

Delete Payment Link

Hapus/nonaktifkan payment link yang sudah tidak digunakan.

DELETE /payment-link/:id Delete a payment link

curl -X DELETE https://temanqris.com/api/qris/payment-link/456 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "message": "Payment link deleted successfully"
}

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": [...]
    }
  }
}

Embed Widget (widget.js)

Pasang tombol pembayaran QRIS di website Anda dengan satu baris kode. Widget akan menampilkan modal pembayaran yang cantik dan responsif.

EMBED widget.js Embeddable payment button

Installation

Tambahkan kode ini di halaman website Anda:

<script 
  src="https://temanqris.com/widget.js" 
  data-merchant="YOUR_MERCHANT_ID"
></script>

💡 Mendapatkan Merchant ID: Login ke Dashboard → Widget untuk melihat Merchant ID Anda.

Result

Widget akan otomatis menampilkan tombol seperti ini:

Bayar dengan QRIS

Preview tombol widget

Widget Options

Kustomisasi widget sesuai kebutuhan Anda dengan data attributes:

Attribute	Type	Description
`data-merchant`	string *	Merchant ID Anda (wajib)
`data-amount`	number	Nominal tetap (jika tidak diisi, user bisa input sendiri)
`data-button-text`	string	Teks tombol (default: "Bayar dengan QRIS")
`data-button-color`	string	Warna tombol dalam hex (default: "#ff6b35")
`data-description`	string	Deskripsi pembayaran (opsional)
`data-redirect`	string (URL)	URL redirect setelah user klik "Sudah Bayar". Query params otomatis: `order_id`, `amount`, `status`

Full Example with Redirect

<script 
  src="https://temanqris.com/widget.js" 
  data-merchant="abc123xyz"
  data-amount="50000"
  data-button-text="Bayar Sekarang"
  data-button-color="#22c55e"
  data-description="Pembayaran Order #123"
  data-redirect="https://yoursite.com/payment/success"
></script>

🔄 Redirect URL: Setelah user klik "Sudah Bayar", akan di-redirect ke URL dengan query params:
https://yoursite.com/payment/success?order_id=xxx&amount=50000&status=confirmed

⚠️ Catatan Keamanan: Jangan tampilkan Merchant ID di repositori publik. Widget ini aman digunakan di frontend karena pembayaran diproses via server TemanQRIS.

🚀 TemanQRIS API Documentation

Authentication

API Key

Quick Start

Upload QRIS Statis

Generate QRIS Dinamis

Share atau Embed

Rate Limits

Upload Static QRIS

Penting!

Option 1: Upload Image

Option 2: Upload String

Response

Check QRIS Status

Request

Response (QRIS exists)

Response (No QRIS yet)

Generate Dynamic QRIS

Request Body

Example Request

Response

Render QR Image

Response

Create Payment Link

Request Body

Response

List Payment Links

Response

Check Order Status

Request

Response

Order Status Definitions

Query Parameters

Request

Response

Delete Payment Link

Response

API Usage Statistics

Response

Embed Widget (widget.js)

Installation

Result

Widget Options

Full Example with Redirect