Healthcare

For terminals in the healthcare sector, you have the option to specify additional fields related to healthcare amounts.

There are 2 methods for providing the healthcare amounts:

1. Provide healthcare amounts when first initiating a transaction request to CommerceSDK.
2. If healthcare amounts are not provided, CommerceSDK will perform a bin lookup on the card and return the result via a callback method. You have the option to provide healthcare amounts at this point. Note that you must tell CommerceSDK to continue the transaction after receiving the callback, regardless if you actually set any healthcare amounts or not.

The following healthcare amounts can be set:

• Over The Counter Amount
• Prescription Amount
• Clinic/Other Amount
• Dental Amount
• Vision Amount
• Transit Amount

Code Samples

CWS

Method 1 - set healthcare amounts during the initial startPaymentTransaction request.

Request

{
  "method" : "startPaymentTransaction",
  "requestId" : "1828579547",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "transactionType" : "SALE",
    "paymentGatewayId" : "855cc46b-07fe-448e-ab39-f133c44988ae",
    "tenderType" : "CARD",
    "baseTransactionAmount" : {
      "value" : 500,
      "currencyCode" : "USD"
    },
    "healthcareAmount" : {
      "overTheCounterAmount" : {
        "value" : 200,
        "currencyCode" : "USD"
      },
      "prescriptionAmount" : {
        "value" : 300,
        "currencyCode" : "USD"
      }
    }
  }
}

Method 2 - wait for HandleBinLookupResult in requiredInformation of getPaymentTransactionStatus response.

Response

{
  "requestId" : "1785483547",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : false,
      "eventQueue" : [ ],
      "chanId" : "7386cfad-22a3-40fa-9fe2-d7a41ada9822",
      "requiredInformation" : [ "HandleBinLookupResult" ],
      "binLookupResult" : {
        "hsaCard" : true
      }
    }
  }
}

Continue the transaction, providing any necessary healthcare amounts.

Request

{
  "method" : "continuePaymentTransaction",
  "requestId" : "1785483548",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "chanId" : "7386cfad-22a3-40fa-9fe2-d7a41ada9822",
    "paymentGatewayId" : "855cc46b-07fe-448e-ab39-f133c44988ae",
    "HandleBinLookupResult" : {
      "healthcareAmount" : {
        "overTheCounterAmount" : {
          "value" : 200,
          "currencyCode" : "USD"
        },
        "prescriptionAmount" : {
          "value" : 300,
          "currencyCode" : "USD"
        }
      }
    }
  }
}

Java

// Instantiate ECLHealthcareAmount and set any of the necessary healthcare amounts
ECLHealthcareAmount healthcareAmount = new ECLHealthcareAmount.Builder()
    .overTheCounterAmount(overTheCounterAmount)
    .prescriptionAmount(prescriptionAmount)
    .clinicAmount(clinicAmount)
    .dentalAmount(dentalAmount)
    .visionAmount(visionAmount)
    // don't set this if you have any of the other amounts set - must be sent in a separate transaction
    .transitAmount(transitAmount)
    .build();
 
 
// Method 1: set healthcare amounts when first starting the transaction
ECLCurrencyTransactionInterface transaction = account.getTransactionProcessor().createSaleTransactionWithSubtotal(amount);
transaction.setHealthcareAmount(healthcareAmount);
ECLCardTenderInterface tender = account.getTransactionProcessor().createCardTender();
account.getTransactionProcessor().processTransaction(transaction, tender, transactionListener);
 
 
// Method 2: handle bin lookup complete callback method of ECLTransactionProcessingListener
// if this method is called, you must tell CSDK to continue the transaction after setting any relevant fields
public void handleBinLookupComplete(ECLTransactionInterface transaction, ECLTenderInterface tender, ECLBinLookupResult binLookupResult)
{
    if (binLookupResult.isHsaCard())
    {
        if (transaction instanceof ECLCurrencyTransactionInterface)
        {
            // set healthcare amount on currencyTransaction
            ECLCurrencyTransactionInterface currencyTransaction = (ECLCurrencyTransactionInterface)transaction;
            currencyTransaction.setHealthcareAmount(healthcareAmount);
        }
    }
 
    handler.post(() -> account.getTransactionProcessor().continueProcessingTransaction(transaction, tender, transactionListener));
}

