Result Handling

This page is part of the Payments Library Guides. For what your backend does after capture, like charging stored tokens and refunds, see the REST API Guides.

Prerequisites: Complete the Library Setup first. All payment methods return results through the same callback function. This page covers how to parse results, check for success, and handle different payment types.

Parsing Results

Use parseResultToken() to decode the result token:

function handleResult(result) {
  // User cancelled
  if (!result) {
    console.log('Payment cancelled');
    return;
  }

  const [data, success] = engine.parseResultToken(result.token);
  console.log('Payment result:', data);
}

The method returns a tuple:

data - The parsed result object
success - Boolean indicating if the token was decoded (not whether payment succeeded)

Checking Payment Success

Always check clientSuccess first:

if (!data.clientSuccess) {
  console.error('Payment failed:', data.clientErrorMessage);
  return;
}

// Payment succeeded - check result type

Result Types

Results vary based on the payment method used:

PSP Results (CardPay, Apple Pay, Google Pay)

Card-based payments return results through upgChargeResults:

if (data.upgChargeResults) {
  const charge = data.upgChargeResults;

  if (charge.operationResultCode === 'Success') {
    console.log('Payment approved');
    console.log('Gateway:', charge.gatewayName);
    console.log('Reference:', charge.gatewayReference);
    console.log('Auth code:', charge.authorizationCode);
    console.log('Amount:', charge.amount, charge.currency);
  } else {
    console.log('Payment declined:', charge.operationResultDescription);
  }
}

Available fields:

Field	Description
`gatewayName`	Name of the payment gateway
`gatewayReference`	Gateway’s transaction reference
`authorizationCode`	Authorization code from issuer
`amount`	Charged amount
`currency`	Currency code
`operationResultCode`	`Success`, `Accepted`, `Rejected`, `TemporaryFailure`, `FatalFailure`, `NotImplemented`
`rejectReasonCode`	Why the payment was rejected, normalized across gateways. See Decline Reasons
`operationResultDescription`	Human-readable result message
`gatewayResultDescription`	Message from the gateway

Decline Reasons

Every gateway words its declines differently. rejectReasonCode normalizes them, so you can react to a decline without writing gateway-specific parsing. It is None when nothing was rejected.

Code	Meaning	Worth retrying?
`None`	No rejection	n/a
`InsufficientFunds`	Not enough funds available	Yes, later. Funds may arrive
`CardExpired`	The card has passed its expiry date	No. Ask for a new card
`InvalidCard`	Card details are not valid	No. Ask the customer to re-enter them
`DoNotHonor`	Issuer refused without giving a reason	Sometimes. The customer may need to contact their issuer
`Fraud`	Flagged as fraudulent	No
`LostOrStolenCard`	Reported lost or stolen	No
`ExceedsLimit`	Over a card or account limit	Yes, later or for a smaller amount
`InvalidTransaction`	The issuer will not accept this transaction type	No. Check the operation against the gateway’s requirements
`AuthenticationFailed`	3D Secure authentication did not succeed	Yes, with a fresh authentication attempt
`ProcessorDecline`	Declined by the processor rather than the issuer	Sometimes. Consider a fallback gateway
`TechnicalError`	A technical failure rather than a decision	Yes. Treat it as transient
`Other`	No more specific code applies	Read `gatewayResultDescription`

For scheduled payments, this field tells you whether to chase the customer for a new card or simply let the next scheduled attempt run. CardExpired and InvalidCard need the customer; InsufficientFunds and TechnicalError usually do not.

Do not retry Fraud or LostOrStolenCard. Repeated attempts against a blocked card can affect your standing with the issuer.

upgChargeResults is always a single object holding the final gateway attempt. If your account has a gateway fallback chain and earlier attempts failed, those failed attempts are returned separately as an array in failedUpgChargeResults. When there was only one attempt, failedUpgChargeResults is null.

Direct Results (PayPal, BankPay, UPI)

Redirect-based payments return results through directChargeResults:

if (data.directChargeResults) {
  if (data.directChargeResults.success) {
    console.log('Payment successful');
  } else {
    console.log('Payment failed:', data.directChargeResults.message);
  }
}

Tokenization Results

When using TOKENIZE, CHARGE_AND_TOKENIZE, or PREAUTH_AND_TOKENIZE, card details are returned in tokenAndMaskedCardModel:

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

Persist these non-sensitive fields alongside the token if you plan to offer stored-card payments later - they are needed to display the saved card, and cannot be retrieved afterwards.

Complete Example

