Masuk Unduh

Dokumen teknis H2H

Sambungkan server pulsamu ke Konteraya lewat HTTPS bertanda tangan atau OtomaX. Produknya sama dengan yang dijual di aplikasi.

  • HTTPS GET / POST
  • Jawaban JSON
  • Laporan bertanda tangan
  • OtomaX
KORA di samping rak server
Isi dokumen

Pengenalan

Server pulsamu mengirim permintaan HTTPS ke Pusat IP Konteraya. Setiap permintaan ditandatangani dengan password dan PIN H2H akunmu, jadi keduanya tidak pernah ikut terkirim. Hasil akhir transaksi dikirim balik ke URL report servermu.

Alamat dasarnya diberikan CS saat akun H2H diaktifkan. Di dokumen ini ditulis https://ALAMAT.

JalurMetode HTTPTanda tangan
/h2h/trx/konterayaGET, POST (JSON atau form)SHA-256, mengunci semua isian. Disarankan.
/h2h/trx/otomaxGETSHA-1 gaya OtomaX
/h2h/trx/otomax/trxGET, POSTUntuk server OtomaX yang memasang Konteraya sebagai supplier

Syarat

  1. Akun agen Konteraya. Kode agenmu dipakai sebagai userid.
  2. IP statis. Permintaan hanya diterima dari IP yang didaftarkan. Ganti IP, kabari CS lebih dulu.
  3. Password dan PIN H2H. Dibuat khusus untuk H2H, terpisah dari PIN aplikasi. Simpan hanya di server.
  4. URL report. Alamat di servermu untuk menerima hasil akhir transaksi.
  5. reqid unik. Setiap transaksi memakai reqid baru. reqid yang sama dianggap menanyakan transaksi yang sudah ada.

Salah tanda tangan berulang membuat kredensial H2H dikunci sementara, dan pemilik akun dikabari lewat WhatsApp.

Metode konteraya

SHA-256 atas delapan isian transaksi, kode agen, password, PIN, garam Konteraya, dan SERVER_ID dari CS. Semua isian ikut terkunci, jadi tidak bisa diubah di tengah jalan.

GETPOST/h2h/trx/konteraya
Rumus
bahan = reqid|kodeproduk|tujuan|qty|nominaltrx|urlcallback|limitharga|kodebayar:userid:password:pin:Konteraya|SERVER_ID
sign  = sha256(bahan), hex huruf kecil, 64 karakter

Contoh (nilai rekaan)
bahan = TRX001|S5|081234567890|||||:AG0001:Rahasia123:123456:Konteraya|contoh-server
sign  = c15e961bc951199ff2188d567a05ec79fcdd77d598dd72dd5682d1193cca2e3b
  • Selalu delapan isian dengan tujuh garis tegak sebelum titik dua. Isian yang tidak dikirim ditulis kosong.
  • Nilai ditulis persis seperti yang dikirim, tanpa diubah huruf besar kecilnya.
  • nominal yang dikirim masuk ke posisi nominaltrx.
PHP
<?php
// Isian yang tidak dikirim tetap ditulis kosong: selalu 8 isian sebelum titik dua.
$bahan = implode('|', [$reqid, $kodeproduk, $tujuan, $qty, $nominaltrx, $urlcallback, $limitharga, $kodebayar])
       . ":$userid:$password:$pin:Konteraya|$serverId";
$sign = hash('sha256', $bahan);
Node.js
const crypto = require('crypto');

// Isian yang tidak dikirim tetap ditulis kosong: selalu 8 isian sebelum titik dua.
const isian = [reqid, kodeproduk, tujuan, qty, nominaltrx, urlcallback, limitharga, kodebayar].map((x) => x ?? '');
const bahan = `${isian.join('|')}:${userid}:${password}:${pin}:Konteraya|${serverId}`;
const sign = crypto.createHash('sha256').update(bahan, 'utf8').digest('hex');
Python
import hashlib

