Dokumentasi API H2H Kontera.ME

Versi 1 · format OtomaX

Untuk pemilik server (OtomaX, iRS, R-One, atau software sendiri) yang mengambil stok Kontera.ME. Format permintaan dan tanda tangannya sama dengan H2H OtomaX, jadi bisa dipasang tanpa koding.

1. Persiapan

Mitra didaftarkan oleh admin Kontera.ME. Anda membutuhkan akun member Kontera.ME. Saldo akun inilah yang dipotong untuk setiap transaksi, dan diisi lewat deposit seperti biasa. Dari admin Anda menerima:

Member ID, berbentuk KH diikuti 6 angka (contoh KH123456), plus PIN (6 angka) dan password. Simpan PIN dan password sebagai rahasia.
Pendaftaran IP server Anda. Permintaan dari IP lain selalu ditolak (RC 46). Sampaikan semua IP keluar server Anda ke admin, boleh juga rentang CIDR.
Opsional: URL callback Anda untuk menerima laporan status, lihat bagian 7. Izinkan IP laporan kami 45.136.71.49.

Semua alamat memakai https://. Permintaan http:// dialihkan ke https.

2. Transaksi

GET https://mitra.kontera.me/h2h/trx?product=[kode]&qty=1&dest=[tujuan]&refID=[id transaksi Anda]&memberID=[member ID]&sign=[sign]

POST juga diterima, dalam bentuk form atau JSON dengan nama parameter yang sama. Huruf besar/kecil pada nama parameter tidak berpengaruh (refID = refid).

Parameter	Wajib	Aturan
`product`	ya	Kode produk Kontera.ME (lihat daftar harga), 1–32 karakter `A–Z 0–9 . _ -`. Dibaca sebagai huruf besar.
`dest`	ya	Nomor/ID tujuan, 4–40 karakter `0–9 A–Z a–z . -`. Spasi dibuang. Nomor HP ditulis `08…` (tanpa `+62`).
`refID`	ya	ID transaksi di sistem Anda, unik, 4–64 karakter `A–Z a–z 0–9 . _ -`. Lihat bagian 4.
`memberID`	ya	Member ID Anda (4–16 huruf/angka).
`sign`	ya*	Tanda tangan, lihat bagian 3. *Sebagai ganti sign boleh dikirim `pin` dan `password` (hanya lewat https).
`qty`	tidak	Default `1`. Hanya produk bebas nominal yang memakai qty sebagai nominal (contoh `qty=50000`). Untuk produk lain qty selain 1 ditolak (RC 47).
`check`	tidak	`check=1` hanya menanyakan status refID, tidak pernah membuat transaksi.
`format`	tidak	`format=json` untuk jawaban JSON. Default jawaban berupa teks.

Server menjawab setelah supplier merespons. Biasanya beberapa detik, kadang lebih lama. Atur timeout klien Anda minimal 60 detik. Kalau koneksi putus atau habis waktu, kirim ulang dengan refID yang sama: itu aman dan tidak membuat transaksi kedua.

3. Tanda tangan (sign)

Sama dengan tanda tangan H2H OtomaX:

sign = base64url( sha1( "OtomaX|" + memberID + "|" + product + "|" + dest + "|" + refID + "|" + PIN + "|" + password , raw biner ) )

memberID dan product ditulis huruf besar. dest tanpa spasi. Nilainya harus persis sama dengan yang dikirim di URL.
Hash SHA-1 dalam bentuk biner (20 byte, bukan teks hex), lalu base64 URL-safe (+→-, /→_) tanpa =. Base64 biasa dan padding = juga diterima.

Contoh PHP

$sign = rtrim(strtr(base64_encode(sha1("OtomaX|$memberID|$product|$dest|$refID|$pin|$password", true)), '+/', '-_'), '=');
$url  = 'https://mitra.kontera.me/h2h/trx?' . http_build_query(compact('product', 'dest', 'refID', 'memberID', 'sign') + ['qty' => 1]);

Contoh Python

import base64, hashlib
raw  = f"OtomaX|{member_id}|{product}|{dest}|{ref_id}|{pin}|{password}".encode()
sign = base64.urlsafe_b64encode(hashlib.sha1(raw).digest()).decode().rstrip("=")

4. refID & cek status

