Continue Transaction

This transaction integrates continuance of transaction processing into your application.

During transaction processing, Commerce SDK may need additional information from your application. The information needed will be based on the following Tender or Transaction requirements:

Tender Requirements

  • requiresCardData

    • If you have set card entry to token and have not set tokenizedCardNumber on the card tender, Commerce SDK will pause the transaction until you’ve provided the necessary information and continued the transaction.
  • requiresDigitalSignature

    • If the card and transaction require a digital signature but the card reader failed to get it or does not support it or digitalSignature has not been set on card tender or canceled the signature, Commerce SDK will call back until the digitalSignature is set or you have called cancelSignature on the cardTender.
    • If you have set the digitalSignature but we are unable to use it, lastSignatureError will be set on the tenderRequirements. You can also get the minimize size required for the signature from the tenderRequirements.
  • requiresSignatureVerification

    • If you have set signature verification required on the card tender, Commerce SDK will pause the transaction until you’ve called setSignatureVerificationHandledAndVerified and continued the transaction.
  • requiresVoiceReferral

    • If you have set voice approval required on the card tender and have not called setVoiceReferralHandledAndApproved or setVoiceReferralHandledAndDenied, Commerce SDK will pause the transaction until you’ve called one of them and continued the transaction.
  • requiresSpecifyingCardPresence

    • If you are doing a manual entry transaction whereby you want to key in the card information on the card reader, you will need to specify whether or not the card is physically present at the time of the transaction by calling setCardPresent on the card tender.
  • requiresEmvApplicationSelection

    • If the chip requires an application selection, Commerce SDK will pause the transaction until you’ve called setSelectedEmvApplication on the tender and continued the transaction.
  • requiresAVS

    • If some AVS data is required, Commerce SDK will pause the transaction until you’ve provided Commerce SDK with the required AVS field information via the setAVSField method.

Transaction Requirements

  • requiresGratuity

    • If you are doing a transaction that can have gratuity and have not turned on isGratuityRequested so it will be done on card reader or you have not set gratuity on the transaction, Commerce SDK will call back until it is set.
    • You can set gratuity to null (or nil depending on your platform) if you do not want gratuity to be involved.
    • You can set it when creating the transaction or wait until shouldProvideInformation is called.
  • requiresTax and requiresDiscount

    • This will not be set as tax and discount default to null (or nil).

note

When shouldProvideInformation is called, there can be multiple requirements that need to be set but you should only call contiuePaymentTransaction once you have set as many requirements as you want.

If there are multiple requirements that need to be set, you can set one and call continuePaymentTransaction. shouldProvideInformation will be called again and again until all requirements are set.

If shouldProvideInformation is called and you want to stop the transaction, you should call cancelPaymentTransaction.

Code Samples

CWS

During transaction processing, Commerce SDK will return the requiredInformation variable to indicate the information it needs from your application in order to continue processing the transaction. This variable will contain one of these values:

ValueDescription
DigitalSignatureReturned if digital signature has not been set on card tender
Returned if the card and transaction require a digital signature but the card reader:
- failed to retrieve the information
- does not support digital signature capturing
- canceled the signature
VoiceReferralReturned if voice approval required is set on the card tender but one of these is not called:
- setVoiceReferralHandledAndApproved
- setVoiceReferralHandeledAndDenied
SignatureVerificationReturned if signature verification required is set on the card ternder but setSignatureVerificationHandledAndVerified is not called
TaxReturned if tax is not enabled
DiscountReturned if discount defaults to null
TipReturned if isGratuityRequested is disabled or gratuity is not set on the transaction
TokenizedCardNumberTokenized credit card number
CardPresentReturned if setCardPresent is not called from the card tender
EmvApplicationSelectionRequiredReturned if EMV application is required
- The available applications will be returned in the emvApplicationSelectionList variable.
- To select the application, send the AID in the emvApplicationIdSelected field of the continuePaymentTransaction request to CWS
HandleBinLookupResultReturned if CSDK performed a bin lookup. Allows you to update the transaction based on the binLookupResult

Request

PropertyDescription
method
string | required
continuePaymentTransaction
requestId
string | required
Transaction Request ID
targetType
string | required
paymentGatewayConverge
parameters
JSONObject | required
All relevant parameters for continuing transaction processing.
paymentGatewayId
string | required
Payment Gateway ID
Unique payment gateway identifier as returned in the openPaymentGateway transaction response.
chanId
string | required
Transaction ID
Important: Returned in the startPaymentTransaction response.
DigitalSignature
VoiceReferral
SignatureVerification
Tax
Discount
Tip
TokenizedCardNumber
CardPresent
EmvApplicationIdSelected
RequireAvsZipCode
HandleBinLookupResult
string | required
Required Information
Important: Returned in the requiredInformation variable.

Example

Response
{
  "requestId" : "2101936246",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : false,
      "eventQueue" : [ ],
      "chanId" : "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9",
      "requiredInformation" : [ "VoiceReferral" ]
    }
  }
}
Request
{
  "method" : "continuePaymentTransaction",
  "requestId" : "2101936247",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "VoiceReferral" : "321zxc",
    "paymentGatewayId" : "4c45c792-0513-4218-8b6d-c5ff7039a22e",
    "chanId" : "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9"
  }
}

Response

