Skip to main content
CardPay displays a card entry form where customers enter their card details. The form handles validation, formatting, and card brand detection automatically.
For general setup instructions, see Library Setup.

​
Availability

CardPay is available in all browsers. It appears in checkAvailability() results when a payment gateway account is configured in the session. 
const available = await engine.checkAvailability();
// CardPay is typically always available

​
Button Setup

<div id="card-button"></div>

engine.payBy(
  [{ name: 'CardPay', domEntitySelector: '#card-button' }],
  handleResult,
  undefined
);

​
What the Form Collects

The CardPay popup form collects:
  • Card number (with formatting and brand detection)
  • Expiration date
  • CVV/CVC
  • Cardholder name
The library validates input in real-time and detects the card brand (Visa, Mastercard, Amex, etc.) from the card number.

​
Supported Operations

OperationSupported
CHARGEYes
TOKENIZEYes
CHARGE_AND_TOKENIZEYes

​
Result Handling

​
Charge Results

When the session operation is CHARGE, results come through upgChargeResults: 
const [data] = engine.parseResultToken(result.token);

if (data.upgChargeResults) {
  const charge = data.upgChargeResults;
  console.log('Gateway:', charge.gatewayName);
  console.log('Reference:', charge.gatewayReference);
  console.log('Auth code:', charge.authorizationCode);
  console.log('Result:', charge.operationResultCode);  // "Success", "Rejected", etc.
}

​
Tokenization Results

When the session operation is TOKENIZE or CHARGE_AND_TOKENIZE, results include tokenAndMaskedCardModel: 
const [data] = engine.parseResultToken(result.token);

if (data.tokenAndMaskedCardModel) {
  const token = data.tokenAndMaskedCardModel;
  console.log('Token:', token.token);
  console.log('Card type:', token.bankCard.type);       // "Visa", "Mastercard"
  console.log('Masked number:', token.bankCard.number); // "************1234"
  console.log('Expires:', token.bankCard.expirationMonth + '/' + token.bankCard.expirationYear);
  console.log('Name:', token.bankCard.nameOnCard);
}

​
3D Secure

CardPay automatically triggers 3D Secure authentication when required. The library handles the challenge flow (popup or iframe) without additional code. After 3DS completes, the result includes authentication data: 
if (data.tokenAndMaskedCardModel?.threeDs) {
  const tds = data.tokenAndMaskedCardModel.threeDs;
  console.log('3DS version:', tds.version);
  console.log('ECI:', tds.eci);
  console.log('Authentication value:', tds.authenticationValue);
}
See 3D Secure for details on when 3DS triggers and how to interpret the results.

​
Requirements

CardPay requires a payment processor (PSP) account configured in Orchestra. When creating the session, provide paymentGatewayAccountId: 
// Server-side session creation
const session = {
  operation: 'CHARGE',
  amount: 25.00,
  currencyCode: 'USD',
  mode: 'LIVE',
  paymentGatewayAccountId: 'your-psp-account'  // Required for CardPay
};

Library Reference

Full API reference

3D Secure

Authentication details

PSP Setup

Configure payment processor