# Isian yang tidak dikirim tetap ditulis kosong: selalu 8 isian sebelum titik dua.
isian = [reqid, kodeproduk, tujuan, qty, nominaltrx, urlcallback, limitharga, kodebayar]
bahan = "|".join(x or "" for x in isian) + f":{userid}:{password}:{pin}:Konteraya|{server_id}"
sign = hashlib.sha256(bahan.encode()).hexdigest()

Metode otomax

Untuk server yang sudah memakai tanda tangan gaya OtomaX. Hanya lewat GET.

GET/h2h/trx/otomax
Rumus
data = OtomaX|USERID|kodeproduk|tujuan|reqid|pin|password
sign = base64(sha1(data)), lalu "+" jadi "-", "/" jadi "_", "=" di ekor dibuang

USERID ditulis huruf besar. PIN mendahului password.

Contoh (nilai rekaan)
data = OtomaX|AG0001|S5|081234567890|TRX001|123456|Rahasia123
sign = hgvQCds-UubFgwgeGkwqgF9oERI

Metode ini hanya mengunci userid, kode produk, tujuan, dan reqid. Isian lain (jenistrx, qty, nominaltrx, urlcallback, limitharga, kodebayar) tidak ikut ditandatangani. Butuh isian itu, pakai metode konteraya, dan selalu kirim lewat HTTPS.

PHP
<?php
$data = 'OtomaX|' . strtoupper($userid) . "|$kodeproduk|$tujuan|$reqid|$pin|$password";
$sign = rtrim(strtr(base64_encode(sha1($data, true)), '+/', '-_'), '=');
Node.js
const crypto = require('crypto');

const data = `OtomaX|${userid.toUpperCase()}|${kodeproduk}|${tujuan}|${reqid}|${pin}|${password}`;
const sign = crypto.createHash('sha1').update(data, 'utf8').digest('base64')
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

Parameter

Lewat query string (GET), atau badan JSON maupun form (POST).

NamaContohKeterangan
reqidwajibTRX001ID transaksi di servermu, paling panjang 40 karakter. Unik selamanya untuk akunmu.
useridwajibAG0001Kode agen Konteraya.
kodeprodukwajibS5Kode produk, sama persis dengan daftar harga. Alias: kode.
tujuanwajib081234567890Nomor HP, ID pelanggan, atau nomor meter. 3 sampai 30 huruf atau angka.
jenistrxpilihan1Jenis transaksi, bawaan 1. Lihat tabel jenis transaksi.
signwajiblihat tanda tanganTanda tangan, metode konteraya atau otomax.
nominaltrxpilihan100000Wajib untuk jenistrx 2 (nominal bebas). Alias: nominal.
qtypilihan1Jumlah. Untuk produk nominal bebas, sama dengan nominal isi.
kodebayarpilihan12345678901234Wajib untuk jenistrx 4. Didapat dari jawaban cek tagihan (jenistrx 3).
limithargapilihan6000Harga tertinggi yang mau kamu bayar. Lebih mahal, transaksi dibatalkan.
urlcallbackpilihanhttps://mitra.example/cbAlamat laporan balik untuk transaksi ini. Kosong = URL report akunmu.

Jenis transaksi

jenistrxjenisUntuk
1fixedBeli produk berharga tetap: pulsa, paket data, token, voucher.
2openIsi nominal bebas, misalnya saldo e-wallet. Wajib nominaltrx.
3inquiryCek tagihan pascabayar tanpa membayar. Jawabannya membawa kodebayar.
4paymentBayar tagihan dengan kodebayar dari jenistrx 3. Kode produk dan tujuan harus sama dengan saat cek.
5checkCek akun, misalnya nama pemilik e-wallet. Gratis, hanya untuk produk Cek Akun dan Cek Tagihan.