Objective-C (iOS)

// Instantiate ECLHealthcareAmount and set any of the necessary healthcare amounts
ECLHealthcareAmount *healthcareAmount = [[ECLHealthcareAmount alloc] init];
healthcareAmount.overTheCounterAmount = ...
healthcareAmount.prescriptionAmount = ...
healthcareAmount.clinicAmount = ...
healthcareAmount.dentalAmount = ...
healthcareAmount.visionAmount = ...
 
// don't set this if you have any of the other amounts set - must be sent in a separate transaction
healthcareAmount.transitAmount = ...
 
 
// Method 1: set healthcare amounts when first starting the transaction
id<ECLCurrencyTransactionProtocol> transaction = [account.transactionProcessor createSaleTransactionWithSubtotal:amount];
transaction.healthcareAmount = healthcareAmount;
id<ECLCardTenderProtocol> tender = [account.transactionProcessor createCardTender];
[account.transactionProcessor processTransaction:transaction using:tender delegate:self];
 
 
// Method 2: handle bin lookup complete callback method of ECLTransactionProcessingDelegate
// if this method is called, you must tell CSDK to continue the transaction after setting any relevant fields
- (void)handleBinLookupComplete:(id<ECLTransactionProtocol>)transactionParam tender:(id<ECLTenderProtocol>)tenderParam binLookupResult:(ECLBinLookupResult *)binLookupResult {
    if (binLookupResult.hsaCard) {
        if ([transactionParam conformsToProtocol:@protocol(ECLCurrencyTransactionProtocol)]) {
            // set healthcare amount on currencyTransaction
            id<ECLCurrencyTransactionProtocol> currencyTransaction = (id<ECLCurrencyTransactionProtocol>)transactionParam;
            currencyTransaction.healthcareAmount = healthcareAmount;
        }
    }
     
    dispatch_async(dispatch_get_main_queue(), ^() {
        [[self->_account transactionProcessor] continueProcessingTransaction:transactionParam using:tenderParam delegate:self];
    });
}

C#

// Instantiate HealthcareAmount and set any of the necessary healthcare amounts
HealthcareAmount healthcareAmount = new HealthcareAmount();
healthcareAmount.overTheCounterAmount = ...
healthcareAmount.prescriptionAmount = ...
healthcareAmount.clinicAmount = ...
healthcareAmount.dentalAmount = ...
healthcareAmount.visionAmount = ...
 
// don't set this if you have any of the other amounts set - must be sent in a separate transaction
healthcareAmount.transitAmount = ...
 
 
// Method 1: set healthcare amounts when first starting the transaction
PaymentArgs bea = new PaymentArgs();
bea.baseTransactionAmount = ...
bea.tenderType = TenderType.CARD;           
bea.transactionType = TransactionType.SALE;
bea.paymentGatewayId = ...
bea.healthcareAmount = healthcareAmount;
m_CWS.StartPaymentTransaction(bea, MyNotifyCWSEvent, MyPaymentComplete);
 
 
// Method 2: check for HandleBinLookupResult in RequiredInformation
// You must call CWS.StartHandleBinLookupResult after setting any relevant fields
public void MyPaymentComplete(PaymentTransactionResults paymentResults)
{
    // get required information
    String[] req = paymentResults.GetRequiredInformation();
    if (null != req)
    {
        for (int i = 0; i < req.Length; i++)
        {
            if (String.Compare(req[i], "HandleBinLookupResult", true) == 0)
            {
                HandleBinLookupResultInfo binLookupResultInfo = null;
                BinLookupResult binLookupResult = paymentResults.GetBinLookupResult();
                if (binLookupResult.isHsaCard)
                {
                    binLookupResultInfo = new HandleBinLookupResultInfo();
                    binLookupResultInfo.healthcareAmount = healthcareAmount;
                }
                 
                m_CWS.StartHandleBinLookupResult(m_PaymentGatewayId, chanId, binLookupResultInfo, MyNotifyCWSEvent, MyPaymentComplete);
            }
        }
    }
}