Satu refID = satu transaksi. Kalau refID yang sama dikirim lagi, dengan produk dan tujuan apa pun, server tidak membuat transaksi baru. Jawabannya adalah status terkini transaksi pertama. Inilah cara cek status.
check=1 menanyakan status tanpa risiko membuat transaksi. Kalau refID belum pernah dipakai, jawabannya RC 44.
Status: sedang diproses → SUKSES (dengan SN) atau GAGAL. Transaksi yang gagal setelah saldo dipotong otomatis di-refund ke saldo Anda.
Kalau server kami tidak bisa memastikan transaksi dibuat (gangguan internal), statusnya tetap "sedang diproses" sampai jelas. Kalau setelah 10 menit transaksi memang tidak ada, statusnya menjadi GAGAL dengan keterangan "Transaksi tidak dibuat, silakan kirim ulang dengan refID baru". Dalam kasus ini saldo tidak dipotong.

5. Format jawaban

Teks (default)

R#ABC123 TEL10.081234567890 sedang diproses. TRXID:W1A2B3C4D5E HRG:11270 SALDO:488730 @2026-10-11 15:30:00
R#ABC123 TEL10.081234567890 SUKSES. SN:0412345678901234 TRXID:W1A2B3C4D5E HRG:11270 SALDO:488730 @2026-10-11 15:30:08
R#ABC124 TEL10.081234567890 GAGAL. KET:Nomor tujuan salah. RC:40 TRXID:W9F8E7D6C5B HRG:11270 SALDO:500000 @2026-10-11 15:31:02
R#ABC125 TEL10.081234567890 GAGAL. KET:Saldo tidak mencukupi. RC:42 SALDO:9000 @2026-10-11 15:32:10

Urutan bagian: R#refID, PRODUK.tujuan, status (sedang diproses. / SUKSES. / GAGAL.), lalu bila ada: SN: (sukses), KET: dan RC: (gagal), TRXID: (ID transaksi Kontera.ME), HRG: (harga yang dipotong), SALDO: (saldo Anda sekarang), dan @waktu (WIB).
Penolakan sebelum transaksi dibuat (misalnya saldo kurang atau produk tidak tersedia) tidak memuat TRXID dan HRG.
Saldo pada jawaban gagal bisa belum termasuk refund kalau refund masih berjalan. Laporan callback untuk transaksi gagal dikirim setelah refund selesai.

JSON (`format=json`)

{"success":true,"rc":"00","status":"success","refID":"ABC123","trxid":"W1A2B3C4D5E","product":"TEL10","dest":"081234567890",
 "sn":"0412345678901234","price":11270,"balance":488730,"msg":"R#ABC123 TEL10.081234567890 SUKSES. SN:… @2026-10-11 15:30:08"}

status bernilai processing, success, atau error. success bernilai false hanya bila status error. msg berisi jawaban teks yang sama.

6. Kode RC

RC	Arti	Status
`00`	Sukses	sukses
`68`	Sedang diproses, tunggu callback atau cek ulang dengan refID yang sama	diproses
`40`	Gagal (alasan di KET). Kalau saldo sudah dipotong, otomatis di-refund	gagal
`41`	Produk tidak tersedia: kode tidak ada, stok kosong, tidak dijual lewat H2H, atau tidak termasuk produk akun Anda	gagal
`42`	Saldo tidak mencukupi	gagal
`44`	refID tidak ditemukan (jawaban `check=1`), atau bayar tagihan tanpa cek tagihan dulu	gagal
`45`	Member ID salah/tidak aktif, sign salah, atau PIN/password salah	gagal
`46`	IP server Anda tidak terdaftar (IP-nya disebut di KET)	gagal
`47`	Parameter salah: refID, produk, tujuan, nominal bebas nominal di luar batas, qty untuk produk biasa, kode tagihan dikirim tanpa cek tagihan, atau hasil cek tagihan kedaluwarsa	gagal
`50`	Server sedang maintenance, coba lagi nanti	gagal

Untuk RC 41, 42, 44, 45, 46, 47, dan 50 tidak ada transaksi yang dibuat dan saldo tidak dipotong. Jawaban "sedang diproses" tidak menampilkan RC di teks, tetapi di JSON bernilai 68.

7. Laporan (callback)

Kalau URL callback Anda terdaftar, hasil akhir setiap transaksi dikirim ke URL itu:

GET [URL callback]?refid=ABC123&trxid=W1A2B3C4D5E&status=sukses&rc=00&product=TEL10&dest=081234567890
    &sn=0412345678901234&price=11270&balance=488730&message=[jawaban teks seperti bagian 5]

