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:
- Provide healthcare amounts when first initiating a transaction request to CommerceSDK.
- 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
error_outline
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
Method | Description |
---|---|
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
Method | Description |
---|---|
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
Method | Description |
---|---|
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);
}
}
}
}