Sinyal konteks

Sebelum Anda mulai

Sinyal konteks mengevaluasi transaksi kredit yang telah selesai dan mengembalikan penilaian risiko — self-fraud atau social engineering — untuk memperkaya keputusan antifraud Anda sendiri.

Fitur ini melengkapi Verifikasi Kartu Tidak Hadir: fitur ini tidak mengubah kontrak atau perilaku endpoint transaksi yang sudah Anda gunakan. Anda tetap menerima status akhir transaksi (approved, inconclusive, dan sebagainya) seperti biasa, lalu melakukan query terhadap sinyal konteks.

Permintaan API Anda diautentikasi menggunakan token akses. Setiap permintaan yang tidak menyertakan token akses yang valid akan mengembalikan kesalahan. Pelajari lebih lanjut di Autentikasi.

Akses dikontrol oleh izin

Akses ke endpoint ini dikontrol oleh izin (role) yang diberikan kepada perusahaan Anda. Tanpa izin tersebut, endpoint ini mengembalikan 403. Minta pengaktifan kepada tim Unico.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Production: https://transactions.transactional.unico.app/api/public/v1

Dapatkan sinyal konteks

GET /transactions/{transaction_id}/signals — mengembalikan penilaian risiko dari transaksi yang telah selesai.

Hasilnya dihitung sebelumnya secara asinkron segera setelah transaksi mencapai status akhirnya, sehingga endpoint ini hanya berupa pencarian atas hasil yang sudah tersedia.

Parameter path

Parameter	Tipe	Wajib	Deskripsi
transaction_id	string	ya	ID transaksi (UUID v4). Contoh, 6ab1771e-dfab-4e47-8316-2452268e5481.

Header

Header	Nilai
Authorization	Bearer {token} — token akses yang valid.
Accept	application/json

Contoh permintaan

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Bidang	Tipe	Kehadiran	Deskripsi
signals.auto_fraud_risk	string (enum)	opsional	Tingkat risiko self-fraud. Hadir hanya jika terdeteksi.
signals.social_eng_risk	string (enum)	opsional	Tingkat risiko social engineering. Hadir hanya jika terdeteksi.
signals.more_info.limited_data	boolean	selalu	true jika data tidak cukup untuk penilaian yang andal.
signals.more_info.holder_identified	boolean	selalu	false jika pemegang kartu tidak dapat diidentifikasi.

Kemungkinan nilai risiko: very_low, low, medium, high, very_high.

informasi

auto_fraud_risk dan social_eng_risk saling eksklusif — keduanya tidak pernah muncul bersamaan dalam respons yang sama. Ketika limited_data bernilai true, kedua bidang risiko diperkirakan tidak ada, karena data tidak cukup untuk penilaian.

Contoh respons

Risiko social engineering terdeteksi:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Tidak ada risiko yang teridentifikasi — transaksi biasa:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Data tidak cukup:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Pemegang kartu tidak teridentifikasi:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Kode respons lainnya

Kesalahan dikembalikan dalam format kesalahan standar yang dijelaskan di Kesalahan.

Kode HTTP	Kode	Situasi	Yang harus dilakukan
202	—	Hasilnya belum dihitung — pemrosesan asinkron masih berlangsung.	Ulangi panggilan (polling) sampai Anda mendapatkan 200.
400	40004	transaction_id tidak valid (bukan UUID v4) atau parameter tidak valid formatnya.	Perbaiki format ID sebelum mengirim permintaan lagi.
403	40305	Perusahaan tidak memiliki izin (role) yang diaktifkan untuk endpoint ini.	Minta pengaktifan kepada tim Unico.
404	40401	Transaksi tidak ditemukan.	Periksa ID transaksi.
404	40484	Transaksi tidak ditemukan untuk penilaian.	Perlakukan sebagai "tidak akan ada hasil" dan hentikan query.
409	40983	Transaksi belum mencapai status akhirnya.	Tunggu status akhir sebelum melakukan query lagi.
500	—	Kesalahan layanan internal.	Coba lagi dengan backoff. Jika terus berlanjut, hubungi dukungan Unico.

Aturan dan praktik terbaik

• Lakukan query ke endpoint ini hanya setelah transaksi mencapai status akhirnya. Melakukan query lebih awal akan mengembalikan 409.
• Hanya transaksi kredit yang dinilai. Transaksi yang ditangkap dalam mode senyap tidak dinilai.
• Pada 202, ulangi panggilan sampai Anda mendapatkan 200. Kirim permintaan pertama 1 detik setelah respons transaksi, lalu backoff: 2s, 4s, 8s, 16s — hingga 5 percobaan.
• Service level objective-nya adalah 10 detik setelah respons transaksi.
• Perlakukan 404 sebagai "tidak akan ada hasil" dan hentikan query.
• auto_fraud_risk dan social_eng_risk saling eksklusif.