Dokumentasi API H2H Kontera.ME

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).

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.

E-money bebas nominal (DANA, OVO, GoPay, ShopeePay, dan lain-lain)

Top up e-money dengan nominal bebas cukup satu langkah, tanpa cek tagihan. Kodenya adalah produk dengan "open_amount":true di daftar harga, misalnya DANAD (TOP UP DANA).

https://mitra.kontera.me/h2h/trx?product=DANAD&qty=50000&dest=081234567890&refID=INV9&memberID=[member ID]&sign=[sign]

• qty = nominal yang masuk ke akun e-money pelanggan, dalam rupiah. Yang dipotong dari saldo Anda = nominal + biaya, dengan biaya = price produk itu di daftar harga. Contoh: nominal 50.000 + biaya 340 = HRG:50340.
• Batas nominal per produk ada di daftar harga (min, max). Maksimal Rp500.000 per transaksi. qty kosong, 1, atau di luar batas ditolak (RC 47) dengan keterangan batasnya.
• qty tidak termasuk dalam sign (sama dengan OtomaX). Lewat https nilainya tidak bisa diubah di jalan.
• dest = nomor HP akun e-money (08…). Pastikan nomornya terdaftar di e-money tersebut. Kalau supplier menolak, transaksi gagal dan saldo kembali.
• Jawaban, status, cek ulang dengan refID yang sama, dan laporan (callback) sama dengan transaksi biasa:

R#INV9 DANAD.081234567890 SUKSES. SN:DNID DANA - 081234567890/BUD***/50000/SERIAL:2026101112345 TRXID:W1A2B3C4D5E HRG:50340 SALDO:449660 @2026-10-11 20:40:00
R#INV10 DANAD.081234567890 GAGAL. KET:Nominal top up untuk TOP UP DANA harus antara Rp1.000 dan Rp500.000. RC:47 SALDO:500000 @2026-10-11 20:41:00

Isi SN mengikuti format supplier e-money; contoh di atas hanya ilustrasi.

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

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):

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.

Produk pascabayar dengan nominal

• Top up e-money biasa memakai E-money bebas nominal di bagian 2 (satu langkah). Bagian ini hanya untuk produk yang di daftar harga bertanda "postpaid":true dan "open_amount":true.
• Untuk produk seperti itu, nominal 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.