Tagihan pascabayar

  1. Kirim jenistrx 3 dengan reqid baru. Jawabannya berisi total tagihan dan kodebayar.
  2. Periksa total tagihan dan saldomu.
  3. Kirim jenistrx 4 dengan reqid baru, kode produk dan tujuan yang sama, dan kodebayar tadi. Yang dibayar sama persis dengan hasil cek.

kodebayar berlaku terbatas, bawaannya 30 menit. Lewat dari itu, cek tagihan lagi.

Cek akun

Kirim jenistrx 5 dengan kode produk Cek Akun, misalnya untuk melihat nama pemilik e-wallet sebelum mengisi saldonya. Gratis, saldo tidak dipotong. Hasilnya datang di laporan akhir, di info dan detail. Produk berbayar yang dikirim dengan jenistrx 5 ditolak BUKAN_PRODUK_CEK tanpa dibeli.

Contoh permintaan

Nilai rekaan: userid AG0001, password Rahasia123, PIN 123456, SERVER_ID contoh-server.

GET, beli pulsa
GET /h2h/trx/konteraya?reqid=TRX001&userid=AG0001&kodeproduk=S5&tujuan=081234567890&jenistrx=1&sign=c15e961bc951199ff2188d567a05ec79fcdd77d598dd72dd5682d1193cca2e3b

GET /h2h/trx/otomax?reqid=TRX001&userid=AG0001&kodeproduk=S5&tujuan=081234567890&jenistrx=1&sign=hgvQCds-UubFgwgeGkwqgF9oERI
POST JSON, isi DANA nominal bebas
POST /h2h/trx/konteraya
Content-Type: application/json

{
  "reqid": "TRX002",
  "userid": "AG0001",
  "kodeproduk": "DANA",
  "tujuan": "081234567890",
  "jenistrx": 2,
  "nominaltrx": "100000",
  "urlcallback": "https://mitra.example/cb",
  "sign": "ecb279baecf808665356aef030d110f885bbc3164f39d3da61b0238c96811450"
}

bahan tanda tangan:
TRX002|DANA|081234567890||100000|https://mitra.example/cb||:AG0001:Rahasia123:123456:Konteraya|contoh-server

Jawaban

JSON satu baris. Urutan kunci tetap per jenis, jadi aman diurai dengan pola teks.

jenisKunci, berurutan
fixedreqid, status, jenis, kode, tujuan, harga, saldo, bukti, info, detail
openreqid, status, jenis, kode, tujuan, nominal, harga, saldo, bukti, info, detail
inquiryreqid, status, jenis, kode, tujuan, jmltag, totaltag, fee, potongsaldo, saldo, kodebayar, info, detail
paymentreqid, status, jenis, kode, tujuan, jmltag, totaltag, fee, potongsaldo, saldo, bukti, info, detail
checkreqid, status, jenis, kode, tujuan, saldo, info, detail
  • status: pending, success, atau failed.
  • bukti: nomor seri (SN) dari operator, terisi saat sukses.
  • harga dan potongsaldo: yang dipotong dari saldomu. saldo: saldo sesudahnya.
  • detail: DataTransaksi{…}DataBiaya{…}, butir dipisah ||, selalu diakhiri Ket:.
Diterima, masih diproses
{"reqid":"TRX001","status":"pending","jenis":"fixed","kode":"S5","tujuan":"081234567890","harga":5950,"saldo":494050,"bukti":"","info":"pending","detail":"DataTransaksi{Nama Produk:Telkomsel 5.000||Tujuan:081234567890||Ket:-}DataBiaya{}"}
Hasil cek tagihan (jenistrx 3)
{"reqid":"CEK01","status":"success","jenis":"inquiry","kode":"PLNPASCA","tujuan":"530000012345","jmltag":1,"totaltag":152500,"fee":0,"potongsaldo":152500,"saldo":500000,"kodebayar":12345678901234,"info":"ok success","detail":"DataTransaksi{Nama Produk:PLN Pascabayar||ID Pelanggan:530000012345||Nama Pelanggan:BUDI SANTOSO||Periode Bayar:NOV 2026||Ket:-}DataBiaya{Tagihan Awal:150000||Denda:0||Admin:2500||Total Tagihan:152500}"}

