EBT Payment

Overview

This guide covers Electronic Benefits Transfer (EBT) payment processing for government assistance programs. EBT cards are used to distribute SNAP (Supplemental Nutrition Assistance Program) food benefits and TANF (Temporary Assistance for Needy Families) cash benefits. All EBT transactions require PIN authentication.

EBT Sale Transactions

1. FOOD Benefits - Swiped

SNAP benefits for purchasing eligible food items.

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "entryMode": "swiped",
  "commerceIndicator": "retail",
  "ebtCategory": "FOOD",
  "pin_block": "D3D246844445AB8A",
  "pin_format": "0",
  "ksn": "23288800010000200002",
  "cardData": {
    "emvData": {
      "trackData": ";5061123456789012=29121234567890123456?"
    }
  }
}'

Key Fields:

ebtCategory: "FOOD" - SNAP food benefits
entryMode: "swiped" - Magnetic stripe read
No card field required for sales (implied by ebtCategory)
cardData.emvData.trackData: Track 2 data from card swipe

Track Data Format: ;[PAN]=[Expiry][Service Code][Discretionary Data]?

2. FOOD Benefits - Keyed

Manual entry for FOOD benefits when card cannot be swiped.

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "entryMode": "keyed",
  "commerceIndicator": "retail",
  "ebtCategory": "FOOD",
  "pin_block": "D3D246844445AB8A",
  "pin_format": "0",
  "ksn": "23288800010000200002",
  "cardData": {
    "panNumber": "5061123456789012",
    "expiryDate": "1229"
  }
}'

Key Fields:

entryMode: "keyed" - Manual card number entry
cardData.panNumber: 16-digit card number (PAN)
cardData.expiryDate: Expiration date in MMYY format (e.g., "1229" for December 2029)

3. CASH Benefits - Swiped

TANF cash benefits for any purchase or cash withdrawal.

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "entryMode": "swiped",
  "commerceIndicator": "retail",
  "amount": "100",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "ebtCategory": "CASH",
  "cardData": {
    "emvData": {
      "trackData": ";5061123456789012=29121234567890123456?"
    }
  }
}'

Key Fields:

ebtCategory: "CASH" - TANF cash benefits
Can be used for any purchase (not restricted to food items)
Supports cash back transactions

4. FOOD Benefits with Voucher

Voucher-based FOOD benefit transactions for paper voucher programs.

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "entryMode": "keyed",
  "commerceIndicator": "retail",
  "ebtCategory": "FOOD",
  "voucherSerialNumber": "123451234512345",
  "cardData": {
    "panNumber": "5061123456789012",
    "expiryDate": "1229"
  }
}'

Key Fields:

voucherSerialNumber: 15-digit voucher identifier from paper voucher
No PIN required for voucher transactions (no pin_block, pin_format, or ksn)
Voucher must be validated and matched to card number

Important: Voucher transactions do not require PIN authentication as the physical voucher serves as authorization.

EBT Refund Transactions

Direct refunds return funds to an EBT benefits account without referencing a previous transaction.

1. FOOD Benefits Refund - Swiped

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "commerceIndicator": "retail",
  "card": "ebt",
  "amount": "100",
  "entryMode": "swiped",
  "ebtCategory": "FOOD",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "trackData": ";5061123456789012=29121234567890123456?"
  }
}'

Key Fields:

card: "ebt" - Required for refunds (identifies EBT transaction)
paymentType: "refund" - Direct refund (no ref_id needed)
ebtCategory: "FOOD" - Refund to FOOD benefits account

2. FOOD Benefits Refund - Contact

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "card": "ebt",
  "commerceIndicator": "retail",
  "amount": "100.00",
  "entryMode": "contact",
  "pin_block": "5D5FA5E5B448F33B",
  "pin_format": "0",
  "ksn": "FFFF1B1D140000200001",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";5061123456789012=29121234567890123456?",
      "cardSequenceNumber": "01"
    }
  }
}'

Note: Contact (chip) entry mode may be supported depending on card issuer and terminal capabilities.

3. CASH Benefits Refund - Keyed

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "commerceIndicator": "retail",
  "card": "ebt",
  "amount": "100",
  "entryMode": "keyed",
  "ebtCategory": "CASH",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "panNumber": "5061123456789012",
    "expiryDate": "1229"
  }
}'

Important Notes:

Direct refunds do not require a ref_id from a previous transaction
Refunds credit the benefits back to the cardholder's account
PIN authentication is required for all refund transactions
The card field must be set to "ebt" for refunds

Balance Inquiry

Balance inquiry allows checking available benefits on an EBT card without performing a transaction. Cardholders can check both FOOD and CASH balances.

1. FOOD Benefits Balance Inquiry

curl --location 'https://apitest.valorvpc.com/payment/balance-inquiry' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "balance_inquiry",
  "commerceIndicator": "retail",
  "entryMode": "swiped",
  "ebtCategory": "FOOD",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "trackData": ";4111111111111111=33121019761186800000?"
  }
}'

