$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(10000, 'EGP'),
    targetOrigins: ['https://shop.test'],       // origin(s) that embed the widget
    orderReference: 'ORDER-123',                // reconcile — and default the charge idempotency key — off this
    allowedPaymentTypes: ['PANENTRY', 'GOOGLEPAY'], // cards + wallets (defaults to ['PANENTRY'])
));

// load the widget script from $session->clientLibrary (pin it with
// $session->clientLibraryIntegrity), then initialise the widget with
// the capture context in $session->jwt

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(15000, 'EGP'),
    orderReference: 'ORDER-124',
    returnUrl: 'https://shop.test/return',
    customer: new Customer(email: 'ada@shop.test'),
));

// redirect the payer to $session->redirectUrl

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(15000, 'EGP'),
    orderReference: 'ORDER-125',
    paymentMethod: 'card',
    options: new PaymobCheckoutOptions(integrationId: 111111, iframeId: 222222),
));

// redirect to $session->redirectUrl (the Paymob iframe)

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(25000, 'USD'),
    orderReference: 'ORDER-126',
    description: 'Gold Plan',
    returnUrl: 'https://shop.test/return',
    options: new PaylinkCheckoutOptions(iframe: true), // embeddable checkout URL
));

// embed $session->redirectUrl in an <iframe> (or redirect without the option)

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(12030, 'SAR'),
    orderReference: 'ORDER-127',
    returnUrl: 'https://shop.test/return',
    paymentMethod: 'invoice',      // 'invoice' | 'paylink' | 'managed' — selects the integration type
    options: new PaytabsCheckoutOptions(
        iframe: true,                       // embed the page in an <iframe> instead of redirecting
        tokenise: 2,                        // save the card as a reusable token
        agreement: new PaytabsAgreement(/* … */),  // repeat billing — PayTabs auto-bills the schedule
        splitPayout: [new PaytabsSplitPayout(/* … */)], // split the settled funds across beneficiaries
        webhookUrl: 'https://shop.test/ipn',
    ),
));

// redirect to $session->redirectUrl (hosted page); $session->reference is the tran_ref

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(10000, 'USD'),
    orderReference: 'ORDER-127',
    description: 'Gold Plan',
    returnUrl: 'https://shop.test/return', // PayPal redirects here after approval
    paymentMethod: 'authorize',        // omit to capture on approval (intent CAPTURE)
    options: new PayPalCheckoutOptions(  // typed options — no ambiguous array
        cancelUrl: 'https://shop.test/cancel',
        brandName: 'Example',
        userAction: PayPalUserAction::PayNow,
    ),
));

// redirect to $session->redirectUrl (PayPal approval page);
// $session->reference is the order id — pass it to charge() after approval

$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(25000, 'USD'),
    orderReference: 'ORDER-128',          // becomes the MPGS order id
    description: 'Goods and Services',
    options: new MpgsCheckoutOptions(
        operation: 'PURCHASE',               // PURCHASE | AUTHORIZE | VERIFY
        merchantName: 'Example LLC',
        returnUrl: 'https://shop.test/return',
    ),
));

// launch Hosted Checkout on the front end with $session->reference (the session id),
// loading the checkout script from $session->clientLibrary

// 1. Mint a capture context that tells the widget to auto-complete the payment.
$session = $gateway->createCheckoutSession(new CheckoutSessionRequest(
    money: Money::minor(10000, 'EGP'),
    targetOrigins: ['https://shop.test'],
    orderReference: 'ORDER-123',
    completeMandate: MandateCompletionType::Capture, // Capture (sale) | Auth (hold only)
));

// hand $session->jwt to checkout.mount(); it resolves with a signed result JWT.

// 2. Verify that result JWT against the capture context and trust the outcome.
$result = $gateway->confirmOrchestratedPayment(new ConfirmOrchestratedPaymentRequest(
    resultJwt: $resultJwt,                // returned by checkout.mount() on the front end
    captureContextJwt: $session->jwt, // source of the RS256 verification key (flx.jwk)
    expectedMoney: Money::minor(10000, 'EGP'),
    orderReference: 'ORDER-123',
));

// $result->status is Captured (Authorized for an AUTH mandate). For a real card,
// $result->instrumentIdentifierId / paymentInstrumentId / customerId are the reusable
// TMS token for later installments; a wallet sets $result->isWallet with no token.

$result = $gateway->charge(new ChargeRequest(
    transientToken: $tokenFromWidget,
    money: Money::minor(10000, 'EGP'),
    orderReference: 'ORDER-123', // = idempotency key
));

$result = $gateway->charge(new ChargeRequest(
    transientToken: $paymentToken, // Own Form browser-generated token
    money: Money::minor(9500, 'SAR'),
    orderReference: 'ORDER-127',
));

// 3-D Secure card → status Pending + $result->raw['redirect_url'] to send the payer

$result = $gateway->charge(new ChargeRequest(
    transientToken: $session->reference, // the approved PayPal order id
    money: Money::minor(10000, 'USD'),
    capture: true,                    // capture the order; false authorizes a hold instead
));

// status Captured (or Authorized when capture: false);
// $result->transactionId is the capture / authorization id for follow-ons

