EBT Transactions

EBT Transactions

The EBT web services provide payment and processing services for EBT cards.

 

Service Information


Service Endpoint - https://ps1.merchantware.net/Merchantware/ws/RetailTransaction/v4/ebt.asmx

Methods

BalanceCheck

The BalanceCheck web method looks up the balance or credit available on an EBT card.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
basisType string 1-11 The type of basis to check against the card.

Return Values

A EbtResponse4 is returned.

Notes

Data from Track 2 is required for the trackData parameter. However, you may send in the raw swipe, as long as it has not been altered since it was read from the payment card. This method will separate Track 2 data by itself.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

The basisType parameter should correspond to one of the values in the EBTBasisType enumeration.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/BalanceCheck
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <BalanceCheck xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000027</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT05</invoiceNumber>
      <trackData>« track data »</trackData>
      <pinBlock>A62408C48C939BC9</pinBlock>
      <pinKsn>128999010380001D</pinKsn>
      <basisType>2</basisType>
    </BalanceCheck>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <BalanceCheckResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <BalanceCheckResult>
        <Token>2509900</Token>
        <InvoiceNumber>EBT05</InvoiceNumber>
        <TransactionDate>2/16/2009 7:14:28 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100022</AuthorizationCode>
        <Cardholder />
        <Amount />
        <Type>1</Type>
        <CardNumber>************0026</CardNumber>
        <CardType>6</CardType>
        <EntryMode>1</EntryMode>
        <BasisType>2</BasisType>
        <Balance>949.40</Balance>
      </BalanceCheckResult>
    </BalanceCheckResponse>
  </soap:Body>
</soap:Envelope>

BalanceCheckKeyed

The BalanceCheckKeyed web method looks up the balance or credit available on an EBT card.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
basisType string 1-11 The type of basis to check against the card.

Return Values

A EbtResponse4 is returned.

Notes

The expiration date should be specified in the form "MMYY", the same ordering as a card holder would physically see on their card. For example, a card expiring in November 2008 would be specified as 1108. Unlike Credit and Debit cards, there may be some EBT programs that require an extended expiration date. This method will be updated in the future to allow other date formats as more information becomes available.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

This method identifies all cards simply as 'EBT' when a transaction is complete.

The basisType parameter should correspond to one of the values in the EBTBasisType enumeration.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/BalanceCheckKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <BalanceCheckKeyed xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT01</invoiceNumber>
      <cardNumber>7777777777777777</cardNumber>
      <expirationDate>0512</expirationDate>
      <pinBlock>CF60075050D48033</pinBlock>
      <pinKsn>1289990103800018</pinKsn>
      <basisType>2</basisType>
    </BalanceCheckKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <BalanceCheckKeyedResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <BalanceCheckKeyedResult>
        <Token>2795642</Token>
        <InvoiceNumber>EBT01</InvoiceNumber>
        <TransactionDate>2009-02-09 11:33:36.100</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100585</AuthorizationCode>
        <Cardholder />
        <Amount />
        <Type>10</Type>
        <CardNumber>***********7777</CardNumber>
        <CardType>6</CardType>
        <EntryMode>1</EntryMode>
        <BasisType>2</BasisType>
        <Balance>949.40</Balance>
      </BalanceCheckKeyedResult>
    </BalanceCheckKeyedResponse>
  </soap:Body>
</soap:Envelope>

CashSale

The CashSale web method issues a sale on an EBT card issued for cash benefit purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
cashbackAmount string (double) 0-20 The optional amount the customer received as cash back from the transaction.
forceDuplicate string 0-5 Override duplicate protection and allow the transaction to process normally.

Return Values

A EbtResponse4 is returned.

Notes

Data from Track 2 is required for the trackData parameter. However, you may send in the raw swipe, as long as it has not been altered since it was read from the payment card. This method will separate Track 2 data by itself.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge or cash-back amount, please note that these values are not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify these values.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/CashSale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CashSale xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT06</invoiceNumber>
      <amount>1.02</amount>
      <trackData>« track data »</trackData>
      <pinBlock>DDFAC0E7E057CBFA</pinBlock>
      <pinKsn>128999010380001E</pinKsn>
      <surchargeAmount></surchargeAmount>
      <cashbackAmount></cashbackAmount>
      <forceDuplicate></forceDuplicate>
    </CashSale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CashSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <CashSaleResult>
        <Token>2511737</Token>
        <InvoiceNumber>EBT06</InvoiceNumber>
        <TransactionDate>2/16/2009 8:33:43 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100040</AuthorizationCode>
        <Cardholder />
        <Amount>1.02</Amount>
        <Type>1</Type>
        <CardNumber>************0026</CardNumber>
        <CardType>6</CardType>
        <EntryMode>2</EntryMode>
        <BasisType>2</BasisType>
        <Balance>1.02</Balance>
      </CashSaleResult>
    </CashSaleResponse>
  </soap:Body>
