Result Handling

This page is part of the Payments Library Guides. Prefer direct API calls instead? See 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`
`operationResultDescription`	Human-readable result message
`gatewayResultDescription`	Message from the gateway

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);
}

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)

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)

​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)

Direct Results (PayPal, BankPay, UPI)

Tokenization Results

Complete Example

Server-Side Validation

Getting Selected Payment Method

Related