async function handleResult(result) {
  // User cancelled
  if (!result) {
    showMessage('Payment cancelled', 'info');
    return;
  }

  const [data] = engine.parseResultToken(result.token);

  // Check overall success
  if (!data.clientSuccess) {
    showMessage('Payment failed: ' + data.clientErrorMessage, 'error');
    return;
  }

  // Handle PSP results (CardPay, Apple Pay, Google Pay)
  if (data.upgChargeResults) {
    if (data.upgChargeResults.operationResultCode === 'Success') {
      showMessage('Payment successful! Reference: ' + data.upgChargeResults.gatewayReference, 'success');
    } else {
      showMessage('Payment declined: ' + data.upgChargeResults.operationResultDescription, 'error');
    }
  }

  // Handle direct results (PayPal, BankPay, UPI)
  if (data.directChargeResults) {
    if (data.directChargeResults.success) {
      showMessage('Payment successful!', 'success');
    } else {
      showMessage('Payment failed: ' + data.directChargeResults.message, 'error');
    }
  }

  // Server-side validation (recommended)
  await validateWithServer(result.token);
}

Server-Side Validation

Always validate results on your server before fulfilling orders:

// Client-side
async function validateWithServer(resultToken) {
  const response = await fetch('/api/validate-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ resultToken })
  });

  const validation = await response.json();
  console.log('Server validation:', validation);
}

app.post('/api/validate-payment', async (req, res) => {
  const { resultToken } = req.body;

  const response = await fetch('https://api.orchestrasolutions.com/EWalletOperations/validateResults', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ORCHESTRA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(resultToken)
  });

  const validationResult = await response.json();

  if (validationResult.failedUpgChargeResults?.length) {
    res.json({ success: false, error: validationResult.failedUpgChargeResults[0].operationResultDescription });
  } else if (validationResult.upgChargeResults) {
    // Payment confirmed - fulfill the order
    res.json({ success: true });
  } else if (validationResult.directChargeResults) {
    res.json({
      success: validationResult.directChargeResults.success,
      error: validationResult.directChargeResults.message
    });
  } else if (validationResult.tokenAndMaskedCardModel) {
    res.json({ success: true });
  }
});

@app.route('/api/validate-payment', methods=['POST'])
def validate_payment():
    data = request.json
    result_token = data['resultToken']

    response = requests.post(
        'https://api.orchestrasolutions.com/EWalletOperations/validateResults',
        headers={
            'X-Api-Key': os.environ['ORCHESTRA_API_KEY'],
            'Content-Type': 'application/json'
        },
        data=json.dumps(result_token)
    )

    validation_result = response.json()

    if validation_result.get('failedUpgChargeResults'):
        return jsonify({
            'success': False,
            'error': validation_result['failedUpgChargeResults'][0]['operationResultDescription']
        })
    elif validation_result.get('upgChargeResults'):
        # Payment confirmed - fulfill the order
        return jsonify({'success': True})
    elif validation_result.get('directChargeResults'):
        return jsonify({
            'success': validation_result['directChargeResults']['success'],
            'error': validation_result['directChargeResults'].get('message')
        })
    elif validation_result.get('tokenAndMaskedCardModel'):
        return jsonify({'success': True})

Getting Selected Payment Method

Use getSelectedProviderName() to know which payment method the customer used:

function handleResult(result) {
  const provider = engine.getSelectedProviderName();
  console.log('Customer paid with:', provider);
  // "CardPay", "ApplePay", "GooglePay", "PayPal", "BankPay", or "UPI"
}

Library Reference

Full API reference

Complete Example

End-to-end integration

Start Session API

Create a session token

Validate Results API

Server-side validation endpoint

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Parsing Results

Checking Payment Success

Result Types

PSP Results (CardPay, Apple Pay, Google Pay)

Decline Reasons

Direct Results (PayPal, BankPay, UPI)

Tokenization Results

Complete Example

Server-Side Validation

Getting Selected Payment Method

Library Reference

Complete Example

Start Session API

Validate Results API

​Parsing Results

​Checking Payment Success

​Result Types

​PSP Results (CardPay, Apple Pay, Google Pay)

​Decline Reasons

​Direct Results (PayPal, BankPay, UPI)

​Tokenization Results

​Complete Example

​Server-Side Validation

​Getting Selected Payment Method

​Related

Library Reference

Complete Example

Start Session API

Validate Results API

Parsing Results

Checking Payment Success

Result Types

PSP Results (CardPay, Apple Pay, Google Pay)

Decline Reasons

Direct Results (PayPal, BankPay, UPI)

Tokenization Results

Complete Example

Server-Side Validation

Getting Selected Payment Method

Related