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
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.
| Jalur | Metode HTTP | Tanda tangan |
|---|---|---|
| /h2h/trx/konteraya | GET, POST (JSON atau form) | SHA-256, mengunci semua isian. Disarankan. |
| /h2h/trx/otomax | GET | SHA-1 gaya OtomaX |
| /h2h/trx/otomax/trx | GET, POST | Untuk server OtomaX yang memasang Konteraya sebagai supplier |
Syarat
- Akun agen Konteraya. Kode agenmu dipakai sebagai
userid. - IP statis. Permintaan hanya diterima dari IP yang didaftarkan. Ganti IP, kabari CS lebih dulu.
- Password dan PIN H2H. Dibuat khusus untuk H2H, terpisah dari PIN aplikasi. Simpan hanya di server.
- URL report. Alamat di servermu untuk menerima hasil akhir transaksi.
- 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.
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.
nominalyang dikirim masuk ke posisinominaltrx.
<?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); 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'); 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.
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
$data = 'OtomaX|' . strtoupper($userid) . "|$kodeproduk|$tujuan|$reqid|$pin|$password";
$sign = rtrim(strtr(base64_encode(sha1($data, true)), '+/', '-_'), '='); 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).
| Nama | Contoh | Keterangan | |
|---|---|---|---|
| reqid | wajib | TRX001 | ID transaksi di servermu, paling panjang 40 karakter. Unik selamanya untuk akunmu. |
| userid | wajib | AG0001 | Kode agen Konteraya. |
| kodeproduk | wajib | S5 | Kode produk, sama persis dengan daftar harga. Alias: kode. |
| tujuan | wajib | 081234567890 | Nomor HP, ID pelanggan, atau nomor meter. 3 sampai 30 huruf atau angka. |
| jenistrx | pilihan | 1 | Jenis transaksi, bawaan 1. Lihat tabel jenis transaksi. |
| sign | wajib | lihat tanda tangan | Tanda tangan, metode konteraya atau otomax. |
| nominaltrx | pilihan | 100000 | Wajib untuk jenistrx 2 (nominal bebas). Alias: nominal. |
| qty | pilihan | 1 | Jumlah. Untuk produk nominal bebas, sama dengan nominal isi. |
| kodebayar | pilihan | 12345678901234 | Wajib untuk jenistrx 4. Didapat dari jawaban cek tagihan (jenistrx 3). |
| limitharga | pilihan | 6000 | Harga tertinggi yang mau kamu bayar. Lebih mahal, transaksi dibatalkan. |
| urlcallback | pilihan | https://mitra.example/cb | Alamat laporan balik untuk transaksi ini. Kosong = URL report akunmu. |
Jenis transaksi
| jenistrx | jenis | Untuk |
|---|---|---|
| 1 | fixed | Beli produk berharga tetap: pulsa, paket data, token, voucher. |
| 2 | open | Isi nominal bebas, misalnya saldo e-wallet. Wajib nominaltrx. |
| 3 | inquiry | Cek tagihan pascabayar tanpa membayar. Jawabannya membawa kodebayar. |
| 4 | payment | Bayar tagihan dengan kodebayar dari jenistrx 3. Kode produk dan tujuan harus sama dengan saat cek. |
| 5 | check | Cek akun, misalnya nama pemilik e-wallet. Gratis, hanya untuk produk Cek Akun dan Cek Tagihan. |
Tagihan pascabayar
- Kirim jenistrx 3 dengan reqid baru. Jawabannya berisi total tagihan dan
kodebayar. - Periksa total tagihan dan saldomu.
- Kirim jenistrx 4 dengan reqid baru, kode produk dan tujuan yang sama, dan
kodebayartadi. 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 /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 /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.
| jenis | Kunci, berurutan |
|---|---|
| fixed | reqid, status, jenis, kode, tujuan, harga, saldo, bukti, info, detail |
| open | reqid, status, jenis, kode, tujuan, nominal, harga, saldo, bukti, info, detail |
| inquiry | reqid, status, jenis, kode, tujuan, jmltag, totaltag, fee, potongsaldo, saldo, kodebayar, info, detail |
| payment | reqid, status, jenis, kode, tujuan, jmltag, totaltag, fee, potongsaldo, saldo, bukti, info, detail |
| check | reqid, status, jenis, kode, tujuan, saldo, info, detail |
status:pending,success, ataufailed.bukti: nomor seri (SN) dari operator, terisi saat sukses.hargadanpotongsaldo: yang dipotong dari saldomu.saldo: saldo sesudahnya.detail:DataTransaksi{…}DataBiaya{…}, butir dipisah||, selalu diakhiriKet:.
{"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{}"} {"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.
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
urlcallbackpermintaan 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.
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.
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
$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); 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.
- Alamat supplier:
https://ALAMAT/h2h/trx/otomax, tanpa garis miring di ujung. - memberID = kode agen Konteraya. PIN dan password = PIN dan password H2H.
- IP server OtomaX-mu didaftarkan, URL report diisi lewat CS.
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.
| status | Arti |
|---|---|
| 1 | Diterima, sedang diproses |
| 20 | Sukses |
| 40 | Gagal, sebab lain |
| 43 | Saldo kurang |
| 44 | Kode produk salah atau nonaktif |
| 45 | Stok kosong |
| 47 | Produk gangguan |
| 50 | Dibatalkan |
| 52 | Nomor tujuan salah |
| 61 | Jumlah atau nominal salah |
| 69 | Jam 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:
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#REFIDsupaya 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.
| errcode | Arti | OtomaX |
|---|---|---|
| SALDO_KURANG | Saldo tidak cukup. | 43 |
| PRODUK_TIDAK_DIKENAL | Kode produk tidak ada. | 44 |
| PRODUK_NONAKTIF | Produk sedang tidak dijual. | 44 |
| PRODUK_KOSONG | Stok produk kosong. | 45 |
| PRODUK_GANGGUAN | Produk sedang gangguan. | 47 |
| HARGA_BELUM_DIATUR | Harga produk belum diatur. | 47 |
| PREFIX_TIDAK_COCOK | Nomor tujuan tidak cocok dengan operator produk. | 52 |
| TUJUAN_TIDAK_SAH | Bentuk nomor tujuan salah. | 52 |
| CUTOFF | Produk sedang jam tutup. | 69 |
| NOMINAL_WAJIB | jenistrx 2 tanpa nominaltrx. | 61 |
| REQID_SUDAH_DIPAKAI | reqid sudah dipakai transaksi lain di akunmu. | 40 |
| DUPLIKAT_TANPA_COUNTER | Produk dan tujuan yang sama sudah terlalu sering dalam rentang waktu dobel. | 40 |
| MELEBIHI_LIMITHARGA | Harga lebih mahal dari limitharga. | 40 |
| INQUIRY_EXPIRED | kodebayar sudah kedaluwarsa. Cek tagihan lagi. | 40 |
| INQUIRY_USED | kodebayar sudah dipakai. | 40 |
| KODEBAYAR_BEDA_PRODUK | kodebayar milik produk lain. | 40 |
| KODEBAYAR_BEDA_TUJUAN | kodebayar milik tujuan lain. | 40 |
| URLCALLBACK_SALAH | urlcallback bukan alamat http atau https yang sah. | 40 |
| RATE_LIMIT | Terlalu banyak transaksi per menit. | 40 |
| LIMIT_HARIAN | Batas nominal harian akun tercapai. | 40 |
| PARAM_KURANG | Ada isian wajib yang kosong. | 40 |
| BUKAN_PRODUK_CEK | jenistrx 5 dengan produk berbayar. Untuk membeli, kirim jenistrx 1. | 40 |
| METODE_TIDAK_DIIZINKAN | Metode 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.
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:biayaditambahkan 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.
Tanya CS