| Required role: | Merchant |
| POST | /v2/transactions/ebt | Run an electronic bank transfer transaction. |
|---|
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| TransactionType | model | TransactionType? | Yes | Identifies the type of transaction to process.Allowable Values
|
| MerchantFNS | model | string | No | Merchant FNS |
| EbtType | model | EBTType? | Yes | Identifies whether the EBT card is being used for Cash Benefit or SNAP transactions.Allowable Values
|
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| CardData | model | TransactionCardData | No | Properties of the card used as payment for this transaction. |
| IgnoreBinData | query | bool | No | Properties of the card used as payment for this transaction. |
| VoucherNumber | model | string | No | Used in VoucherClear requests. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| EntryMode | model | EntryMode | No | The method in which card data was collected. This is used in conjunction with other properties of the transaction to determine the correct values for card and cardholder presence to send to the processor.Allowable Values
|
| AuthorizationCode | model | string | No | Authorization/approval code |
| IsConsecutiveFallback | model | bool | No | This value is used on TSYS transaction requests to inform the gateway if this is a consecutive fallback in order to properly set the chip condition code to the TSYS specification. As such it is only used on transactions with a TechnicalFallback or an EmptyCandidateFallback entry mode. This value defaults to 'false' so it is only necessary to set it when declaring it is 'true'. |
| PurchaseCardData | model | PurchaseCardData | No | Required to qualify transactions for level 2 and level 3 processing. |
| CardOnFile | model | CardOnFile | No | Contains information related to a card on file transaction. |
| IsOfflineTransaction | model | bool | No | Signifies an offline transaction. This value defaults to 'false' so it is only necessary to set it when declaring it is 'true'. |
| SecureTransaction | model | SecureTransaction | No | Parameters for secure Ecommerce transaction authentication. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| ForceDuplicate | model | boolean | No | This is an indicator that specifies - if this transaction is flagged as a duplicate of a previous transaction - whether or not this transaction will be processed. |
| Register | model | string | No | Identifies the physical or virtual register where the transaction is run, for reporting. |
| InvoiceData | model | InvoiceData | Yes | Tracking/reporting fields used for identifying the transaction and associating it with a customer invoice. |
| DeviceData | model | DeviceData | No | Properties of the terminal/reader used in the transaction. |
| OriginalTransaction | model | AssociatedTransaction | No | Properties of the original transaction, when necessary for processing the current transaction (such as refunds, voids, reversals). |
| CustomFields | model | List<CustomField> | No | Merchant-configured fields used to store data per transaction outside the system fields. |
| CustomerID | model | string | No | Identifies the customer that is associated with this transaction. |
| CustomerKey | model | int | No | Identifies the customer key that is associated with this transaction. Customer Key takes priority over Customer ID |
| Tags | model | List<string> | No | A collection of tag data that will be associated with this transaction. Each tag is limited to 20 characters, character length greater than 20 will be truncated. |
| MerchantOptions | model | MerchantOptions | No | Merchant specific transaction parameters. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| InvoiceNumber | model | string | No | Unique identifier for the customer/cardholder |
| OrderNumber | model | string | No | ... |
| TotalAmount | model | number | Yes | Total amount of the transaction |
| TipAmount | model | number | No | Amount charged at the card holder's discretion for tip/gratuity |
| ShippingAmount | model | number | No | ... |
| SalesTaxAmount | model | number | No | Amount charged by a merchant for state/local sales tax |
| DutyAmount | model | number | No | ... |
| DiscountAmount | model | number | No | Amount of discount that was applied. |
| ConvenienceAmount | model | number | No | Allows the merchant to add a flat fee to the total transaction. This function may be used by utility companies, government agencies, and schools. |
| ConvenienceAmountPercentage | model | decimal? | No | Allows the merchant to add a percentage of the total amount as a fee to the total transaction (ex 10.5 would add a 10.5% fee). This function may be used by utility companies, government agencies, and schools. |
| SurchargeAmount | model | number | No | Amount charged by a merchant in exchange for processing a specific transaction |
| CashBackAmount | model | number | No | Amount requested by the card holder in cash back for an eligible transaction |
| FSA | model | FSA | No | Includes medical specific payment amounts. |
| IsEstimatedAmount | model | bool | No | Set this to True when the amount sent in the initial transaction is an estimate. Visa transactions only. |
| IsTaxExempt | model | bool | No | Set this to True if this purchase is exempt from sales tax. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| ClinicalAmount | form | decimal? | No | |
| CopayAmount | form | decimal? | No | |
| HealthcareAmount | form | decimal? | No | |
| DentalAmount | form | decimal? | No | |
| RXAmount | form | decimal? | No | |
| TransitAmount | form | decimal? | No | |
| VisionAmount | form | decimal? | No | |
| IIASVerified | form | IIASVerified? | No | |
| CumulativeAmount | form | decimal? | No |
| False | |
| True | |
| Exempt |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| SdkVersion | form | string | No | The SDK version of the device |
| SerialNumber | form | string | No | The serial number of the device |
| BatteryLevel | form | int? | No | The current battery level of the device |
| IsEncrypted | form | bool | No | Indicates whether or not transaction data sent from the device is encrypted |
| EncryptionType | form | string | No | Type of encryption used when transaction data is encrypted |
| ReaderEncryptionType | form | string | No | Type of encryption used by the card reader during card swipe. "data" and "pin" are the only valid values. Data is the default value. |
| MagnePrint | form | string | No | Encrypted MagnePrint data for use with Magtek devices |
| MagnePrintStatus | form | string | No | MagnePrint status for use with Magtek devices |
| CVMResults | form | string | No | Returned from Discover transactions initated on an Igenico terminal to supplement the missing 9F34 tag for CVM. Valid values are "1: Offline PIN", "2: Online PIN", "E: Signature" |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| TransactionId | model | int | No | Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| Key | model | int? | No | Gateway key for the custom field |
| Name | model | string | No | Name of the custom field as set by the merchant |
| Value | model | string | No | Value (if applicable) to store in the custom field |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| MerchantCategoryCode | model | string | No | Identifies the category of a transaction (e.g. gas, grocery, travel). |
| Name | Value | |
|---|---|---|
| Unknown | 0 | |
| NotApplicable | 1 | |
| Manual | 2 | |
| UnencryptedCardReaderSwipe | 3 | |
| EncryptedCardReaderSwipe | 4 | |
| ICC | 5 | |
| Proximity | 6 | |
| Fallback | 8 | |
| TechnicalFallback | 9 | |
| EmptyCandidateFallback | 10 |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| PurchaseOrderNumber | model | string | No | ... |
| TotalAmount | model | decimal? | No | ... |
| MerchantPostalCode | model | string | No | ... |
| IsTaxExempt | model | bool | No | ... |
| ShipFromPostalCode | model | string | No | ... |
| DestinationPostalCode | model | string | No | ... |
| DestinationState | model | string | No | ... |
| DestinationCountryCode | model | int? | No | ... |
| MerchantTaxId | model | string | No | ... |
| TransactionDate | model | DateTime | No | ... |
| PurchaseCardLineItemData | model | List<PurchaseCardLineItemData> | No | ... |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| UniversalProductCode | model | string | No | ... |
| CommodityCode | model | string | No | ... |
| ProductDescription | model | string | No | ... |
| ItemCode | model | string | No | ... |
| ItemDescription | model | string | No | ... |
| InvoiceNumber | model | string | No | ... |
| Quantity | model | int? | No | ... |
| QuantityExponent | model | int? | No | ... |
| UnitOfMeasure | model | string | No | ... |
| UnitPrice | model | decimal? | No | ... |
| UnitPriceExponent | model | int? | No | ... |
| DiscountAmount | model | decimal? | No | ... |
| IsDiscountIncluded | model | bool? | No | ... |
| LineItemAmount | model | decimal? | No | ... |
| TaxAmount | model | decimal? | No | ... |
| TaxAmountExponent | model | int? | No | ... |
| TaxRate | model | decimal? | No | ... |
| TaxType | model | string | No | ... |
| ExtendedAmount | model | decimal? | No | ... |
| FreightAmount | model | decimal? | No | ... |
| DutyAmount | model | decimal? | No | ... |
| IsTaxIncluded | model | bool? | No | ... |
| DebitCardIndicator | model | string | No | ... |
| IsTaxExempt | model | bool? | No | ... |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| InitialTransaction | form | bool | No | |
| Scheduled | form | bool | No | |
| InitiatedBy | form | string | No |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| VisaXid | form | string | No | A unique transaction ID set by the merchant and sent to the Issuer Authentication/Service in the Authentication Request message |
| VisaSecureTrxAuthData | form | string | No | A cryptographic value that is generated during the VISA transaction authentication process i.e. VISA CAVV (3-D Secure) or an ApplePay In-App token transaction |
| AmexXid | form | string | No | A unique transaction ID set by the merchant and sent to the Issuer Authentication/Service in the Authentication Request message |
| AmexSecureData | form | string | No | A cryptographic value that is generated during the Amex transaction authentication process i.e. American Express AEVV |
| DiscoverSecureData | form | string | No | A cryptographic value that is generated during the Discover and Diners transaction authentication process or an In-App token transaction. |
| DiscoverAuthType | form | string | No | This field specifies the type of secure transaction used. |
| MasterCardSecureData | form | string | No | A cryptographic value that is generated during the MasterCard transaction authentication process (MasterCard UCAF/ SecureCode) or statically assigned to the merchant by MasterCard. |
| UcafCollectionIndicator | form | UcafCollectionIndicators? | No | Indicates whether the merchant supports MasterCard UCAF (Secure Code) data collection. |
| EcommTransactionIndicator | form | EcommTrxIndicators? | No | An indicator provided by the merchant to identify the security level of an Ecommerce transaction. |
| NotSupported | |
| SupportedAndAttemptedAAV | |
| SupportedAndFullyAuthenticatedAAV | |
| EcommerceCompletion | |
| MasterCardRiskBasedDecisioning | |
| IssuerRiskBasedDecisioning | |
| MerchantRiskBasedDecisioning | |
| StaticAAV | |
| PartialShipmentRecurringPaymentMIT |
| Name | Value | |
|---|---|---|
| SecureEcommTrx | 1 | |
| NonAuth3ds | 2 | |
| ChannelEncrypted | 3 | |
| NonSecureEcommTrx | 4 | |
| DigitalWallet | 5 | |
| MasterPass | 6 | |
| MasterCardDigitalEnhancement | 7 | |
| UP3DSAuthMode | 8 | |
| ChannelEncryptionNoCardCertificate | 21 | |
| MasterPassGenerated | 22 | |
| DigitalSecureRemotePayment | 24 | |
| NoSecurityProtocol | 91 |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| CardNumber | model | string | No | Credit card number used to uniquely identify the card owner’s account. |
| ExpirationDate | model | string | No | Credit card date of expiration in MMYY format. |
| NameOnCard | model | string | No | Name of the cardholder, as displayed on the card |
| TrackData | model | string | No | The magnetic stripe/track data read from a swiped transaction. If the card reader is capable of reading both track 1 and track 2, only track 2 should be provided. |
| EncryptedTrack1Data | model | string | No | The encrypted magnetic stripe/track 1 data read from a secure reader |
| EncryptedTrack2Data | model | string | No | The encrypted magnetic stripe/track 2 data read from a secure reader |
| EncryptedTrack3Data | model | string | No | The encrypted magnetic stripe/track 3 data read from a secure reader |
| IIN | model | string | No | The card IIN when using an encrypted magnetic stripe/track data read from a secure reader |
| PIN | model | string | No | The encrypted PIN-block returned by the PIN pad. The transaction will fail if an unencrypted PIN is used. Note: This information is not required for PIN-less debit transactions. |
| ARQC | model | string | No | The encrypted ARQC generated from a secure reader chip-based transaction |
| KeySerialNumber | model | string | No | PIN pad serial number used in managing DUKPT PIN pads. This is required for all transactions where a pin is present |
| Presentation | model | Presentation | No | Optional information about the presentation of the card and CVV value. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| CVVPresence | model | CVPresence | No | Indicates the status of the presentation of the card's CVV value. Defaults to 'None'.Allowable Values
|
| IsCardPresent | model | bool | No | Indicates if the card is present. Defaults to 'true'. |
| None | |
| NotSubmitted | |
| Submitted | |
| Illegible | |
| NotPresent |
| Void | |
| Settle | |
| SettleAll | |
| Reversal | |
| Refund | |
| Sale | |
| AuthOnly | |
| OfflineAuth | |
| CardVerify | |
| AuthCapture | |
| Adjustment | |
| RepeatSale | |
| BalanceInquire |
| CashBenefit | |
| Snap |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| CardDetails | form | BankCardResponseDetail | No | Bank card specific response details. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| TransactionId | model | int | No | Gateway transaction ID/reference number. |
| TransactionType | model | string | Yes | Identifies the type of transaction processed. |
| Token | model | string | No | A value generated by the gateway for payment data which has been previously stored. The format of the value depends on the format selected when the payment method was originally stored. |
| MerchantKey | model | int | No | System-generated unique identifier of the merchant. |
| CustomerID | model | string | No | Customer ID related to the transaction. |
| CustomerKey | model | int | No | Customer Key related to the transaction. |
| TransactionIpAddress | model | string | No | IP Address of host the transaction request originated from. |
| HostCode | model | string | No | Host code/transaction id. |
| ResponseMessage | model | string | No | Text description of the transaction result or error. |
| ResultCode | model | int | No | Gateway code indicating the result of the transaction or error.Allowable Values
|
| ProcessorErrorCode | model | string | No | The error code, if any, returned by the processor. |
| ResultText | model | string | No | Short description of the transaction result. |
| InvoiceData | model | InvoiceData | Yes | Tracking/reporting fields used for identifying the transaction and associating it with a customer invoice. |
| CustomFields | model | List<CustomField> | No | Any merchant-defined custom fields and their associated values. |
| Timestamp | model | DateTime | No | Timestamp when transaction was processed. |
| UserName | model | string | No | Username for this transaction. |
| Register | model | string | No | Register used for this transaction. |
| ResellerKey | model | int | No | The merchant's reseller key. |
| PaymentType | model | string | No | Payment type for this transaction. |
| Processor | model | string | No | Name of the processor handling this transaction. |
| HostReferenceNumber | model | string | No | Timestamp when transaction was processed. |
| OriginalTransaction | form | AssociatedTransaction | No | Properties of the original transaction. |
| Tags | model | List<string> | No | A collection of the transaction's tag data (if present). |
| OrigResponseCode | form | string | No | The original response code received from the processor. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| AuthorizedAmount | form | decimal? | No | Amount authorized by processor. |
| AuthorizationCode | form | string | No | Authorization code assigned by processor. |
| EntryMode | model | string | No | The method in which payment data was collected. |
| CardData | form | TransactionCardData | No | Properties of the card used as payment for this transaction. |
| BINData | model | BINData | No | Bin data of the card used in the transaction. |
| CardValidationData | model | BankCardValidationData | No | Validation results of the card used in the transaction. |
| RawEMVResponse | model | string | No | Raw EMV response from the processor (if any). |
| AvailableBalance | form | decimal? | No | Available balance remaining on the card for benefit/prepaid cards. |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| BIN | form | long | No | The BIN/first 6-11 digits of the card |
| CardBrand | form | string | No | The card brand (VISA, MasterCard, American Express, etc |
| IssuingOrg | form | string | No | The organization/bank that issued the card |
| CardType | form | string | No | Typically debit or credit |
| CardCategory | form | string | No | The category indicating special types of card such as corporate, purchasing, and prepaid |
| IssuingCountry | form | string | No | The country where the card was issued |
| IssuingCountryCodeA2 | form | string | No | The A2 country code |
| IssuingCountryCodeA3 | form | string | No | The A3 country code |
| IssuingCountryNumber | form | int? | No | The issuing country number |
| IssuingPhone | form | string | No | Phone number, if available, of the issuing organization |
| IssuingWebsite | form | string | No | Web site, if available, of the issuing organization |
| PanLength | form | string | No | The length of credit card number |
| IssuedEntity | form | string | No | Defines if the BIN is PERSONAL or COMMERCIAL |
| IsRegulated | form | string | No | Indicates if the card is regulated (value range: 'Y', 'N'). |
| IsCommercial | form | bool | No | True if the IssuedEntity is equal to 'COMMERCIAL' |
| Name | Parameter | Data Type | Required | Description |
|---|---|---|---|---|
| AVSResponse | model | string | No | Address verification response code |
| CVResponse | model | string | No | Card verification response code |
| AVSResponseText | model | string | No | Text representation of the AVS response |
| CVResultText | model | string | No | Text representation of the CVV response |
| StreetMatchText | model | string | No | Additional detail on the AVS street match |
| ZipMatchText | model | string | No | Additional detail on the AVS zip match |
To override the Content-type in your clients, use the HTTP Accept Header, append the .json suffix or ?format=json
To embed the response in a jsonp callback, append ?callback=myCallback
The following are sample HTTP requests and responses. The placeholders shown need to be replaced with actual values.
POST /v2/transactions/ebt HTTP/1.1
Host: syntch.simpay.net
Accept: application/json
Content-Type: application/json
Content-Length: length
{"TransactionType":"FoodStampSale","MerchantFNS":"String","EbtType":"CashBenefit","CardData":{"CardNumber":"String","ExpirationDate":"String","NameOnCard":"String","TrackData":"String","EncryptedTrack1Data":"String","EncryptedTrack2Data":"String","EncryptedTrack3Data":"String","IIN":"String","PIN":"String","ARQC":"String","KeySerialNumber":"String","Presentation":{"CVVPresence":"None","IsCardPresent":false}},"IgnoreBinData":false,"VoucherNumber":"String","EntryMode":"Unknown","AuthorizationCode":"String","IsConsecutiveFallback":false,"PurchaseCardData":{"PurchaseOrderNumber":"String","TotalAmount":0,"MerchantPostalCode":"String","IsTaxExempt":false,"ShipFromPostalCode":"String","DestinationPostalCode":"String","DestinationState":"String","DestinationCountryCode":0,"MerchantTaxId":"String","TransactionDate":"0001-01-01T00:00:00.0000000","PurchaseCardLineItemData":[{"UniversalProductCode":"String","CommodityCode":"String","ProductDescription":"String","ItemCode":"String","ItemDescription":"String","InvoiceNumber":"String","Quantity":0,"QuantityExponent":0,"UnitOfMeasure":"String","UnitPrice":0,"UnitPriceExponent":0,"DiscountAmount":0,"IsDiscountIncluded":false,"LineItemAmount":0,"TaxAmount":0,"TaxAmountExponent":0,"TaxRate":0,"TaxType":"String","ExtendedAmount":0,"FreightAmount":0,"DutyAmount":0,"IsTaxIncluded":false,"DebitCardIndicator":"String","IsTaxExempt":false}]},"CardOnFile":{"InitialTransaction":false,"Scheduled":false,"InitiatedBy":"String"},"IsOfflineTransaction":false,"SecureTransaction":{"VisaXid":"String","VisaSecureTrxAuthData":"String","AmexXid":"String","AmexSecureData":"String","DiscoverSecureData":"String","DiscoverAuthType":"String","MasterCardSecureData":"String","UcafCollectionIndicator":"NotSupported","EcommTransactionIndicator":"0"},"ForceDuplicate":false,"Register":"String","InvoiceData":{"InvoiceNumber":"String","OrderNumber":"String","TotalAmount":0,"TipAmount":0,"ShippingAmount":0,"SalesTaxAmount":0,"DutyAmount":0,"DiscountAmount":0,"ConvenienceAmount":0,"ConvenienceAmountPercentage":0,"SurchargeAmount":0,"CashBackAmount":0,"FSA":{"ClinicalAmount":0,"CopayAmount":0,"HealthcareAmount":0,"DentalAmount":0,"RXAmount":0,"TransitAmount":0,"VisionAmount":0,"IIASVerified":"False","CumulativeAmount":0},"IsEstimatedAmount":false,"IsTaxExempt":false},"DeviceData":{"SdkVersion":"String","SerialNumber":"String","BatteryLevel":0,"IsEncrypted":false,"EncryptionType":"String","ReaderEncryptionType":"String","MagnePrint":"String","MagnePrintStatus":"String","CVMResults":"String"},"OriginalTransaction":{"TransactionId":0},"CustomFields":[{"Key":0,"Name":"String","Value":"String"}],"CustomerID":"String","CustomerKey":0,"Tags":["String"],"MerchantOptions":{"MerchantCategoryCode":"String"}}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{"CardDetails":{"AuthorizedAmount":0,"AuthorizationCode":"String","EntryMode":"String","CardData":{"CardNumber":"String","ExpirationDate":"String","NameOnCard":"String","TrackData":"String","EncryptedTrack1Data":"String","EncryptedTrack2Data":"String","EncryptedTrack3Data":"String","IIN":"String","PIN":"String","ARQC":"String","KeySerialNumber":"String","Presentation":{"CVVPresence":"None","IsCardPresent":false}},"BINData":{"BIN":0,"CardBrand":"String","IssuingOrg":"String","CardType":"String","CardCategory":"String","IssuingCountry":"String","IssuingCountryCodeA2":"String","IssuingCountryCodeA3":"String","IssuingCountryNumber":0,"IssuingPhone":"String","IssuingWebsite":"String","PanLength":"String","IssuedEntity":"String","IsRegulated":"String","IsCommercial":false},"CardValidationData":{"AVSResponse":"String","CVResponse":"String","AVSResponseText":"String","CVResultText":"String","StreetMatchText":"String","ZipMatchText":"String"},"RawEMVResponse":"String","AvailableBalance":0},"TransactionId":0,"TransactionType":"String","Token":"String","MerchantKey":0,"CustomerID":"String","CustomerKey":0,"TransactionIpAddress":"String","HostCode":"String","ResponseMessage":"String","ResultCode":0,"ProcessorErrorCode":"String","ResultText":"String","InvoiceData":{"InvoiceNumber":"String","OrderNumber":"String","TotalAmount":0,"TipAmount":0,"ShippingAmount":0,"SalesTaxAmount":0,"DutyAmount":0,"DiscountAmount":0,"ConvenienceAmount":0,"ConvenienceAmountPercentage":0,"SurchargeAmount":0,"CashBackAmount":0,"FSA":{"ClinicalAmount":0,"CopayAmount":0,"HealthcareAmount":0,"DentalAmount":0,"RXAmount":0,"TransitAmount":0,"VisionAmount":0,"IIASVerified":"False","CumulativeAmount":0},"IsEstimatedAmount":false,"IsTaxExempt":false},"CustomFields":[{"Key":0,"Name":"String","Value":"String"}],"Timestamp":"0001-01-01T00:00:00.0000000","UserName":"String","Register":"String","ResellerKey":0,"PaymentType":"String","Processor":"String","HostReferenceNumber":"String","OriginalTransaction":{"TransactionId":0},"Tags":["String"],"OrigResponseCode":"String"}