Better Payment

Parampos

Parampos (Param / TurkPOS) integration reference.

Parampos uses Param's TurkPOS SOAP service.

Configuration

import { betterPayment, parampos } from 'better-payment';

const payment = betterPayment({
  providers: {
    parampos: parampos({
      clientCode: process.env.PARAMPOS_CLIENT_CODE!,
      clientUsername: process.env.PARAMPOS_CLIENT_USERNAME!,
      clientPassword: process.env.PARAMPOS_CLIENT_PASSWORD!,
      guid: process.env.PARAMPOS_GUID!, // keep secret: callbacks are verified with it
      // baseUrl: defaults from mode (test-dmz.param.com.tr / posws.param.com.tr)
    }),
  },
});

Amounts and installments

  • price → Islem_Tutar, paidPrice → Toplam_Tutar (the amount charged, including installment commission). Amounts are sent with a decimal comma.
  • For installments, paidPrice must include the commission from your Param rates. Get it with calculatePaidPrice() (below); the library never guesses rates.
  • Only TRY is supported (TP_WMD_UCD). Other currencies return failure.

paymentId is your order id (Siparis_ID): the conversationId you pass, or a generated alphanumeric id.

Direct Payment (non-3D)

const result = await payment.parampos.createPayment({ ...paymentRequest, conversationId: 'ORDER123' });

3D Secure

const init = await payment.parampos.initThreeDSPayment({
  ...paymentRequest,
  conversationId: 'ORDER123',
  installment: 1,
  callbackUrl: 'https://yoursite.com/api/pay/parampos/payment/complete-3ds',
});
// Render init.threeDSHtmlContent (UCD_HTML)

Param POSTs md, mdStatus, orderId, islemGUID, islemHash, … to callbackUrl:

const result = await payment.parampos.completeThreeDSPayment(callbackBody);
  1. islemHash is verified with the GUID from your configuration. A GUID inside the callback is ignored.
  2. mdStatus must be 1.
  3. The payment is finalized with TP_WMD_Pay. It counts as success only when Param returns a Dekont_ID.

Refund, Cancel & Status

await payment.parampos.refund({ paymentId: 'ORDER123', price: '50.00', currency: 'TRY', ip: '1.2.3.4' });

// Same-day void. Param needs the full amount; without price it is looked up.
await payment.parampos.cancel({ paymentId: 'ORDER123', ip: '1.2.3.4' });

const status = await payment.parampos.getPayment('ORDER123'); // TP_Islem_Sorgulama4

BIN

const bin = await payment.parampos.binCheck('444676'); // BIN_SanalPos

Installments

installmentInfo() combines BIN_SanalPos (which card program the card belongs to) with TP_Ozel_Oran_SK_Liste (your customer-facing rates) and returns the available installment counts with Param's totals:

const info = await payment.parampos.installmentInfo({ binNumber: '435508', price: '100.00' });
// installmentPrices: [
//   { installmentNumber: 1, totalPrice: 101.75, installmentPrice: 101.75, commissionRate: 1.75 },
//   { installmentNumber: 3, totalPrice: 104.10, installmentPrice: 34.70, commissionRate: 4.1 },
//   ...
// ]

To charge with installments, compute paidPrice (Toplam_Tutar) the same way:

const paidPrice = await payment.parampos.calculatePaidPrice({
  binNumber: '435508',
  price: '250.00',
  installment: 3,
}); // '260.25'

await payment.parampos.initThreeDSPayment({ ...order, price: '250.00', paidPrice, installment: 3 });
  • Total: Toplam_Tutar = price + price × rate / 100, rounded half up to kuruş.
  • Installment counts with a negative rate (Param's "not available") are left out; calculatePaidPrice() throws a ValidationError for them.
  • When BIN_SanalPos returns DKK = 1, the "Diğer Banka Kartları" rates apply.
  • getInstallmentRates() returns the raw rate table of every card program.

On this page

ConfigurationAmounts and installmentsDirect Payment (non-3D)3D SecureRefund, Cancel & StatusBINInstallments