Galat

Penolakan transaksi dijawab HTTP 200 dengan status: error dan errcode, supaya tidak dikira gangguan jaringan lalu dikirim ulang. Penolakan identitas (IP, userid, tanda tangan) dijawab HTTP 403.

Contoh galat
HTTP 200
{"status":"error","errcode":"SALDO_KURANG","info":"SALDO_KURANG","reqid":"TRX003","kode":"S5","tujuan":"081234567890"}

HTTP 403
{"detail":"tanda tangan tidak cocok"}

HTTP 403
{"detail":"userid atau kredensial tidak dikenal"}

HTTP 403
{"status":"error","errcode":"ALAMAT_TIDAK_TERDAFTAR","info":"Alamat IP ini tidak terdaftar di pintu ini."}

Cek status dan saldo

Cek status = kirim ulang permintaan dengan reqid yang sama dan tanda tangan sah. Jawabannya keadaan transaksi itu sekarang; tidak ada transaksi kedua.

Saldo ikut di setiap jawaban. Cek saldo tersendiri tersedia lewat /h2h/trx/otomax/balance.

reqid berbeda untuk produk dan tujuan yang sama tetap diproses sebagai transaksi baru. Pastikan servermu tidak membuat reqid baru saat mengulang permintaan yang belum dijawab.

Laporan balik

  • Dikirim saat transaksi selesai: sukses, gagal, atau saldo dikembalikan. Status pending tidak dilaporkan.
  • Tujuannya urlcallback permintaan itu, atau URL report akunmu bila kosong.
  • POST, Content-Type: application/json, badannya sama dengan bentuk jawaban. Batas tunggu 10 detik.
  • Jawab dengan HTTP 2xx. Selain itu dicoba ulang beberapa kali dengan jeda makin panjang.
  • Laporan untuk reqid yang sama bisa datang lagi bila SN atau harga dikoreksi. Simpan yang terakhir.
Contoh laporan sukses
POST https://mitra.example/cb
Content-Type: application/json

{"reqid":"TRX001","status":"success","jenis":"fixed","kode":"S5","tujuan":"081234567890","harga":5950,"saldo":494050,"bukti":"0123456789012345","info":"success","detail":"DataTransaksi{Nama Produk:Telkomsel 5.000||Tujuan:081234567890||Ref:0123456789012345||Ket:-}DataBiaya{}"}

Periksa tanda tangan laporan

Setiap laporan membawa header X-Sign, dihitung dari badan laporan dan kredensial H2H akunmu. Tolak laporan yang tanda tangannya tidak cocok, lalu cocokkan reqid-nya dengan transaksi yang memang kamu kirim.

Rumus X-Sign
X-Sign = sha256(badan + ":" + userid + ":" + password + ":" + pin), hex huruf kecil, 64 karakter

badan = isi POST persis seperti diterima (JSON satu baris), jangan diurai lalu disusun ulang

Contoh (nilai rekaan, badan laporan sukses di atas)
X-Sign: 111440b1a17f2ae6489151f4f1fdf3bca6001178ce173ac41f09febe8e905b30
PHP
<?php
$badan = file_get_contents('php://input');
$harap = hash('sha256', "$badan:$userid:$password:$pin");
if (!hash_equals($harap, $_SERVER['HTTP_X_SIGN'] ?? '')) {
    http_response_code(403);
    exit;
}
$laporan = json_decode($badan, true);
// cocokkan $laporan['reqid'] dengan transaksi di servermu, lalu simpan status terakhirnya
http_response_code(200);
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();