</soap:Envelope>

CashSaleKeyed

The CashSaleKeyed web method issues a sale on an EBT card issued for cash benefit purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
cardholder string 0-100 The cardholder name as it appears on the payment card.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
cashbackAmount string (double) 0-20 The optional amount the customer received as cash back from the transaction.
forceDuplicate string 0-5 Override duplicate protection and allow the transaction to process normally.

Return Values

A EbtResponse4 is returned.

Notes

The expiration date should be specified in the form "MMYY", the same ordering as a card holder would physically see on their card. For example, a card expiring in November 2008 would be specified as 1108. Unlike Credit and Debit cards, there may be some EBT programs that require an extended expiration date. This method will be updated in the future to allow other date formats as more information becomes available.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge or cash-back amount, please note that these values are not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify these values.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/CashSaleKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CashSaleKeyed xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT02</invoiceNumber>
      <amount>1.00</amount>
      <cardNumber>7777777777777777</cardNumber>
      <expirationDate>0512</expirationDate>
      <pinBlock>ECA37D95E40AB95B</pinBlock>
      <pinKsn>1289990103800019</pinKsn>
      <cardholder></cardholder>
      <surchargeAmount>.01</surchargeAmount>
      <cashbackAmount></cashbackAmount>
      <forceDuplicate></forceDuplicate>
    </CashSaleKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CashSaleKeyedResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <CashSaleKeyedResult>
        <Token>2506844</Token>
        <InvoiceNumber>EBT02</InvoiceNumber>
        <TransactionDate>2/16/2009 4:56:45 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100000</AuthorizationCode>
        <Cardholder />
        <Amount>1.00</Amount>
        <Type>1</Type>
        <CardNumber>************7777</CardNumber>
        <CardType>6</CardType>
        <EntryMode>1</EntryMode>
        <BasisType>2</BasisType>
        <Balance>1.00</Balance>
      </CashSaleKeyedResult>
    </CashSaleKeyedResponse>
  </soap:Body>
</soap:Envelope>

FoodRefund

The FoodRefund web method issues a refund on an EBT card issued for food purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 0-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.

Return Values

A EbtResponse4 is returned.

Notes

Data from Track 2 is required for the trackData parameter. However, you may send in the raw swipe, as long as it has not been altered since it was read from the payment card. This method will separate Track 2 data by itself.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge amount, please note that the value is not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify it.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/FoodRefund
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FoodRefund xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT08</invoiceNumber>
      <amount>1.05</amount>
      <trackData>« track data »</trackData>
      <pinBlock>0D7A54B5FF71B151</pinBlock>
      <pinKsn>1289990103800020</pinKsn>
      <surchargeAmount></surchargeAmount>
    </FoodRefund>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <IssueSwipedEBTFoodStampRefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <IssueSwipedEBTFoodStampRefundResult>
        <Token>2513629</Token>
        <InvoiceNumber>EBT08</InvoiceNumber>
        <TransactionDate>2/16/2009 10:14:11 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100069</AuthorizationCode>
        <Cardholder />
        <Amount>1.05</Amount>
        <Type>2</Type>
        <CardNumber>************0026</CardNumber>
        <CardType>6</CardType>
        <EntryMode>2</EntryMode>
        <BasisType>1</BasisType>
        <Balance>9.95</Balance>
      </IssueSwipedEBTFoodStampRefundResult>
    </IssueSwipedEBTFoodStampRefundResponse>
  </soap:Body>
</soap:Envelope>

FoodRefundKeyed

The FoodRefundKeyed web method issues a sale on an EBT card issued for food purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 0-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
cardholder string 0-100 The cardholder name as it appears on the payment card.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.

Return Values

A EbtResponse4 is returned.

Notes