$result = $gateway->charge(new ChargeRequest(
    transientToken: $sessionId,        // the MPGS Hosted Session id holding the card
    money: Money::minor(10000, 'USD'),
    orderReference: 'ORDER-128',      // the MPGS order id
    idempotencyKey: 'txn-1',          // becomes the MPGS transaction id
));

// PAY → status Captured; capture: false authorises instead (AUTHORIZE)

$result = $gateway->charge(new ChargeRequest(
    transientToken: $opaqueDataValue, // the Accept.js opaqueData dataValue (nonce)
    money: Money::minor(5000, 'USD'),
    orderReference: 'ORDER-129',    // Authorize.Net invoiceNumber / refId
    capture: true,                 // false authorises only (authOnlyTransaction)
));

// status Captured (Authorized when capture: false); $result->transactionId is the transId

$outcomes = $reconciler->reconcile(GatewayName::CybersourceUnifiedCheckout, [
    '7040000000000000001',
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::Fawry, [
    'ORDER-124', 'ORDER-125',
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::Paymob, [
    '123456789',
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::Paylink, [
    'INV-0001',
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::Paytabs, [
    'TST2000000000001',
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::PayPal, [
    '7NK74838L4813105R', // a PayPal order id
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::Mpgs, [
    'ORDER-128', // MPGS order ids
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$outcomes = $reconciler->reconcile(GatewayName::AuthorizeNet, [
    '40000000001', // Authorize.Net transaction ids (transId)
]);

foreach ($outcomes as $outcome) {
    // $outcome->reconciled(), $outcome->snapshot?->status, $outcome->error
}

$result = $gateway->validatePayerAuth(new ValidatePayerAuthRequest(
    authenticationTransactionId: $authTxnId,
    money: Money::minor(10000, 'USD'),
    device: new BrowserDeviceData(
        ipAddress: $request->ip(),
        userAgent: $request->userAgent(),
        colorDepth: 24, screenHeight: 640, screenWidth: 480,
        language: 'en-US', timeZone: 273, javaScriptEnabled: true,
        challengeWindowSize: 'FULL_SCREEN',
    ),
));

$vaulted = $gateway->vaultInstrument(new TokenizeInstrumentRequest(/* … */));
// keep $vaulted->paymentInstrumentId

$vaulted = $gateway->vaultInstrument(new TokenizeInstrumentRequest(
    cardNumber: '4111111111111111',
    expirationMonth: '02',
    expirationYear: '2027',
));

// keep $vaulted->paymentInstrumentId (PayPal vault id) and $vaulted->customerId

$vaulted = $gateway->vaultInstrument(new TokenizeInstrumentRequest(
    cardNumber: '5123450000000008',
    expirationMonth: '05',
    expirationYear: '2027',
));

// keep $vaulted->paymentInstrumentId (the MPGS token)

$vaulted = $gateway->vaultInstrument(new TokenizeInstrumentRequest(
    cardNumber: '4111111111111111',
    expirationMonth: '05',
    expirationYear: '2027',
    billTo: new BillingAddress(     // PayLink requires the cardholder name + country/address/city
        firstName: 'Jane', lastName: 'Roe',
        country: 'SA', address1: '1 Main St', locality: 'Riyadh',
    ),
));

// keep $vaulted->paymentInstrumentId (the PayLink card token);
// revoke it later with $gateway->deleteToken($token)

$vaulted = $gateway->vaultInstrument(new TokenizeInstrumentRequest(
    transientToken: $opaqueDataValue, // Accept.js nonce — PAN-free (or pass cardNumber/expirationMonth/expirationYear)
));

// CIM profile ids: $vaulted->customerId (customerProfileId) + $vaulted->paymentInstrumentId (paymentProfileId)

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $vaulted->paymentInstrumentId,
    money: Money::minor(9900, 'EGP'),
    initiator: CredentialInitiator::Merchant, // MIT
));

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $savedToken, // token from a tokenise checkout
    money: Money::minor(50000, 'SAR'),
    initiator: CredentialInitiator::Merchant, // recurring; Customer → ecom
));

// create the token by passing new PaytabsCheckoutOptions(tokenise: 2) on any checkout

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $vaulted->paymentInstrumentId, // the PayPal vault id
    money: Money::minor(50000, 'USD'),
    initiator: CredentialInitiator::Merchant, // MIT → RECURRING; Customer → ONE_TIME
));

// vault the card first with vaultInstrument() to get $vaulted->paymentInstrumentId

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $vaulted->paymentInstrumentId, // the MPGS token
    money: Money::minor(10000, 'USD'),
    initiator: CredentialInitiator::Merchant, // MIT → adds the stored-credential agreement
    orderReference: 'ORDER-129',
));

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $vaulted->paymentInstrumentId, // the PayLink card token
    money: Money::minor(10000, 'USD'),
    initiator: CredentialInitiator::Merchant, // MIT rebill; Customer → CIT
    orderReference: 'ORDER-9',
));

// billing is reused from tokenize time — no cardholder/address is resent

$result = $gateway->chargeStoredCredential(new StoredCredentialChargeRequest(
    paymentInstrumentId: $vaulted->paymentInstrumentId, // CIM customerPaymentProfileId
    customerId: $vaulted->customerId,                 // CIM customerProfileId — required
    money: Money::minor(9900, 'USD'),
    initiator: CredentialInitiator::Merchant, // MIT → isSubsequentAuth; Customer → isStoredCredentials (CIT)
));