> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifikasi Dompet ID Digital via API

> Verifikasi identitas melalui dompet ID digital dari aplikasi Anda tanpa membuat alur kerja verifikasi. Didit menyediakan API ini.

Gunakan endpoint dompet khusus untuk memverifikasi seseorang dari aplikasi Anda sendiri.
Anda tidak perlu membuat atau mempublikasikan alur kerja, atau memberikan `workflow_id`.
Backend Anda memulai verifikasi dan mengambil hasilnya; antarmuka Anda memandu orang tersebut melalui autentikasi yang diwajibkan dompet.

> [!NOTE]
>
> Integrasi API tetap mengharuskan orang tersebut mengautentikasi dan menyetujui pembagian identitasnya.
> Anda tidak dapat memverifikasi seseorang dengan mengirimkan pengenal pribadinya tanpa interaksi tersebut.

## Cara kerja verifikasi

1. Backend Anda memeriksa [katalog dompet](https://docs.didit.me/id/standalone-apis/digital-id-wallet-catalog.md), lalu memanggil endpoint mulai milik dompet yang tersedia menggunakan kunci API aplikasi Anda.
2. Didit mengembalikan referensi verifikasi dan tindakan yang perlu dilakukan orang tersebut.
3. Aplikasi Anda membuka halaman autentikasi atau menampilkan instruksi persetujuan dari dompet.
4. Orang tersebut mengautentikasi diri dengan dompetnya.
5. Backend Anda mengambil hasil verifikasi dan menangani notifikasi penyelesaian.

Autentikasi dompet bersifat asinkron.
Permintaan mulai yang berhasil berarti autentikasi telah dimulai; itu tidak berarti identitas telah diverifikasi.
Selalu periksa hasil akhir sebelum memperlakukan orang tersebut sebagai terverifikasi.

## Integrasi backend

Gunakan [Daftar dompet identitas digital](https://docs.didit.me/id/standalone-apis/digital-id-wallet-catalog.md) untuk memperoleh endpoint, kolom wajib, dan ketersediaan terkini untuk aplikasi Anda.

Simpan `x-api-key` Anda di backend.
Jangan letakkan di bundle browser atau aplikasi seluler.
Gunakan `Idempotency-Key` yang berbeda untuk setiap percobaan verifikasi baru, dan gunakan kembali kunci tersebut saat mencoba ulang permintaan mulai yang sama.
Mengubah permintaan sambil menggunakan kembali kuncinya merupakan konflik, bukan percobaan verifikasi baru.

Setiap dompet memiliki URL mulai sendiri, misalnya `/v3/id-verification/wallets/ftn/` untuk Finnish Trust Network.
`request_id` mengidentifikasi verifikasi terpisah untuk operasi berikutnya.
Gunakan `vendor_data` sebagai referensi Anda sendiri, hingga 2.000 byte UTF-8, dan `metadata` untuk objek JSON opsional.
Keduanya dikembalikan bersama hasil dan webhook penyelesaian.

| Operasi | Endpoint |
| - | - |
| Baca status dan hasil | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Lakukan polling persetujuan telepon | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Kirim respons dompet Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Batalkan verifikasi yang tertunda | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Operasi ini menggunakan kunci API aplikasi yang memulai verifikasi.
Ketersediaan polling dan autentikasi bergantung pada dompet yang dipilih.

Pembatalan menolak verifikasi yang tertunda tanpa dikenai biaya, dan mengembalikan verifikasi yang sudah selesai tanpa perubahan.
Untuk Smart-ID dan Mobile-ID, pembatalan yang masuk saat polling sedang memeriksa persetujuan akan menunggu beberapa detik untuk polling tersebut.
Setelah itu, pembatalan menolak verifikasi, atau mengembalikannya sebagai `verified` jika orang tersebut sudah menyetujui.
Verifikasi yang sedang diselesaikan orang tersebut pada saat itu tidak dapat dibatalkan: responsnya adalah `409` dengan `error: "verification_in_progress"` dan header `Retry-After`.
Coba lagi setelah menunggu selama jumlah detik tersebut untuk membaca hasil yang telah selesai.

## Daftarkan tujuan pengembalian Anda

Dompet redirect mengembalikan orang tersebut ke aplikasi Anda setelah autentikasi.
Daftarkan nama host yang tepat sebelum memulai verifikasi:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

Lalu kirim `return_url` HTTPS, misalnya `https://app.example.com/identity/complete`, dalam permintaan mulai.
Gunakan nama host saja di `allowed_return_hosts`, tanpa skema, path, atau wildcard.
Daftarkan setiap subdomain yang Anda gunakan secara terpisah, hingga 20 nama host.
Memperbarui `allowed_return_hosts` menggantikan daftar yang terdaftar, jadi sertakan setiap nama host yang ingin Anda pertahankan.
`GET /v3/webhook/` mengembalikan daftar saat ini; lihat [Konfigurasi webhook](https://docs.didit.me/id/sessions-api/management-api.md#konfigurasi-webhook).
Anda tidak memerlukan alur kerja atau domain White Label untuk mendaftarkan tujuan pengembalian.
Tujuan tersebut adalah halaman pengembalian browser; konfigurasikan webhook penyelesaian secara terpisah untuk backend Anda.

## Contoh: Finnish Trust Network

Setelah mendaftarkan nama host pengembalian Anda, mulai verifikasi Finnish Trust Network:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

Simpan `request_id` yang dikembalikan dan kirim browser orang tersebut ke `wallet_verification.next_action.url` ketika `type`-nya `redirect`.
Setelah orang tersebut kembali, ambil hasilnya dari backend Anda:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Periksa `wallet_verification.outcome`:

| Hasil | Arti |
| - | - |
| `pending` | Autentikasi masih berlangsung. |
| `verified` | Autentikasi selesai dan identitas yang dikembalikan telah terverifikasi. |
| `cancelled` | Orang tersebut atau aplikasi Anda membatalkan percobaan. |
| `timeout` | Jendela autentikasi telah berakhir. |
| `failed` | Autentikasi atau validasi identitas gagal. |

Hanya gunakan identitas ketika hasil adalah `verified` dan `simulated` bernilai `false` untuk pemeriksaan identitas nyata.
Respons pending dapat memuat tindakan berikutnya; respons terminal tidak memiliki tindakan berikutnya.

## Pengalaman autentikasi

**Dompet dengan pengalihan** mengembalikan URL autentikasi.
Buka URL tersebut di browser pengguna, biarkan mereka menyelesaikan proses autentikasi dompet, lalu arahkan mereka kembali ke tujuan yang sudah Anda daftarkan.
Baca hasilnya dari backend Anda, jangan mempercayai parameter URL pengembalian sebagai bukti identitas.

**Smart-ID dan Mobile-ID** menggunakan permintaan persetujuan di ponsel pengguna.
Antarmuka Anda mengumpulkan pengenal pribadi yang diperlukan; Mobile-ID juga memerlukan nomor telepon yang terkait.
Tampilkan kode perbandingan dan minta pengguna menyetujui hanya jika kode tersebut sama dengan kode di ponsel mereka.
PIN mereka harus dimasukkan di dompet atau pada permintaan di ponsel, jangan pernah di formulir Anda atau dalam permintaan API.
Lakukan polling dari backend Anda pada `poll_interval_seconds` yang dikembalikan untuk mendapatkan umpan balik atas permintaan tersebut.
Didit juga memeriksa persetujuan telepon yang masih tertunda di latar belakang, sehingga penyelesaian dapat sampai ke webhook Anda setelah pengguna menutup halaman Anda.

**Google Wallet** diminta dari halaman atau aplikasi Anda sendiri melalui Digital Credentials API, tanpa redirect; lihat [Dompet Digital Credentials (Google Wallet)](#dompet-digital-credentials-google-wallet).

Interaksi yang tersedia bergantung pada dompet yang dipilih.
Jangan berasumsi bahwa setiap dompet mendukung formulir yang tertanam, kode QR, atau autentikasi tanpa browser.

## Dompet Digital Credentials (Google Wallet)

Google Wallet diminta langsung oleh halaman web atau aplikasi Android Anda, menggunakan W3C Digital Credentials API.
Tidak ada redirect, tidak ada halaman yang di-hosting Didit, dan tidak ada kode QR Didit.
Layanan ini tersedia di produksi dan di sandbox.
Aplikasi sandbox tidak memerlukan pendaftaran; setiap aplikasi produksi mendaftar sekali dari konsol (langkah Verifikasi Identitas, baris Google Wallet, **Daftar ke Google**) sebelum dapat menggunakan Google Wallet.
Periksa [Daftar dompet identitas digital](https://docs.didit.me/id/standalone-apis/digital-id-wallet-catalog.md) untuk mengetahui dompet mana yang dapat mulai digunakan oleh aplikasi Anda sekarang.

**1. Mulai dengan origin Anda**

Backend Anda memanggil `POST /v3/id-verification/wallets/google-wallet/` dengan `country` pengguna (`USA`, `GBR`, `BRA`, `SGP` atau `TWN`) dan `origin` yang akan digunakan untuk meminta dompet.
`origin` adalah origin HTTPS dari halaman Anda, misalnya `https://app.example.com`, yang host-nya harus salah satu dari [nama host pengembalian yang terdaftar](#daftarkan-tujuan-pengembalian-anda) atau domain White Label Anda.
Untuk aplikasi Android, nilainya adalah `android:apk-key-hash:` diikuti SHA-256 base64 dari sertifikat penandatanganan aplikasi Anda, tanpa padding.
Dompet menolak permintaan yang dibuat dari origin lain.
Tidak ada `return_url`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. Minta dompet di dalam gestur pengguna**

Respons memiliki `wallet_verification.interaction = "digital_credentials"` dan `next_action.type = "request_digital_credential"`.
Teruskan `next_action.digital_credentials.request` ke browser atau ke Android Credential Manager, dari ketukan atau klik pada `origin` yang Anda gunakan untuk memulai.
Di desktop, browser menampilkan kode QR-nya sendiri jika dompet berada di perangkat lain.

**3. Kirim respons dari dompet**

Kirim `{protocol, data}` yang dikembalikan ke backend Anda, lalu dari sana ke `POST /v3/id-verification/wallets/verifications/{request_id}/response/` sebagai `{"response": {...}}`.
Permintaan hanya dapat dikirim sekali; pengiriman kedua akan mengembalikan verifikasi yang sudah diputuskan.

**4. Baca hasilnya**

Respons pengiriman adalah verifikasi yang sudah diputuskan.
Anda juga dapat membacanya dengan `GET /v3/id-verification/wallets/verifications/{request_id}/` atau menerimanya di webhook penyelesaian.

Di browser, minta dompet dari penangan klik:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

Tawarkan metode ini hanya jika browser mendukungnya, misalnya ketika `"DigitalCredential" in window` bernilai true.
`navigator.credentials.get` harus berjalan dalam gestur pengguna, jadi panggil dari penangan klik, bukan setelah langkah asinkron.

Di Android, gunakan Jetpack Credential Manager (`androidx.credentials` 1.5.0 atau yang lebih baru) dengan permintaan yang sama:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Kesalahan yang perlu ditangani:

| Kesalahan | Tempat | Arti |
| - | - | - |
| `origin_invalid` | Mulai, `400` | `origin` bukan origin HTTPS atau origin aplikasi Android. |
| `origin_not_allowed` | Mulai, `400` | Host dari origin tidak terdaftar untuk aplikasi Anda. Daftarkan di `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Kirim, `409` | Verifikasi ini tidak menerima respons dari dompet. |

Kredensial yang gagal verifikasi berupa verifikasi yang sudah diputuskan dengan hasil `failed`, bukan respons error.
Hanya kolom yang diminta oleh verifikasi yang diberikan oleh dompet, dan hasilnya berisi atribut identitas yang dikembalikan dompet.
ID pass Google Wallet atau lisensi mengemudi seluler negara bagian AS tidak mengembalikan foto potret.

Di aplikasi sandbox, alur ini disimulasikan dengan langkah-langkah yang sama dan mengembalikan `simulated: true`.
Setiap respons yang dikirim akan memutuskan verifikasi sesuai `sandbox_scenario`, sehingga Anda dapat membangun alur browser atau aplikasi secara lengkap tanpa kredensial asli.

## Webhook penyelesaian

Konfigurasikan tujuan webhook aplikasi untuk `status.updated` menggunakan [panduan integrasi webhook](https://docs.didit.me/id/integration/webhooks.md).
Gunakan `webhook_version: "v3"` untuk struktur keputusan yang dijelaskan di sini.
Verifikasi tanda tangan webhook di backend Anda sebelum memprosesnya.
`session_id` pada webhook sama dengan `request_id` yang dikembalikan oleh API dompet.
Identitas pengguna yang telah selesai diverifikasi melalui dompet muncul dalam array `decision.id_verifications` pada webhook dengan `verification_method: "wallet"`.
Anda juga dapat menggunakan pengenal tersebut untuk mengambil hasil khusus dari API dompet.

Tangani notifikasi persetujuan dan penolakan, termasuk verifikasi yang dibatalkan dan kedaluwarsa.
Buat handler webhook Anda idempoten karena pengiriman yang gagal akan dicoba ulang.
Kembalinya pengguna dari browser bukan webhook penyelesaian, dan parameter query-nya bukan bukti identitas.

## Identitas yang dikembalikan

Gunakan kolom identitas yang dinormalisasi untuk nama dan tanggal lahir jika kolom tersebut dikembalikan.
Atribut khusus dompet menjelaskan informasi identitas yang dibagikan oleh dompet yang dipilih.
Atribut yang tersedia berbeda-beda menurut dompet dan negara.
Identitas yang terautentikasi tidak berarti bahwa potret, alamat, atau atribut lain yang diminta tersedia.

## Uji di sandbox

Aplikasi dalam mode sandbox Didit mensimulasikan verifikasi dompet tanpa menghubungi penyedia dompet atau membebankan kredit.
Respons menandai permintaan ini dengan `wallet_verification.simulated: true`.
Persetujuan simulasi adalah data contoh, bukan identitas dunia nyata yang telah diverifikasi.

Untuk dompet dengan pengalihan, ikuti URL yang dikembalikan untuk menguji callback dan kembali ke aplikasi Anda.
Untuk Smart-ID atau Mobile-ID, gunakan endpoint polling untuk menyelesaikan persetujuan simulasi; tidak ada notifikasi yang dikirim ke ponsel.
Untuk menguji penanganan kegagalan, atur `sandbox_scenario` ke `wallet_cancelled`, `wallet_timeout`, atau `wallet_provider_error` saat memulai permintaan.
Aplikasi produksi menolak `sandbox_scenario`.

Simulasi sandbox Didit terpisah dari pengujian terhadap lingkungan uji milik penyedia.
Simulasi yang berhasil tidak menetapkan akses ke penyedia produksi atau ketersediaan produksi.

### Sandbox penyedia ConnectID

Sandbox penyedia ConnectID menggunakan bank uji dan terpisah dari simulasi sandbox Didit.
Ketika akses sandbox penyedia dikonfigurasi untuk integrasi Anda, teruskan `authorisation_server_id` bank yang dipilih ke [endpoint untuk memulai ConnectID](https://docs.didit.me/id/api-reference/digital-id-wallets/connectid.md).
Gunakan ID yang dikembalikan oleh pemilih bank ConnectID; jangan kirim URL bank atau penerbit yang sembarang.
Jika kolom ini dihilangkan, bank uji default akan dipilih.
Kolom ini khusus untuk ConnectID dan tidak mengubah atribut identitas yang diminta.

Bundel awal meminta nama depan, nama belakang, dan tanggal lahir.
Ikuti `next_action` yang dikembalikan untuk melakukan autentikasi, lalu ambil hasil verifikasi atau lakukan polling.
Hanya hasil yang sudah selesai dengan status disetujui yang mengonfirmasi bahwa verifikasi berhasil; kembali ke aplikasi Anda tidak mengonfirmasi keberhasilan verifikasi.
ConnectID tetap berstatus **Segera hadir** di produksi selama onboarding dan sertifikasi masih berlangsung.

## Ketersediaan dan harga

Cakupan endpoint dan aktivasi dompet di produksi adalah dua hal yang terpisah.
Sebuah dompet dapat memiliki halaman referensi API sambil tetap tidak tersedia untuk autentikasi produksi.
Periksa cakupan negara dan status produksi dompet sebelum mengimplementasikan alur produksi.

Lihat [harga dompet ID digital](https://docs.didit.me/id/getting-started/pricing.md#harga-dompet-id-digital) untuk tarif dan ketersediaan yang dipublikasikan.
Verifikasi dompet ditagih terpisah dari pengambilan dokumen.

## Memilih integrasi

Gunakan API ini jika Anda ingin mengelola antarmuka dan logika aplikasi yang menyertainya.
Gunakan [Sessions API](https://docs.didit.me/id/sessions-api/create-session.md) jika Anda ingin alur verifikasi yang di-hosting oleh Didit, aturan alur kerja, dan langkah cadangan yang dikonfigurasi.
Kedua pendekatan tetap memerlukan proses autentikasi dan persetujuan pada dompet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.