// badan mentah, bukan hasil JSON.parse yang disusun ulang
app.post('/cb', express.text({ type: '*/*' }), (req, res) => {
  const badan = req.body;
  const harap = crypto.createHash('sha256').update(`${badan}:${userid}:${password}:${pin}`, 'utf8').digest('hex');
  if (harap !== req.get('X-Sign')) return res.sendStatus(403);
  const laporan = JSON.parse(badan);
  // cocokkan laporan.reqid dengan transaksi di servermu, lalu simpan status terakhirnya
  res.sendStatus(200);
});

Supplier di OtomaX

Server OtomaX bisa memasang Konteraya sebagai supplier berjenis OtomaX.

  1. Alamat supplier: https://ALAMAT/h2h/trx/otomax, tanpa garis miring di ujung.
  2. memberID = kode agen Konteraya. PIN dan password = PIN dan password H2H.
  3. IP server OtomaX-mu didaftarkan, URL report diisi lewat CS.
Permintaan dan jawaban
Alamat dasar supplier (tanpa garis miring di ujung):
https://ALAMAT/h2h/trx/otomax

Permintaan transaksi dari OtomaX:
GET /h2h/trx/otomax/trx?product=S5&qty=1&dest=081234567890&refID=TRX001&memberID=AG0001&sign=hgvQCds-UubFgwgeGkwqgF9oERI

Jawaban (teks):
status=1&message=R#TRX001 S5.081234567890 DITERIMA, sedang diproses. Harga: 5.950. Saldo: 494.050. TrxID: 123456 @14/11/26 10:57

Cek saldo:
GET /h2h/trx/otomax/balance?memberID=AG0001&sign=utTqzKua-JG81igrxleCcB5-tuI
data tanda tangan: OtomaX|CheckBalance|AG0001|123456|Rahasia123

Jawabannya teks status=KODE&message=KALIMAT. Baca kodenya, bukan kalimatnya; kalimat bisa berubah.

statusArti
1Diterima, sedang diproses
20Sukses
40Gagal, sebab lain
43Saldo kurang
44Kode produk salah atau nonaktif
45Stok kosong
47Produk gangguan
50Dibatalkan
52Nomor tujuan salah
61Jumlah atau nominal salah
69Jam tutup

Mengirim ulang refID yang sama menanyakan statusnya: masih berjalan dijawab 1, sukses 20, gagal 40 atau kode sebabnya. Hasil akhir juga dikirim ke URL report lewat GET:

Laporan ke URL report
GET <URL report>?t=105830&qty=1&refid=TRX001&dest=081234567890&status=20&sn=0123456789012345&price=5950&memberID=AG0001&message=R#TRX001 S5.081234567890 SUKSES. SN: 0123456789012345. ...

Belum tersedia lewat jalur OtomaX: tiket deposit dan tagihan pascabayar. Pakai jalur HTTPS untuk tagihan.

Jabber dan WhatsApp

Transaksi juga bisa dikirim sebagai pesan dari akun Jabber (XMPP) atau nomor WhatsApp yang didaftarkan di akunmu. Format perintahnya sama dengan agen biasa, dan balasannya datang di percakapan yang sama.

  • Akun Jabber Konteraya dan daftar format perintah yang aktif diberikan CS.
  • Pakai R#REFID supaya balasan bisa dicocokkan. refid 1 sampai 20 huruf, angka, garis bawah, atau tanda minus.
  • R# yang sama dikirim lagi tidak diproses ulang: masih berjalan dijawab sedang diproses, sudah selesai dijawab refid sudah dipakai.

Untuk volume besar, pakai jalur HTTPS.

Kode galat

Nilai errcode di jalur HTTPS dan kode status padanannya di jalur OtomaX.