Example Response:

{
  "responseCode": "00",
  "ref_id": "90aade2b-6bde-4fed-b47d-6a35ff756dc3",
  "status": "AUTHORIZED",
  "creatorName": "VALOR",
  "txn_type": "balance_inquiry",
  "tran_no": 9,
  "batch_no": "3",
  "balance": {
    "amount": "+20.00",
    "accountType": "98",
    "amountType": "02"
  },
  "authCode": "831000",
  "reference": "123456882185",
  "cardInformation": {
    "maskedPan": "411111XXXXXX1111",
    "expiryDate": "1233"
  },
  "created": "2025-12-04T18:54:41Z"
}

Response Fields:

responseCode: "00" indicates success
balance.amount: Available FOOD benefits (+ indicates positive balance)
balance.accountType: "98" for FOOD benefits
balance.amountType: "02" indicates ledger balance

2. CASH Benefits Balance Inquiry

curl --location 'https://apitest.valorvpc.com/payment/balance-inquiry' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "balance_inquiry",
  "commerceIndicator": "retail",
  "entryMode": "swiped",
  "ebtCategory": "CASH",
  "pin_block": "D3D246844445AB8A",
  "pin_format": "0",
  "ksn": "23288800010000200002",
  "cardData": {
    "trackData": ";5061123456789012=33121019761186800000?"
  }
}'

Example Response:

{
  "responseCode": "00",
  "ref_id": "fa80bc4b-2395-48eb-a7b7-686214121b8d",
  "status": "AUTHORIZED",
  "creatorName": "VALOR",
  "txn_type": "balance_inquiry",
  "tran_no": 320,
  "batch_no": "1",
  "balance": {
    "amount": "+20.00",
    "accountType": "96",
    "amountType": "02"
  },
  "authCode": "831000",
  "reference": "123456359283",
  "cardInformation": {
    "maskedPan": "506112XXXXXX9012",
    "expiryDate": "1233"
  },
  "created": "2025-12-04T16:05:58Z"
}

Response Fields:

balance.accountType: "96" for CASH benefits
balance.amount: Available CASH benefits

Important Notes:

No amount field is required for balance inquiry
PIN authentication is required
Separate inquiries needed for FOOD and CASH balances
Balance inquiry does not deduct from benefits

Transaction Reversal

Transaction reversal (timeout reversal) is used to reverse an EBT transaction when the terminal doesn't receive a response within the expected timeframe.

EBT Reversal Request

curl --location 'https://apitest.valorvpc.com/payment/txn-timeout' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "txn_timeout",
  "card": "ebt",
  "amount": "100",
  "ref_id": "da8b8b9f-ae8e-4940-bd50-ea03afd72423"
}'

Required Fields:

paymentType: "txn_timeout" - Indicates a reversal request
card: "ebt" - Card type
ref_id: Reference ID from the original transaction to reverse
amount: Original transaction amount (must match exactly)

Important Notes:

Reversals must be sent within a specific time window (typically 24 hours)
The ref_id must match the original transaction's reference ID
Amount must match the original transaction amount exactly
No card data or PIN required for reversals (only the ref_id)
Same reversal endpoint used for both FOOD and CASH transactions

Field Validations

Required Fields by Transaction Type

EBT Sale Transactions

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier (EBT-authorized)
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`sale`	Transaction type
`amount`	Yes	String/Number	Amount in USD (e.g., "100" or "100.00")
`entryMode`	Yes	`swiped`, `keyed`	Card entry method
`commerceIndicator`	Yes	`retail`	Transaction environment
`ebtCategory`	Yes	`FOOD`, `CASH`	Benefit type
`pin_block`	Conditional	String	Required except for voucher transactions
`pin_format`	Conditional	`0`, `1`	Required except for voucher transactions
`ksn`	Conditional	String	Required except for voucher transactions
`voucherSerialNumber`	Conditional	String (15 digits)	Required for voucher transactions only
`cardData`	Yes	Object	Card information

EBT Refund Transactions

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`refund`	Transaction type
`card`	Yes	`ebt`	Required for refunds
`amount`	Yes	String/Number	Amount in USD
`entryMode`	Yes	`swiped`, `keyed`	Card entry method
`commerceIndicator`	Yes	`retail`	Transaction environment
`ebtCategory`	Yes	`FOOD`, `CASH`	Benefit type
`pin_block`	Yes	String	Encrypted PIN block
`pin_format`	Yes	`0`, `1`	PIN format
`ksn`	Yes	String	Key Serial Number
`cardData`	Yes	Object	Card information