Pengirim: IP 45.136.71.49, User-Agent KonteraME-H2H/1.0. Parameter ditambahkan dengan ? atau & sesuai URL Anda.
status bernilai sukses atau gagal. Laporan hanya dikirim untuk status akhir, tidak untuk "diproses".
Setiap transaksi yang selesai dilaporkan, termasuk yang jawaban pertamanya sudah final dan yang ditolak setelah refID tercatat (misalnya saldo kurang). Laporan ganda untuk refID yang sama boleh diabaikan. Permintaan yang ditolak sebelum refID tercatat tidak dilaporkan, karena jawabannya sudah final: parameter salah (RC 47), produk tidak tersedia (RC 41), member ID/sign/IP salah (RC 45/46), dan maintenance (RC 50).
Transaksi gagal dilaporkan setelah saldonya di-refund, jadi balance sudah termasuk refund. Kalau refund belum selesai dalam 10 menit, laporan tetap dikirim.
Kalau status berubah setelah dilaporkan (misalnya dikoreksi admin), laporan baru dikirim dengan status terbaru.
Server Anda dianggap menerima bila menjawab HTTP 2xx dalam 10 detik. Kalau tidak, laporan dicoba lagi setelah 1, 5, 15, dan 60 menit, lalu berhenti. Selama itu Anda tetap bisa cek status dengan refID yang sama.

8. Cek saldo

GET https://mitra.kontera.me/h2h/trx?product=SALDO&dest=0&refID=[bebas]&memberID=[member ID]&sign=[sign]

Sign dihitung dengan product=SALDO serta dest dan refID yang dikirim. SAL atau S juga diterima. Cek saldo tidak membuat transaksi.

R#S1 SUKSES. SN:Saldo 488730 SALDO:488730 @2026-10-11 15:40:00

9. Daftar harga

GET https://mitra.kontera.me/h2h/price?memberID=[member ID]&sign=[sign]

Sign dihitung dengan product=PRICE, dest=0, refID=0, yaitu sha1("OtomaX|memberID|PRICE|0|0|PIN|password"). Boleh juga dengan pin dan password. Jawabannya selalu JSON:

{"success":true,"rc":"00","balance":488730,"count":2,"data":[
 {"code":"TEL10","name":"Telkomsel 10.000","category":"pulsa-reguler","brand":"TELKOMSEL","price":11270,"status":"tersedia"},
 {"code":"DANAD","name":"TOP UP DANA","category":"dompet-digital","brand":"BEBAS DENOM","price":340,"status":"tersedia",
  "open_amount":true,"min":10000,"max":500000,"note":"harga = nominal (qty) + biaya ini"}]}

price adalah harga untuk akun Anda saat ini. Harga bisa berubah, jadi ambil daftar ini secara berkala.
status bernilai tersedia atau kosong. Pesanan untuk produk kosong ditolak (RC 41).
Kalau admin membatasi produk untuk akun Anda, hanya produk itu yang tampil.

10. Pascabayar (tagihan)

Tagihan (PLN pascabayar, BPJS, PDAM, telepon/internet, angsuran, dan lain-lain) dibayar dalam dua langkah dengan refID yang sama: cek tagihan, lalu bayar. Kode tagihan yang dikirim sebagai transaksi biasa ditolak (RC 47).

Langkah 1 — cek tagihan (tidak memotong saldo)

Kirim seperti transaksi biasa, dengan salah satu penanda ini (pilih yang sesuai software Anda):

Gaya	Cek tagihan	Bayar
OtomaX (kode)	`product=CEK`+kode, mis. `CEKTAGPLN`	`product=BAYAR`+kode, mis. `BAYARTAGPLN` (`PAY`… juga diterima)
iRS / R-One	`product=TAGPLN&jenis=5`	`product=TAGPLN&jenis=6`
Parameter	`product=TAGPLN&cmd=inq`	`product=TAGPLN&cmd=pay`

dest = nomor/ID pelanggan. Sign dihitung dengan nilai product persis seperti yang dikirim (mis. CEKTAGPLN).

R#INV001 CEKTAGPLN.530000000001 CEK TAGIHAN SUKSES. SN:BUDI SANTOSO/Oktober 2026 NAMA:BUDI SANTOSO PERIODE:Oktober 2026 LEMBAR:1
  TARIF:R1/1300 TAGIHAN:300000 DENDA:0 ADMIN:2500 TOTAL:302500 BAYAR SEBELUM:20:15 HRG:301740 SALDO:500000 @2026-10-11 19:45:00

