PaymentService - MerchantId

PaymentService adalah mesin rekonsiliasi. Ia membuat pembayaran dengan nominal unik, menurunkan QRIS dinamis, memindai feed transaksi, lalu menyelesaikan (settle) atau kedaluwarsakan (expire) pembayaran. Biasanya Anda mengaksesnya lewat provider.payments(), bukan mengonstruksinya langsung.

const service = gopay.payments();
service.on("paid", (p) => console.log("lunas", p.id));
service.start();
const payment = await service.createPayment({ amount: 25000 });

PaymentServiceOptions

Opsi	Tipe	Default	Kegunaan
`merchantId`	`string`	wajib	Merchant id pemilik pembayaran
`scope`	`PaymentScope`	`{provider:"gopay",merchantId}`	Kepemilikan untuk isolasi di store bersama; `scope.merchantId` wajib sama dengan `merchantId`
`store`	`PaymentStore`	wajib	Backend penyimpanan pembayaran
`transactions`	`TransactionLister`	-	Port transaksi offset-paginated (dipakai GoPay)
`transactionFeed`	`TransactionFeed`	-	Feed ternormalisasi (dipakai Shopee)
`staticQris`	`string`	-	QRIS statis untuk turunan QRIS dinamis per order
`allocator`	`AmountAllocator`	`new AmountAllocator()`	Alokator offset nominal unik
`pollIntervalMs`	`number`	`3000`	Interval polling background
`defaultExpiryMs`	`number`	`300000` (5 menit)	Masa berlaku default pembayaran
`clockSkewMs`	`number`	`60000` (1 menit)	Toleransi skew jam untuk matching, grace, dan karantina
`transactionPageSize`	`number`	`50`	Ukuran halaman feed (dibatasi maksimum 100)
`logger`	`Logger`	`noopLogger`	Logger terstruktur
`lifecycleToken`	`object`	-	Dipakai facade provider yang menahan service lintas scope

Konstruktor melempar CONFIG_INVALID bila transactions maupun transactionFeed tak diberikan, atau bila scope.merchantId tidak sama dengan merchantId.

CreatePaymentInput

interface CreatePaymentInput {
  amount: number; // base amount dalam rupiah penuh (integer positif)
  reference?: string; // referensi internal (order id, dll.)
  expiresInMs?: number; // override masa berlaku, harus finite
  metadata?: Record<string, unknown>;
}

Metode

Metode	Kembalian	Kegunaan
`createPayment(input)`	`Promise<Payment>`	Buat pembayaran pending nominal unik + QRIS (bila ada)
`getPayment(id)`	`Promise<Payment \| undefined>`	Ambil pembayaran milik scope ini
`cancelPayment(id)`	`Promise<Payment \| undefined>`	Batalkan pembayaran pending, lepas slot nominal
`tick()`	`Promise<{ paid: Payment[]; expired: Payment[] }>`	Satu putaran rekonsiliasi manual
`start()`	`void`	Mulai polling background (aman dipanggil sekali)
`stop()`	`void`	Hentikan polling background
`setStaticQris(qris)`	`void`	Set/lepas QRIS statis
`setTransactionFeed(feed)`	`void`	Ganti kredensial transport tanpa membuang replay guard
`get hasStaticQris`	`boolean`	Apakah QRIS statis dikonfigurasi
`get isRunning`	`boolean`	Apakah polling terjadwal
`get isActive`	`boolean`	Apakah service memegang lifecycle scope-nya
`activate(token?)`	`void`	Aktifkan ulang service yang ditahan
`deactivate(token?)`	`Promise<boolean>`	Cegah alokasi/rekonsiliasi baru dan tuntaskan antrian

createPayment memvalidasi amount sebagai integer positif dan expiresInMs sebagai angka finite; keduanya melempar CONFIG_INVALID bila invalid. Panggilan konkuren diserialisasi lewat write queue agar tidak ada dua order menerima nominal sama.

Event

PaymentService adalah event emitter dengan peta terketik:

interface PaymentServiceEvents {
  paid: [Payment];
  expired: [Payment];
  error: [Error];
}

service.on("paid", (payment) => {
  /* ... */
});
service.on("expired", (payment) => {
  /* ... */
});
service.on("error", (err) => {
  /* ... */
});

Listener yang melempar tidak menghentikan tick(); error-nya dialihkan ke channel error (kecuali listener error itu sendiri, agar tidak rekursif). Tersedia on, once, off, dan removeAllListeners.

Urutan rekonsiliasi

tick() menjalankan matching sebelum expiry secara sengaja: feed mengindeks transaksi dengan jeda, sehingga pembayar yang membayar dalam jendela bisa muncul setelah expiresAt lewat. Pembayaran baru di-expire setelah expiresAt + clockSkewMs - persis saat matcher berhenti menerima transaksi untuknya. Nominal yang dibebaskan masuk karantina 2 x clockSkewMs, dan transaksi yang sudah settle diingat lintas tick agar tak menyelesaikan pembayaran kedua. Lihat Model pembayaran.

Pencocokan

Fungsi murni yang diekspos untuk pengujian dan penggunaan lanjutan:

function matchesPayment(
  payment: Payment,
  transaction: MerchantTransaction,
  clockSkewMs: number,
): boolean;
function reconcile(
  payments: Payment[],
  transactions: MerchantTransaction[],
  clockSkewMs: number,
): Array<{ payment: Payment; transaction: MerchantTransaction }>;

reconcile menjamin at-most-one settlement per transaksi dalam satu pemanggilan. Lihat Model pembayaran dan QRIS dan alokasi.

​PaymentServiceOptions

​CreatePaymentInput

​Metode

​Event

​Urutan rekonsiliasi

​Pencocokan

PaymentServiceOptions

CreatePaymentInput

Metode

Event

Urutan rekonsiliasi

Pencocokan