Balance Inquiry

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`balance_inquiry`	Transaction type
`commerceIndicator`	Yes	`retail`	Transaction environment
`entryMode`	Yes	`swiped`, `keyed`	Card entry method
`ebtCategory`	Yes	`FOOD`, `CASH`	Benefit type to check
`pin_block`	Yes	String	Encrypted PIN block
`pin_format`	Yes	`0`, `1`	PIN format
`ksn`	Yes	String	Key Serial Number
`cardData`	Yes	Object	Card information

Transaction Reversal

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`txn_timeout`	Reversal transaction type
`card`	Yes	`ebt`	Card type
`amount`	Yes	String/Number	Original transaction amount
`ref_id`	Yes	UUID	Reference ID from original transaction

Card Data Validations by Entry Mode

Swiped Entry Mode

Required Fields:

{
  "cardData": {
    "trackData": "string" // Track 2 data (required)
  }
}

OR for some processors:

{
  "cardData": {
    "emvData": {
      "trackData": "string" // Track 2 data (required)
    }
  }
}

trackData: Format ;[PAN]=[Expiry][Service Code][Discretionary Data]?
Example: ;5061123456789012=29121234567890123456?

Keyed Entry Mode

Required Fields:

{
  "cardData": {
    "panNumber": "string", // 16-digit card number (required)
    "expiryDate": "string" // MMYY format (required)
  }
}

panNumber: 16-digit Primary Account Number (e.g., "5061123456789012")
expiryDate: Expiration date in MMYY format (e.g., "1229" for December 2029)

EBT Category Validations

Category	Description	Eligible Items	Account Type Code
`FOOD`	SNAP benefits	Eligible food items only	`98`
`CASH`	TANF benefits	Any purchase, cash withdrawal	`96`

FOOD Eligible Items:

Fruits and vegetables
Meat, poultry, and fish
Dairy products
Breads and cereals
Seeds and plants (for growing food)

FOOD Ineligible Items:

Alcohol and tobacco
Hot prepared foods
Non-food items (soap, paper products, pet food)
Vitamins and medicines

Voucher Validations

For voucher-based transactions:

Field	Required	Format	Description
`voucherSerialNumber`	Yes	String (15 digits)	Voucher identifier
`ebtCategory`	Yes	`FOOD`	Typically FOOD only
`entryMode`	Yes	`keyed`	Manual entry
`cardData.panNumber`	Yes	String	Card number from voucher
`cardData.expiryDate`	Yes	String (MMYY)	Expiration date

Important: Voucher transactions do NOT require pin_block, pin_format, or ksn.

PIN Block Validations

PIN Block: Encrypted PIN data in hexadecimal format
PIN Format:
- "0": ISO Format 0 - Standard format for EBT
- "1": ISO Format 1 - Alternative format
KSN (Key Serial Number): Unique identifier for DUKPT encryption key
- Format: Hexadecimal string
- Used to derive the transaction key for PIN decryption

Amount Validations

Must be a positive number greater than zero
Maximum 2 decimal places
Minimum amount: $0.01
Maximum amount: Limited by available benefits balance
Format: Can be string ("100" or "100.00") or number (100)
Not required for balance inquiry transactions

Response Codes

Code	Status	Description	Action
`00`	AUTHORIZED	Transaction approved	Complete transaction
`05`	DECLINED	Do not honor	Request different payment method
`51`	DECLINED	Insufficient funds	Check balance or reduce amount
`54`	DECLINED	Expired card	Card has expired
`55`	DECLINED	Incorrect PIN	Allow customer to retry (max 3 attempts)
`57`	DECLINED	Transaction not permitted	Card not authorized for this transaction type
`61`	DECLINED	Exceeds withdrawal limit	Reduce amount
`91`	DECLINED	Issuer unavailable	Retry later

Account Type Codes (Balance Inquiry Response)

Code	Account Type	Description
`96`	EBT Cash	TANF cash benefits
`98`	EBT Food	SNAP food benefits

API Endpoint Reference

Base URL

Test Environment: https://apitest.valorvpc.com

Authentication

All requests require the X-App-Key header:

X-App-Key: your-app-key-here

Endpoints

Endpoint	Method	Description
`/payment/sale`	POST	Process EBT sale transaction
`/payment/refund`	POST	Process EBT refund transaction
`/payment/balance-inquiry`	POST	Check EBT benefits balance
`/payment/txn-timeout`	POST	Reverse EBT transaction (timeout)

Headers

Content-Type: application/json
X-App-Key: {your-app-key}

Summary

EBT payment processing requires:

Benefit Categories: Support for FOOD (SNAP) and CASH (TANF) benefits
PIN Authentication: Required for all transactions except vouchers
Entry Modes: Primarily swiped and keyed (contactless/contact less common)
Item Eligibility: Validation for FOOD benefit purchases
Balance Inquiry: Check available benefits before purchase
Split Tender: Support for combining EBT with other payment methods
Compliance: Federal and state EBT program regulations
Reversals: Timeout reversal capability for failed transactions
Voucher Support: Optional voucher-based transactions without PIN