errcodeArtiOtomaX
SALDO_KURANGSaldo tidak cukup.43
PRODUK_TIDAK_DIKENALKode produk tidak ada.44
PRODUK_NONAKTIFProduk sedang tidak dijual.44
PRODUK_KOSONGStok produk kosong.45
PRODUK_GANGGUANProduk sedang gangguan.47
HARGA_BELUM_DIATURHarga produk belum diatur.47
PREFIX_TIDAK_COCOKNomor tujuan tidak cocok dengan operator produk.52
TUJUAN_TIDAK_SAHBentuk nomor tujuan salah.52
CUTOFFProduk sedang jam tutup.69
NOMINAL_WAJIBjenistrx 2 tanpa nominaltrx.61
REQID_SUDAH_DIPAKAIreqid sudah dipakai transaksi lain di akunmu.40
DUPLIKAT_TANPA_COUNTERProduk dan tujuan yang sama sudah terlalu sering dalam rentang waktu dobel.40
MELEBIHI_LIMITHARGAHarga lebih mahal dari limitharga.40
INQUIRY_EXPIREDkodebayar sudah kedaluwarsa. Cek tagihan lagi.40
INQUIRY_USEDkodebayar sudah dipakai.40
KODEBAYAR_BEDA_PRODUKkodebayar milik produk lain.40
KODEBAYAR_BEDA_TUJUANkodebayar milik tujuan lain.40
URLCALLBACK_SALAHurlcallback bukan alamat http atau https yang sah.40
RATE_LIMITTerlalu banyak transaksi per menit.40
LIMIT_HARIANBatas nominal harian akun tercapai.40
PARAM_KURANGAda isian wajib yang kosong.40
BUKAN_PRODUK_CEKjenistrx 5 dengan produk berbayar. Untuk membeli, kirim jenistrx 1.40
METODE_TIDAK_DIIZINKANMetode ini tidak dibuka untuk akunmu. Pakai konteraya atau otomax.40

Penolakan identitas: ALAMAT_TIDAK_TERDAFTAR (IP belum didaftarkan), "userid atau kredensial tidak dikenal", "tanda tangan tidak cocok", dan kredensial yang sedang dikunci karena salah berulang. Semuanya HTTP 403.

Daftar harga

Harga untuk akunmu ada di tautan daftar harga khusus. Minta tautannya ke CS. Halamannya menulis kode, keterangan, harga, dan status tiap produk, dan bisa dibuka tanpa login.

Untuk menyamakan katalog dan harga di servermu secara otomatis, tambahkan /json di ujung tautan itu. Paling banyak 10 permintaan per menit, isinya diperbarui tiap 30 detik.

Daftar harga JSON
GET https://ALAMAT/harga/TOKEN/json

{"kode_agen":"AG0001","diperbarui":"2026-11-14T21:00:00+07:00","provider":[
 {"kode":"SP","nama":"Telkomsel Pulsa Reguler","produk":[
  {"kode":"S5","nama":"Pulsa Telkomsel 5.000","jenis":"tetap","harga":5950,"biaya":null,"status":"Open"},
  {"kode":"S10","nama":"Pulsa Telkomsel 10.000","jenis":"tetap","harga":10900,"biaya":null,"status":"Gangguan"}]},
 {"kode":"PLNPASCA","nama":"PLN Pascabayar","produk":[
  {"kode":"PLNPASCA","nama":"PLN Pascabayar","jenis":"tagihan","harga":null,"biaya":2500,"status":"Open"}]}]}
  • tetap: harga = yang dipotong dari saldo.
  • nominal: biaya ditambahkan di atas nominal yang diketik.
  • tagihan: biaya = admin di atas total tagihan.
  • cek: gratis.
  • status: Open, Gangguan, atau Kosong.

Gambaran umum harga ada di halaman Produk.

Bantuan

Untuk aktivasi akun H2H, pendaftaran IP, URL report, dan pertanyaan integrasi, hubungi CS. Siapkan kode agen, IP server, dan reqid transaksi yang ditanyakan.

Kembali ke halaman Server pulsa · Kontak CS

Tanya CS