Area API

Test on Postman

Endpoint pencarian baca-saja (read-only) untuk wilayah administratif Indonesia (Provinsi, Kota, Kecamatan, Kelurahan).

LINGKUNGAN API

Endpoint

GET
Provinceshttps://sandbox.ipaymu.com/api/areas/province
GET
Citieshttps://sandbox.ipaymu.com/api/areas/city/{province}
GET
Districtshttps://sandbox.ipaymu.com/api/areas/district/{city}
GET
Villageshttps://sandbox.ipaymu.com/api/areas/village/{district}

Gunakan kredensial sesuai lingkungan yang dipilih. Kredensial Sandbox dan Production berbeda.

Endpoint pencarian baca-saja (read-only) untuk wilayah administratif Indonesia: Provinsi → Kota/Kabupaten → Kecamatan → Kelurahan/Desa. Biasanya digunakan untuk mengisi dropdown bertingkat (misalnya formulir alamat, verifikasi, pengiriman).

Daftar ini bersifat hierarkis: pilih provinsi untuk mendapatkan kota/kabupatennya, pilih kota/kabupaten untuk mendapatkan kecamatannya, dan seterusnya. Setiap endpoint mengembalikan kode wilayah (code) yang digunakan sebagai parameter untuk tingkat berikutnya di bawahnya.


Base URL

Lingkungan (Environment)Base URL
Productionhttps://my.ipaymu.com/api
Sandboxhttps://sandbox.ipaymu.com/api
ⓘ

Sesuaikan dengan deployment Anda. Secara lokal ini dipetakan ke {APP_URL}/api.

Semua endpoint Area berada di bawah prefiks /areas.


Autentikasi

Setiap permintaan harus ditandatangani. Middleware tanda tangan (signaturecheck) memerlukan header HTTP berikut:

HeaderWajibTipeContoh / nilaiDeskripsi
va✅ YastringYOUR_IPAYMU_VANomor Virtual Account (baccount) dari menu Integrasi Production atau Sandbox. Gunakan sesuai environment request.
signature✅ Yastring (64 karakter heksadesimal)GENERATED_SIGNATUREHasil HMAC-SHA256 untuk request ini (lihat di bawah), memakai API Key dari menu Integrasi Production atau Sandbox. Jangan kirim API Key sebagai nilai header.
timestampDirekomendasikanstring (14 digit)20260102153045Waktu request dalam format YYYYMMDDHHmmss (2 Januari 2026 pukul 15:30:45).
Content-Type✅ Yastringapplication/jsonTipe MIME untuk request JSON.

Akun yang terikat dengan va harus aktif dan memiliki kunci API (API key).

Pembuatan Tanda Tangan (Signature)

requestBody  = lowercase( sha256( <raw request body> ) )
stringToSign = <HTTP_METHOD> + ":" + <VA> + ":" + requestBody + ":" + <API_KEY>
signature    = hmac_sha256( stringToSign, <API_KEY> )

Catatan:

  • <HTTP_METHOD> harus berhuruf besar (GET).
  • Untuk permintaan tanpa body (semua endpoint GET Area), gunakan objek JSON kosong {} sebagai body saat melakukan hash — yaitu requestBody = sha256("{}").
  • <API_KEY> digunakan baik sebagai bagian dari stringToSign maupun sebagai kunci rahasia HMAC.

Contoh Kode Pembuatan Signature

const crypto = require('crypto');

const va = 'YOUR_IPAYMU_VA';
const apiKey = 'YOUR_API_KEY';
const method = 'GET';

const body = '{}';
const requestBody = crypto.createHash('sha256').update(body).digest('hex').toLowerCase();
const stringToSign = `${method}:${va}:${requestBody}:${apiKey}`;
const signature = crypto.createHmac('sha256', apiKey).update(stringToSign).digest('hex');
const timestamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);

Struktur Respon (Response Envelope)

Semua respon menggunakan wrapper yang sama:

{
  "Status": 200,
  "Success": true,
  "Message": "Success",
  "Data": []
}
FieldTipeDeskripsi
StatusintegerKode status HTTP, dicerminkan dalam body.
Successbooleantrue jika berhasil, false jika terjadi kesalahan.
MessagestringPesan yang dapat dibaca manusia.
Dataarray | nullPayload hasil (array objek wilayah).

Daftar Endpoint

1. Dapatkan Provinsi (Get Provinces)

Mengembalikan semua provinsi, diurutkan berdasarkan nama (A→Z).

GET /areas/province

Parameter: tidak ada

Contoh permintaan

curl --location 'https://sandbox.ipaymu.com/api/areas/province' \
  --header 'Content-Type: application/json' \
  --header 'va: YOUR_IPAYMU_VA' \
  --header 'signature: <generated-signature>' \
  --header 'timestamp: 20260629103000'