{
  "requestId" : "2101936248",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : false,
      "eventQueue" : [ ],
      "chanId" : "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9",
      "requiredInformation" : [ "EmvApplicationSelectionRequired" ],
      "emvApplicationSelectionList" : [ {
        "name" : "Visa Debit      ",
        "index" : 0,
        "aid" : "A0000000031010"
      }, {
        "name" : "US Debit        ",
        "index" : 1,
        "aid" : "A0000000980840"
      } ]
    }
  }
}

Request

{
  "method" : "continuePaymentTransaction",
  "requestId" : "2101936249",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "EmvApplicationIdSelected" : "A0000000980840",
    "paymentGatewayId" : "4c45c792-0513-4218-8b6d-c5ff7039a22e",
    "chanId" : "eb5fcc9f-07db-40a6-9711-6c2bda9a26b9"
  }
}

Java

If Commerce SDK need information in order to continue processing a transaction, the transaction listener shouldProvideInformation method will be called. You can check the parameters in that method to determine the specific information Commerce SDK needs.

After obtaining the required information, you can call the continueTransaction method on the transaction processor to tell Commerce SDK to continue.

note

You should call continueTransaction on a different thread than the current one in order to not block the current thread.

Refer to the Windows sample app source code for more information.

In this example from shouldProvideInformation, we are checking the tenderRequirements interface to see if a voice referral was needed. In this case, it is needed so you need to get an approval code from the card issuer and then pass it back to Commerce SDK so the transaction can continue.

boolean continueTransaction = false;
if (tenderRequirementsInterface.getRequiresVoiceReferral() != ECLVoiceReferralRequirement.NOT_REQUIRED)
{
      // you'd need to obtain an approval code at this point.  In this example, the code is 321.  Then you'd pass it back to CSDK like this:
      ((ECLCardTenderInterface) tender).setVoiceReferralHandledAndApproved("321");
     continueTransaction = true;
}

if (continueTransaction == true) 
{
    Thread thread = new Thread() {
        @Override
        public void run()
            account.getTransactionProcessor().continueProcessingTransaction(transaction, tender, transactionListener);
        }
    };
    thread.start();
    return;
}

Objective-C

If Commerce SDK needs information from you in order to continue processing a transaction, your transaction processing delegate’s shouldProvideInformation method will be called. You can check the parameters in that method to determine what specific information Commerce SDK needs from you. After you’ve obtained the required information, you can call the continueProcessingTransaction method on the transaction processor to tell Commerce SDK to continue.

note

You should call continueProcessingTransaction from inside a dispatch_async.

See the sample app source code for more information.

In the example below, we are inside the shouldProvideInformation method. We are checking to see if voice referral is needed.

BOOL continueTransaction = NO;
if (tenderRequirementsInterface.requiresVoiceReferral != ECLVoiceReferral_NotRequired) {
      // you'd need to obtain an approval code at this point.  In this example, the code is 321. You should show UI to get the actual code. Then you'd pass it back to CSDK like this:
      [((id<ECLCardTenderProtocol>) tender) setVoiceReferralHandledAndApproved:@"321"];
      continueTransaction = YES;
}

if (continueTransaction == YES) {
    dispatch_async(dispatch_get_main_queue(), ^() {
          [[_account transactionProcessor] continueProcessingTransaction:transaction using:tender delegate:delegate];
    });
    return;
}

C#

If Commerce SDK needs information from you in order to continue processing a transaction, your payment complete callback will be called. You’ll have access to a paymentresults parameter. Check to see if paymentresults.completed is false. If it is then you can call getRequiredInformation which will return an array of items that Commerce SDK needs from you. Typically there will only be one element in the array. If there are multiple elements, you need to handle them one by one.

During transaction processing, Commerce SDK will return the requiredInformation variable to indicate the information it needs from your application in order to continue processing the transaction. This variable will contain one of these values:

ValueDescription
DigitalSignatureReturned if digital signature has not been set on card tender
Returned if the card and transaction require a digital signature but the card reader:
- failed to retrieve the information
- does not support digital signature capturing
- canceled the signature
VoiceReferralReturned if voice approval required is set on the card tender but one of these is not called:
- setVoiceReferralHandledAndApproved
- setVoiceReferralHandeledAndDenied
SignatureVerificationReturned if signature verification required is set on the card ternder but setSignatureVerificationHandledAndVerified is not called
TaxReturned if tax is not enabled
DiscountReturned if discount defaults to null
TipReturned if isGratuityRequested is disabled or gratuity is not set on the transaction
TokenizedCardNumberTokenized credit card number.
CardPresentReturned if setCardPresent is not called from the card tender
EmvApplicationSelectionRequiredReturned if setSelectedEmvApplication is not called from the card tender
EmvApplicationIdSelectedIdentifier of the selected EMV application.
RequireAvsZipCodeReturned if cardholder zip code is required for the transaction
HandleBinLookupResultIf you need to update the transaction based on the binLookupResult, then you should use CWS.HandleBinLookupResult method to pass in a HandleBinLookupResultInfo object.

In the example below, we’ve called getRequiredInformation and there was a single element in there for VoiceReferral. Then the merchant obtains the voice referral code from the issuer and then gives it to your app. You pass the code into Commerce SDK by setting the VoiceReferral variable. Then you call continuePaymentTransaction to continue the transaction.

Dictionary<string, string> info = new Dictionary<string, string>();
info["VoiceReferral"] = "abc123";

PaymentTransactionResults tr = m_CWS.ContinuePaymentTransaction(m_PaymentGatewayId, chanId, info, MyNotifyCWSEvent);