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

important

If you need to set Transit Amount, it must be sent in a separate transaction request from any of the other healthcare amounts.

Code Samples

CWS

MethodDescription
parameters
JSONObject | required
All relevant parameters for a transaction.
healthcareAmount
JSONObject | optional
Healthcare amount.
overTheCounterAmount
JSONObject | optional
Amount of over the counter medical expenditures.
prescriptionAmount
JSONObject | optional
Amount of prescription drug expenditures.
clinicAmount
JSONObject | optional
Amount of expenditures for clinic or other medical office services.
dentalAmount
JSONObject | optional
Amount of dental expenditures.
visionAmount
JSONObject | optional
Amount of vision expenditures.
transitAmount
JSONObject | optional
Amount of transit expenditures.
Note: Transit Amount must be sent separately from healthcare transactions that include other healthcare amount fields above.

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

MethodDescription
paymentGatewayCommand
JSONObject
Payment Gateway Command
requiredInformation
Array
HandleBinLookupResult
binLookupResult
JSONObject
Result of the bin lookup
hsaCard
boolean
Whether the card is an HSA card.
{
  "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

MethodDescription
parameters
JSONObject | required
All relevant parameters for a transaction.
chanId
JSONObject | required
Unique transaction identifier.
paymentGatewayId
JSONObject | required
Unique payment gateway identifier.
HandleBinLookupResult
JSONObject | required
Contains any new fields that need to be added to the transaction, e.g. healthcare amounts.
healthcareAmount
JSONObject | optional
Healthcare amount. See above for different amounts to include in this field.
{
  "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);
            }
        }
    }
}