TOTAL = total resmi tagihan (tagihan + denda + admin biller). HRG = yang akan dipotong dari saldo Anda saat bayar.
Hasil cek berlaku 30 menit (lihat BAYAR SEBELUM). Cek ulang dengan refID yang sama selama masih berlaku menjawab tagihan yang sama, tanpa cek baru. Setelah kedaluwarsa, cek ulang dengan refID yang sama mengambil data terbaru.
Dengan format=json jawabannya memuat "type":"inquiry" dan objek bill: name, tarif, periode, lembar, tagihan, denda, admin, total, price, expires (unix time).
ID salah, tagihan sudah dibayar, atau tagihan belum tersedia dijawab GAGAL RC 40 dengan alasannya. Produk/layanan gangguan dijawab RC 41.

Langkah 2 — bayar

Kirim dengan refID, kode, dan nomor yang sama dengan cek tagihan. Yang dibayar adalah tagihan hasil cek itu, dan saldo dipotong sebesar HRG.
Jawaban dan laporan (callback) sama seperti transaksi biasa: sukses dengan SN (nomor referensi pembayaran), sedang diproses, atau gagal (saldo otomatis kembali). Mengirim bayar lagi dengan refID yang sama menjawab statusnya dan tidak membayar dua kali.
Bayar tanpa cek tagihan → RC 44. Kode/nomor berbeda dari cek tagihan, atau hasil cek sudah kedaluwarsa → RC 47.
Saldo kurang → RC 42. Hasil cek tetap tersimpan, jadi setelah isi saldo Anda bisa bayar lagi dengan refID yang sama selama belum kedaluwarsa.

E-money pascabayar (bebas nominal)

Untuk produk e-money pascabayar (misalnya DANA bebas nominal), nominal top up dikirim saat cek tagihan dengan amount= (atau qty=). Contoh: product=CEK[kode]&dest=08xxxxxxxxxx&amount=50000.
Bayar seperti tagihan biasa, dengan refID yang sama dan tanpa nominal. Yang dibayar adalah nominal hasil cek itu, dan jawabannya memuat NOMINAL:.
Batas nominal ada di daftar harga (open_amount, min, max). Nominal kosong atau di luar batas ditolak (RC 47). refID yang sudah dipakai dengan nominal lain juga ditolak (RC 47).

Di daftar harga, produk pascabayar ditandai "postpaid":true dan price-nya adalah biaya layanan. Harga final selalu dari cek tagihan.

11. Harga, saldo & produk

Setiap transaksi memotong saldo akun Anda sebesar harga H2H produk pada saat itu, yaitu nilai HRG/price. Untuk produk bebas nominal, yang dipotong adalah nominal (qty) ditambah biaya.
Saldo dipotong saat transaksi dibuat. Kalau transaksi gagal, saldo dikembalikan otomatis. Satu transaksi hanya bisa di-refund satu kali.
Kalau supplier utama gagal, server bisa memakai rute cadangan. Selama itu status tetap "sedang diproses".
Produk pascabayar dibayar lewat cek tagihan lalu bayar (bagian 10). Produk inject voucher dan produk manual tidak dijual lewat H2H dan selalu ditolak (RC 41).
Pesanan H2H tidak mendapat koin cashback dan tidak mendapat diskon referral. Promo tersebut khusus pengguna aplikasi.
Nominal produk bebas nominal minimal sesuai daftar harga (min, standar Rp10.000) dan maksimal Rp500.000.

12. Setelan di OtomaX

URL transaksi: https://mitra.kontera.me/h2h/trx. Kalau setelan OtomaX Anda meminta alamat dasar dan menambahkan /trx sendiri, isi https://mitra.kontera.me/h2h. Isi Member ID, PIN, dan password dari admin.
Cek status: OtomaX mengirim ulang refID yang sama, atau dengan check=1. Keduanya didukung.
Kata kunci parsing jawaban: SUKSES, GAGAL, sedang diproses, SN:, HRG:, SALDO:, TRXID:, R#.
URL report: URL report H2H di OtomaX Anda, didaftarkan oleh admin sebagai URL callback. Laporan memuat refid dan message (teks jawaban lengkap), plus parameter lain di bagian 7.

13. Keamanan

IP diperiksa lebih dulu, sebelum PIN atau sign. Permintaan dari IP yang tidak terdaftar selalu ditolak, meskipun datanya benar.
Utamakan sign. PIN dan password tidak pernah ikut terkirim saat memakai sign. Mode pin+password hanya diterima lewat https.
Kalau PIN atau password bocor, minta admin membuat yang baru. Data lama langsung tidak berlaku.
Simpan refID dan TRXID setiap transaksi untuk keperluan rekonsiliasi.

Butuh bantuan atau perubahan (IP, URL callback, daftar produk)? Hubungi admin Kontera.ME. Data rahasia hanya dikirim lewat jalur pribadi.