Contoh respon 200 OK

{
  "Status": 200,
  "Success": true,
  "Message": "Success",
  "Data": [
    { "code": "11", "name": "ACEH" },
    { "code": "51", "name": "BALI" },
    { "code": "36", "name": "BANTEN" }
  ]
}

2. Dapatkan Kota berdasarkan Provinsi (Get Cities by Province)

Mengembalikan kota/kabupaten milik suatu provinsi.

GET /areas/city/{province}

Parameter path

ParameterTipeDeskripsi
provincestringKode provinsi (code dari endpoint Provinsi).

Contoh permintaan

curl --location 'https://sandbox.ipaymu.com/api/areas/city/51' \
  --header 'Content-Type: application/json' \
  --header 'va: YOUR_IPAYMU_VA' \
  --header 'signature: <generated-signature>' \
  --header 'timestamp: 20260629103000'

Contoh respon 200 OK

{
  "Status": 200,
  "Success": true,
  "Message": "Success",
  "Data": [
    { "code": "5171", "name": "KOTA DENPASAR" },
    { "code": "5103", "name": "KABUPATEN BADUNG" }
  ]
}

3. Dapatkan Kecamatan berdasarkan Kota (Get Districts by City)

Mengembalikan kecamatan milik suatu kota/kabupaten.

GET /areas/district/{city}

Parameter path

ParameterTipeDeskripsi
citystringKode kota/kabupaten (code dari endpoint Kota/Kabupaten).

Contoh permintaan

curl --location 'https://sandbox.ipaymu.com/api/areas/district/5171' \
  --header 'Content-Type: application/json' \
  --header 'va: YOUR_IPAYMU_VA' \
  --header 'signature: <generated-signature>' \
  --header 'timestamp: 20260629103000'

Contoh respon 200 OK

{
  "Status": 200,
  "Success": true,
  "Message": "Success",
  "Data": [
    { "code": "517101", "name": "DENPASAR SELATAN" },
    { "code": "517102", "name": "DENPASAR TIMUR" }
  ]
}

4. Dapatkan Kelurahan berdasarkan Kecamatan (Get Villages by District)

Mengembalikan kelurahan/desa milik suatu kecamatan. Objek kelurahan/desa juga menyertakan kode pos.

GET /areas/village/{district}

Parameter path

ParameterTipeDeskripsi
districtstringKode kecamatan (code dari endpoint Kecamatan).

Contoh permintaan

curl --location 'https://sandbox.ipaymu.com/api/areas/village/517101' \
  --header 'Content-Type: application/json' \
  --header 'va: YOUR_IPAYMU_VA' \
  --header 'signature: <generated-signature>' \
  --header 'timestamp: 20260629103000'

Contoh respon 200 OK

{
  "Status": 200,
  "Success": true,
  "Message": "Success",
  "Data": [
    { "code": "5171011001", "name": "SANUR", "postal_code": "80227" },
    { "code": "5171011002", "name": "RENON", "postal_code": "80226" }
  ]
}

Referensi Field

Provinsi / Kota / Kecamatan

FieldTipeDeskripsi
codestringKode wilayah. Gunakan sebagai parameter path untuk tingkat berikutnya.
namestringNama wilayah.

Kelurahan / Desa (sama seperti di atas, ditambah)

FieldTipeDeskripsi
postal_codestring | nullKode pos (null jika tidak tersedia).

Respon Error

Pada kegagalan autentikasi, permintaan ditolak sebelum mencapai kontroler:

StatusPesanPenyebab
401invalid header param - va is requiredHeader va tidak ditemukan.
401invalid header param - signature is requiredHeader signature tidak ditemukan.
401unauthorized credentialva tidak ditemukan, akun tidak aktif, atau tidak ada kunci API.
401unauthorized signatureSignature tidak cocok.

Contoh respon error

{
  "Status": 401,
  "Success": false,
  "Message": "unauthorized signature",
  "Data": null
}
ⓘ

Permintaan yang valid untuk kode yang tidak memiliki anak (atau kode yang tidak dikenal) mengembalikan 200 dengan array Data kosong ([]).


Catatan

  • Metode: Didokumentasikan sebagai GET. Rute menerima metode HTTP apa pun, tetapi gunakan GET secara konsisten agar cocok dengan metode yang digunakan dalam tanda tangan (signature) Anda.
  • Caching: Data wilayah bersifat statis; lakukan caching respon pada klien untuk mengurangi panggilan.
  • Pengurutan: Provinsi dikembalikan A→Z berdasarkan nama. Kota, kecamatan, dan kelurahan dikembalikan dalam urutan alami database.

On this page