The expiration date should be specified in the form "MMYY", the same ordering as a card holder would physically see on their card. For example, a card expiring in November 2008 would be specified as 1108. Unlike Credit and Debit cards, there may be some EBT programs that require an extended expiration date. This method will be updated in the future to allow other date formats as more information becomes available.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge amount, please note that the value is not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify it.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/FoodRefundKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FoodRefundKeyed xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT03</invoiceNumber>
      <amount>1.01</amount>
      <cardNumber>7777777777777777</cardNumber>
      <expirationDate>0512</expirationDate>
      <pinBlock>F06F85E3393DE53D</pinBlock>
      <pinKsn>128999010380001A</pinKsn>
      <cardholder></cardholder>
      <surchargeAmount>.01</surchargeAmount>
    </FoodRefundKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <IssueKeyedEBTFoodStampRefundResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <IssueKeyedEBTFoodStampRefundResult>
        <Token>2508600</Token>
        <InvoiceNumber>EBT03</InvoiceNumber>
        <TransactionDate>2/16/2009 6:20:45 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100019</AuthorizationCode>
        <Cardholder />
        <Amount>1.01</Amount>
        <Type>2</Type>
        <CardNumber>************7777</CardNumber>
        <CardType>6</CardType>
        <EntryMode>1</EntryMode>
        <BasisType>1</BasisType>
        <Balance>1.01</Balance>
      </IssueKeyedEBTFoodStampRefundResult>
    </IssueKeyedEBTFoodStampRefundResponse>
  </soap:Body>
</soap:Envelope>

FoodSale

The FoodSale web method issues a sale on an EBT card issued for food purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
trackData string 1-500 The complete track data (all tracks) for the payment card returned from a card reader.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
forceDuplicate string 0-5 Override duplicate protection and allow the transaction to process normally.

Return Values

A EbtResponse4 is returned.

Notes

Data from Track 2 is required for the trackData parameter. However, you may send in the raw swipe, as long as it has not been altered since it was read from the payment card. This method will separate Track 2 data by itself.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge amount, please note that the value is not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify it.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/FoodSale
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FoodSale xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT07</invoiceNumber>
      <amount>1.03</amount>
      <trackData>« track data »</trackData>
      <pinBlock>50616F531AA20149</pinBlock>
      <pinKsn>128999010380001F</pinKsn>
      <surchargeAmount></surchargeAmount>
      <forceDuplicate></forceDuplicate>
    </FoodSale>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <IssueSwipedEBTFoodStampSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <IssueSwipedEBTFoodStampSaleResult>
        <Token>2512077</Token>
        <InvoiceNumber>EBT07</InvoiceNumber>
        <TransactionDate>2/16/2009 8:49:22 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100041</AuthorizationCode>
        <Cardholder />
        <Amount>1.03</Amount>
        <Type>1</Type>
        <CardNumber>************0026</CardNumber>
        <CardType>6</CardType>
        <EntryMode>2</EntryMode>
        <BasisType>1</BasisType>
        <Balance>10.30</Balance>
      </IssueSwipedEBTFoodStampSaleResult>
    </IssueSwipedEBTFoodStampSaleResponse>
  </soap:Body>
</soap:Envelope>

FoodSaleKeyed

The FoodSaleKeyed web method issues a sale on an EBT card issued for food purposes.

Arguments

Name Type Size Description
merchantName string 1-160 The name of the business or organization owning the Merchantware account.
merchantSiteId string 8-160 The site identifier of a location or storefront owned by the Merchantware account owner.
merchantKey string 1-160 The software key or password for the site accessing a Merchantware account.
invoiceNumber string 0-8 The invoice or order number associated with the transaction.
amount string (double) 1-100 The amount of the sale.
cardNumber string 13-19 The PAN or card number of the payment card.
expirationDate string 4 The expiration date of the payment card in MMYY format.
pinBlock string 1-100 The PIN block received from a pinpad device.
pinKsn string 1-100 The key serial number (KSN) associated with the PIN block received from a pinpad device.
cardholder string 0-100 The cardholder name as it appears on the payment card.
surchargeAmount string (double) 0-20 The optional surcharge fee or amount charged for the transaction.
forceDuplicate string 0-5 Override duplicate protection and allow the transaction to process normally.

Return Values

A EbtResponse4 is returned.

Notes

The expiration date should be specified in the form "MMYY", the same ordering as a card holder would physically see on their card. For example, a card expiring in November 2008 would be specified as 1108. Unlike Credit and Debit cards, there may be some EBT programs that require an extended expiration date. This method will be updated in the future to allow other date formats as more information becomes available.

This method does not attempt to cleanup PIN-specific parameters. Please note that your pin pad may prepend the KSN or PIN block with extra Zero digits. It is your responsibility to ensure that the KSN and PIN are correct when relayed.

