API LAZISNU — Mitra Eksternal

Spesifikasi integrasi API untuk mitra eksternal pada platform NU Care / CMS LAZISNU.

Status: Endpoint /api/v1/partners/* telah diimplementasikan. Dokumen ini menjadi kontrak integrasi resmi untuk mitra eksternal.

1. Ringkasan

Aspek	Keterangan
Base path	`/api/v1/partners/*`
Identitas mitra	API Key + `X-Partner-Code` (kode unik per mitra)
Format body create	`application/json`
Response envelope	`{ meta, data, pagination? }`
Create donasi/zakat/kurban	1 endpoint unified `POST /transactions`
List program	filter `category_id` / `sub_category_id`
Auth	API Key + HMAC signature (recommended)

2. Base URL & Versioning

Semua endpoint menggunakan path prefix:

/api/v1/partners

Environment	Keterangan
Production	Host production diberikan saat onboarding integrasi
Staging	Host staging diberikan saat onboarding integrasi

Format lengkap: https://{host}/api/v1/partners/{endpoint}

Hostname (base URL) tidak dipublikasikan di dokumentasi publik. Hubungi tim integrasi LAZISNU untuk mendapatkan endpoint environment Anda.

Semua endpoint wajib menggunakan prefix versi (/v1/). Perubahan breaking hanya melalui versi baru (/v2/).

3. Autentikasi & Keamanan

3.1 Header wajib

Header	Wajib	Contoh	Keterangan
`Authorization`	Ya	`Bearer {api_key}`	API key mitra (diberikan LAZISNU)
`X-Partner-Code`	Ya	`your_partner_code`	Kode mitra unik (snake_case, diberikan saat onboarding)
`Content-Type`	Ya (POST/PUT)	`application/json`
`Accept`	Disarankan	`application/json`
`X-Request-Id`	Disarankan	UUID v4	Trace request
`Idempotency-Key`	Ya (POST transaksi)	UUID v4	Cegah duplikasi transaksi
`X-Timestamp`	Ya (HMAC mode)	`1718000000`	Unix timestamp (detik)
`X-Signature`	Ya (HMAC mode)	`sha256=...`	HMAC-SHA256 body

3.2 Partner code

X-Partner-Code berisi kode unik mitra dalam format snake_case. Nilai kode diberikan secara khusus oleh tim LAZISNU saat onboarding dan bersifat rahasia.

Contoh:

Field	Contoh
Header `X-Partner-Code`	`your_partner_code`
Response `partner_code`	`your_partner_code`
Response `partner_name`	`YOUR PARTNER`

Daftar lengkap partner code tidak dipublikasikan. Hubungi tim integrasi LAZISNU untuk mendapatkan kode mitra Anda.

3.3 HMAC Signature (recommended)

signature = HMAC_SHA256(api_secret, timestamp + "." + raw_json_body)
Header: X-Signature: sha256={signature}

Timestamp toleransi: ±300 detik
Request di luar window → 401 INVALID_SIGNATURE

3.4 Rate limit

Tier	Limit
Default	60 request / menit / API key
Burst create transaction	10 request / detik

Response headers:

X-RateLimit-Limit
X-RateLimit-Remaining
Retry-After (saat 429)

4. Format Response Standar

4.1 Success (single resource)

{
  "meta": {
    "code": 200,
    "status": "success",
    "message": null,
    "response_date": "2026-06-03T10:12:07+07:00",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "data": {}
}

4.2 Success (list + pagination)

{
  "meta": {
    "code": 200,
    "status": "success",
    "message": null,
    "response_date": "2026-06-03T10:12:07+07:00",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "data": [],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "last_page": 8
  }
}

4.3 Error

{
  "meta": {
    "code": 422,
    "status": "error",
    "message": "Validation failed",
    "response_date": "2026-06-03T10:12:07+07:00",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "data": null,
  "errors": {
    "amount": ["Minimal nominal transaksi Rp 5.000"]
  }
}

4.4 HTTP status mapping

HTTP	`meta.code`	Keterangan
200	200	OK
201	201	Created
400	400	Bad request
401	401	Unauthorized / invalid signature
403	403	Partner tidak punya akses resource
404	404	Resource tidak ditemukan
409	409	Idempotency conflict
422	422	Validation error
429	429	Rate limit
500	500	Internal server error

5. Data Model (referensi `app/Models`)

5.1 Transaction (`transactions`)

Field	Type	Required	Keterangan
`id`	integer	auto	Primary key internal
`trx_id`	string	auto	Format: `LZNU{4digit}{timestamp}`
`amount`	integer	ya	Nominal Rupiah (tanpa desimal)
`name`	string	ya	Nama donatur/muzakki
`email`	string	opsional
`phone`	string	opsional	Nomor telepon donatur
`address`	string	opsional
`description`	string	opsional	Catatan transaksi
`donation_id`	integer	ya	ID program donasi/zakat/qurban
`category_id`	integer	auto	Dari relasi `donation.category_id`
`organization_id`	integer	auto	Dari relasi `donation.organization_id`
`status`	enum	auto	`PENDING`, `SUCCESS`, `EXPIRED`
`via_method`	enum	auto	Selalu `partner` untuk mitra eksternal
`payment_method`	string	ya	Di-set server dari `X-Partner-Code` (contoh: `your_partner_code`)
`is_anon`	boolean	opsional	Default `false`
`is_published`	boolean	opsional	Default `true`
`meta_data`	object	opsional	Data tambahan bebas (JSON)
`partner_reference_id`	string	opsional	ID transaksi di sisi mitra (disarankan)
`expired_at`	datetime	auto	ISO8601 WIB
`created_at`	datetime	auto	ISO8601 WIB
`updated_at`	datetime	auto	ISO8601 WIB

5.2 Donation / Campaign (`donations`)

Field	Type	Keterangan
`id`	integer	ID program
`title`	string	Judul campaign
`slug`	string	URL slug
`descriptions`	string	Deskripsi HTML/text
`target`	decimal	Target nominal
`total_collected`	integer	Agregat transaksi SUCCESS
`category_id`	integer	Lihat tabel kategori
`sub_category_id`	integer	Sub-kategori program
`organization_id`	integer	LAZISNU pengelola
`status`	enum	`processed`, `approved`, `rejected`
`is_active`	boolean	Hanya `true` yang ditampilkan ke mitra
`started_at`	datetime
`ended_at`	datetime

5.3 DonationCategory (`donation_categories`)

ID	Kode	Nama
1	ZN	Zakat
2	DN	Donasi
3	CN	Campaign / Crowdfunding
4	QN	Qurban
5	FN	Fidyah
6	KN	Koin NU
7	WK	Wakaf

5.4 Organization (`organizations`)

Field	Type	Keterangan
`id`	integer
`name`	string
`slug`	string
`code`	string	Kode unit LAZISNU
`phone`	string	Nomor telepon
`email`	string
`address`	string	Alamat lengkap
`npwp`	string
`is_active`	boolean

6. Endpoint

6.1 Profil Mitra

GET /me

Response 200

{
  "meta": { "code": 200, "status": "success", "message": null, "response_date": "2026-06-03T10:12:07+07:00", "request_id": "..." },
  "data": {
    "partner_code": "your_partner_code",
    "partner_name": "YOUR PARTNER",
    "organization": {
      "id": 1,
      "name": "LAZISNU Pusat",
      "slug": "lazisnu-pusat",
      "phone": "021-xxxx",
      "email": "[email protected]",
      "address": "Jakarta",
      "npwp": "xx.xxx.xxx.x-xxx.xxx"
    },
    "allowed_category_ids": [1, 2, 3, 4],
    "webhook_url": "https://partner.example.com/webhooks/lazisnu"
  }
}

6.2 Kategori & Sub-kategori

GET /categories

Response 200: list kategori aktif.

GET /categories/{category_id}/sub-categories

Mengembalikan daftar sub-kategori untuk kategori tertentu.

6.3 Campaign / Donasi (Crowdfunding)

GET /campaigns

Query	Type	Keterangan
`category_id`	integer	Default `3` (Campaign)
`sub_category_id`	integer	Filter sub-kategori
`organization_id`	integer	Filter LAZISNU unit
`search`	string	Cari judul
`status`	string	Default hanya `approved` + `is_active=true`
`page`	integer	Default `1`
`per_page`	integer	Default `20`, max `100`

Response 200 (item)

{
  "id": 9,
  "title": "Bantu Pulihkan Pesantren Terdampak Banjir Sultra",
  "slug": "bantu_pulihkan_pesantren_terdampak_banjir_sultra",
  "category": { "id": 3, "name": "Campaign", "slug": "campaign" },
  "sub_category": { "id": 6, "name": "Pendidikan", "slug": "pendidikan" },
  "status": "open",
  "target": 500000000,
  "total_collected": 125000000,
  "organization": { "id": 1, "name": "LAZISNU Pusat", "slug": "lazisnu-pusat" },
  "started_at": "2026-01-01 00:00:00",
  "ended_at": "2026-12-31 23:59:59"
}

GET /campaigns/{id} — detail campaign.

GET /campaigns/slug/{slug} — detail by slug.

6.4 Zakat

GET /zakat

Query	Type	Keterangan
`type`	string	`zakat_maal`, `zakat_profesi`, `zakat_fitrah`, `zakat`
`page`, `per_page`	integer	Pagination

Response 200 (item)

{
  "id": 58,
  "title": "Zakat Maal",
  "slug": "zakat_maal",
  "program_type": "zakat",
  "category_id": 1,
  "status": "open",
  "minimum_amount": 10000
}

6.5 Qurban

GET /qurban/products

Query	Type	Keterangan
`organization_id`	integer	Opsional
`page`, `per_page`	integer	Pagination

Response 200 (item)

{
  "id": 37,
  "title": "Kambing",
  "slug": "kambing",
  "category_id": 4,
  "price": 2900000,
  "status": "open",
  "organization": { "id": 1, "name": "LAZISNU Pusat" }
}

6.6 Transaksi (Unified Create)

POST /transactions

Headers tambahan: Idempotency-Key: {uuid}

Request body

{
  "donation_id": 58,
  "amount": 1000000,
  "name": "Andi Chan",
  "email": "[email protected]",
  "phone": "0853981253678",
  "npwp": "1234567891234567",
  "address": "Jakarta",
  "description": "Donasi via mitra",
  "is_anon": false,
  "partner_reference_id": "PTR-20260603-001",
  "meta_data": {
    "channel": "partner_checkout",
    "order_id": "1234567890"
  }
}

Field	Required	Validasi
`donation_id`	ya	exists, active, whitelisted untuk partner
`amount`	ya	integer, min `5000` (qurban: harus match `price` jika fixed)
`name`	ya	max 255
`email`	opsional	valid email
`phone`	opsional	8–15 digit
`npwp`	opsional	15–16 digit
`partner_reference_id`	disarankan	unique per partner
`meta_data`	opsional	object

payment_method tidak dikirim client — di-set server dari X-Partner-Code.
via_method otomatis partner.

Response 201

{
  "meta": { "code": 201, "status": "success", "message": "Transaction created", "response_date": "...", "request_id": "..." },
  "data": {
    "id": 4,
    "trx_id": "LZNU00011718000000",
    "donation_id": 58,
    "donation": {
      "id": 58,
      "title": "Zakat Maal",
      "slug": "zakat_maal"
    },
    "amount": 1000000,
    "name": "Andi Chan",
    "email": "[email protected]",
    "phone": "0853981253678",
    "status": "SUCCESS",
    "via_method": "partner",
    "payment_method": "your_partner_code",
    "partner_code": "your_partner_code",
    "partner_reference_id": "PTR-20260603-001",
    "created_at": "2026-06-03T10:12:07+07:00"
  }
}

Untuk mitra eksternal, transaksi biasanya langsung SUCCESS (pembayaran sudah terjadi di platform mitra). Jika flow async, status awal PENDING + webhook follow-up.

6.7 Query Transaksi

GET /transactions

Query	Type	Keterangan
`status`	string	`PENDING`, `SUCCESS`, `EXPIRED`
`donation_id`	integer
`partner_reference_id`	string
`trx_id`	string
`date_from`, `date_to`	date	`Y-m-d`
`page`, `per_page`	integer

GET /transactions/{trx_id}

Detail transaksi by trx_id.

GET /transactions/history

Shortcut: hanya status=SUCCESS, sorted created_at desc.

7. Webhook ke Mitra (Outbound)

LAZISNU dapat mengirim notifikasi ke URL mitra saat status transaksi berubah.

POST {partner_webhook_url}

Headers dari LAZISNU

Content-Type: application/json
X-Lazisnu-Signature: sha256={hmac}
X-Lazisnu-Timestamp: 1718000000
X-Request-Id: uuid

Payload

{
  "event": "transaction.status_updated",
  "data": {
    "trx_id": "LZNU00011718000000",
    "partner_reference_id": "SHP-20260603-001",
    "status": "SUCCESS",
    "amount": 1000000,
    "payment_method": "your_partner_code",
    "paid_at": "2026-06-03T10:15:00+07:00",
    "donation": {
      "id": 58,
      "title": "Zakat Maal",
      "slug": "zakat_maal"
    }
  }
}

Expected response mitra: HTTP 200 dengan body { "received": true }

Retry policy LAZISNU: 3x exponential backoff (1m, 5m, 30m).

8. Idempotency

Header Idempotency-Key wajib untuk POST /transactions
Key yang sama + payload identik → return transaksi existing (200, bukan 201)
Key sama + payload berbeda → 409 Conflict

9. Best Practices Integrasi

Simpan trx_id dan partner_reference_id di database mitra untuk reconciliasi.
Gunakan webhook + polling (GET /transactions/{trx_id}) sebagai fallback.
Validasi amount server-side — jangan percaya nominal dari client tanpa verifikasi di mitra.
Whitelist campaign — mitra hanya bisa create transaksi untuk program yang diizinkan.
Log X-Request-Id di kedua sisi untuk support/debugging.
Rotate API key berkala; dukung 2 key aktif saat rotasi.
Sandbox — uji di staging sebelum production.
Timezone — semua datetime ISO8601 dengan offset +07:00 (WIB).

10. Lampiran

OpenAPI 3.0: openapi-mitra-eksternal.yaml
Postman Collection: API LAZISNU - Mitra Eksternal.postman_collection.json

11. Changelog

Versi	Tanggal	Perubahan
1.0.0	2026-06-03	Initial spec mitra eksternal

Dokumen Terkait