Modes

payment mode

Displays a payment form based on a previously created Payment Order. The buyer pays an exact amount that was set server-side.

paygreenjs.init({
  publicKey: "pk_xxx",
  mode: "payment",
  paymentOrder: { id: "po_xxx", objectSecret: "xxx" },
  instrument: { id: "ins_fc6409dc32f248839295539623276cl98" }, // Optionnal
  paymentMethod: "bank_card", // Optionnal
});

Required:

• A Payment Order id and its single-use object secret.
• Your public key.

Optional:

• An instrument.id to pay with a saved instrument (one-click).
• A forced paymentMethod to skip the multi-method picker.

Emits:

• ACTUAL_FLOW_PAYMENT_DONE after a successful payment step (partial payment possible)
• FULL_PAYMENT_DONE once the total amount has been fully paid or authorized
• PAYMENT_FAIL when the terminal reports a failure.

instrument mode

Collects and stores payment information without charging the buyer immediately. The created instrument can be reused for one or more later payments.

paygreenjs.on(paygreenjs.Events.INSTRUMENT_READY, (event) => {
  console.log("Instrument created:", event.detail.id);
});

paygreenjs.init({
  publicKey: "pk_xxx",
  mode: "instrument",
  paymentMethod: "bank_card",
  buyer: { id: "buy_xxx" },
  modeOptions: { authorizedInstrument: true },
});

Required:

• Your public key.
• The paymentMethod to tokenize.
• buyer.id when authorizedInstrument is true

Optional:

• modeOptions.authorizedInstrument — create the instrument and authorize it in one call (with 3DS if required).
• modeOptions.shopId — marketplace setup: link the instrument to a sub-shop.

Emits INSTRUMENT_READY on success and INSTRUMENT_FAIL on failure.

Choosing the right mode

Synchronous Payment Flow

Buyer stays on your checkout page until the payment is taken.

How it works:

1. Initialize PGJS with your payment order.
2. The buyer enters their information and pays.
3. You receive updates via JS events and API hooks.

This flow requires no extra steps.

Instrument Flow (Saved Card)

Collect payment details now, charge later (or never).

How it works:

1. Initialize PGJS in instrument mode.
2. The buyer enters their payment details.
3. You get an instrument that can be used later to make a payment.

No charge is made because no payment order is linked.

Asynchronous Payment Flow

Collect the buyer’s payment information before creating the payment order.
For example, if you have a tips system, the final amount is unknown until the buyer enters it.

Solution: combine instrument and payment modes.

1. Initialize PGJS in instrument mode to get an instrument.
2. Create the payment order with the final amount (including tips).
3. Unmount and Re-initialize PGJS in payment mode and pass the previously obtained instrumentId.

The payment is then processed automatically using the instrument.