If you specify a surcharge amount, please note that the value is not checked against the actual amount. It is your responsibility to ensure their validity if you choose to specify it.

This method identifies all cards simply as 'EBT' when a transaction is complete.

SOAP Information

SOAPAction
http://schemas.merchantwarehouse.com/merchantware/40/Ebt/FoodSaleKeyed
Sample Request Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <FoodSaleKeyed xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <merchantName>Zero Inc.</merchantName>
      <merchantSiteId>00000000</merchantSiteId>
      <merchantKey>00000-00000-00000-00000-00000</merchantKey>
      <invoiceNumber>EBT03</invoiceNumber>
      <amount>1.01</amount>
      <cardNumber>7777777777777777</cardNumber>
      <expirationDate>0512</expirationDate>
      <pinBlock>F06F85E3393DE53D</pinBlock>
      <pinKsn>128999010380001A</pinKsn>
      <cardholder></cardholder>
      <surchargeAmount>.01</surchargeAmount>
      <forceDuplicate></forceDuplicate>
    </FoodSaleKeyed>
  </soap:Body>
</soap:Envelope>
Sample Return Packet (raw)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <IssueKeyedEBTFoodStampSaleResponse xmlns="http://schemas.merchantwarehouse.com/merchantware/40/Ebt/">
      <IssueKeyedEBTFoodStampSaleResult>
        <Token>2507450</Token>
        <InvoiceNumber>EBT03</InvoiceNumber>
        <TransactionDate>2/16/2009 5:28:51 PM</TransactionDate>
        <ApprovalStatus>APPROVED</ApprovalStatus>
        <AuthorizationCode>100004</AuthorizationCode>
        <Cardholder />
        <Amount>1.01</Amount>
        <Type>1</Type>
        <CardNumber>************7777</CardNumber>
        <CardType>6</CardType>
        <EntryMode>1</EntryMode>
        <BasisType>1</BasisType>
        <Balance>18.99</Balance>
      </IssueKeyedEBTFoodStampSaleResult>
    </IssueKeyedEBTFoodStampSaleResponse>
  </soap:Body>
</soap:Envelope>

EbtResponse4

The EbtResponse4 structure encapsulates the results of a retail EBT Merchantware transaction.

Fields

Name Type Description
Amount string (double) The amount of the transaction.
ApprovalStatus string The status of the transaction, whether approved or declined. This value may also have other definitions depending on CardType and context.
AuthorizationCode string This an authorization Code issued by the processor upon receipt of a transaction.
Balance string (double) The remaining amount of credit on the EBT, if available at the time the transaction is made.
BasisType int (EBTBasisType) This describes the EBT basis used to submit a transaction. This value matches up with the EBTBasisType enumeration.
Cardholder string The Cardholder associated with the payment card used in a transaction.
CardNumber string This is a string representing the truncated card number of the payment card used in a transaction.
CardType int (CardType) The issuer type of payment card used in a transaction. This value matches up with the CardType enumeration.
EntryMode int (POSEntryType) This describes the method used to submit a transaction. This value matches up with the POSEntryType enumeration.
ErrorMessage string This field contains a message describing the reason the transaction could not complete.
InvoiceNumber string The InvoiceNumber is the invoice or order number associated with the transaction.
Token string The Token is the identifier received by the Merchantware client when a transaction has been issued. This value may be used to lookup a specific transaction in the history log.
TransactionDate string (DateTime, UTC) The date and time when a transaction is issued, in UTC time.
TransactionType int (TransactionType) The type of transaction, and this value matches up with the TransactionType enumeration.

Notes

The Balance field is set if the remaining balance value is available at the end of a transaction.

Card numbers are always truncated when methods return data in this structure.

ApprovalStatus currently may contain the values 'APPROVED', 'DECLINED', and 'REFERRAL'. In addition, it may have 'DUPLICATE' appended with a comma; when it is known that duplicate transactions were the reason for the decline. A 'REFERRAL' response indicates that the processor should be contacted for an authorization code or for further instructions regarding balance limits or fraud.

Only the value 'APPROVED' will be returned on any approval. It is safe to assume that no charge, refund, or any other action or transfer of value has occurred if you do not receive this return value.

APPROVED

Any of these values and possibly other values may be returned on a decline or other failure.

DECLINED
DECLINED,DUPLICATE
REFERRAL

A detailed explanation of error status values is available here.

References

A EbtResponse4 is returned by these web methods.