Transaction Request

Request Body

application/xml

AuthKey*string

Specifies the Auth-Key, which authorizes the Host system to use the SPIn Web Service. Necessary for all SPIn Proxy connections, optional for direct terminal connections.

Lengthlength <= 25

PaymentType*string

Identifies the EDC (Electronic Data Capture) type — Credit, Debit, EBT_Food, EBT_Cash (Electronic Benefits Transfer), userChoice, or Gift.

If userChoice is sent, the terminal lets the customer choose between Credit, Debit, or EBT during payment; the response's PaymentType field reflects the option the customer actually selected. See the TransType field for which transaction types each PaymentType supports.

Lengthlength <= 20

TransType*string

Identifies the type of transaction to run. Balance applies only to EBT_Food/EBT_Cash.

Supported TransType values per PaymentType (US):

Credit: Sale, Return, Void, Auth, Capture, CashAdvance*
Debit: Sale, Return
EBT_Food: Sale, Return
EBT_Cash: Sale, Return
Gift: Activate, Inquire, Redeem, Refund, Reload, Deactivate, Reissue, Void

* CashAdvance is only available for certain processors.

Lengthlength <= 20

Amount*number

Dollar amount of the transaction ($$$$$$$.CC) — the total amount, including tip if one was added (base + tip). Not used for Loyalty transactions, which use a Points value instead. Must always be a positive value, even for Returns.

Tip?number

Specifies the tip amount in dollars to be applied to the transaction. Tip must be enabled on the payment terminal..

CashbackAmount?number

Cashback amount of the transaction ($$$$$$$.CC). Only valid on Debit or EBT payment types. Available on builds later than 5/17/19 and Aura.

Frequency?string

Indicates whether this is a one-time or recurring transaction.

CustomFee?number

Dollar amount of the transaction ($$$$$$$.CC). Whatever fee type is enabled in the TPN configuration, the provided amount will be considered the custom fee.

IsvId?string

16-character alphanumeric ISV identifier, e.g. 100001 for CP-PINPAD (cloud POS pinpad transaction).

Lengthlength <= 16

ReconId?string

Used for reconciliation purposes. Applicable only to Fiserv North and Elavon transactions, and optional. An alphanumeric reference ID linking the transaction to its corresponding settlement record — 11 characters for Fiserv North, 24 characters for Elavon.

Lengthlength <= 10

RefId*string

Alphanumeric reference field that must be unique within the scope of an open batch. Set by the host system and mandatory for all deployments. Used for Tip or other transaction-adjustment requests related to a specific transaction (e.g. Tip Adjustment or Void Transaction). For the Table payment type, the RefId does not need to be unique within a batch.

Lengthlength <= 50

RegisterId*string

Alphanumeric reference field.

Lengthlength <= 50

TPN?string

Alphanumeric. Can be used instead of RegisterId, only for Dejavoo SPIn Proxy connections — e.g. <RegisterId>21123001</RegisterId><AuthKey>12345678</AuthKey> works the same as <TPN>12345678912</TPN><AuthKey>12345678</AuthKey>.

Lengthlength <= 12

PrintReceipt?string

No = transaction receipt won't be printed on the terminal; Merchant = print Merchant copy only; Customer = print Customer copy only; Both = print both Merchant and Customer copies (default).

Lengthlength <= 50

Value in"No" | "Merchant" | "Customer" | "Both"

ReducedStateTax?string

Reduced state tax applied to this transaction. Reduced tax must be enabled on the terminal.

StateTax?string

State tax applied to this transaction. Tax must be enabled on the terminal.

CityTax?string

City tax applied to this transaction. Tax must be enabled on the terminal.

SigCapture?string

If set to "No", the terminal suppresses the signature capture event during the transaction. If not included or set to "Yes", the terminal captures a signature (if the terminal supports signature capture).

Lengthlength <= 3

Value in"Yes" | "No"

Tag1?string

The portal supports up to three tags. Tag labels can be enabled for the TPN from the portal via S.T.E.A.M → Search and Select TPN → Edit Parameter → Value Add → Enable Tag the Tx. The label for each tag must be configured in Edit Parameter. Once processed, the tag value is printed on the merchant copy of the receipt; transactions can also be filtered by this tag value on the portal, and the settlement report includes it.

Lengthlength <= 8

Tag2?string

Same as Tag1.

Lengthlength <= 8

Tag3?string

Same as Tag1.

Lengthlength <= 8

PerformedBy?string

Identifies the user who performed the transaction. For a Cloud POS + PIN pad transaction, this identifies the merchant user (i.e. the merchant's email ID) who initiated it. The terminal uploads this information to the portal as part of the signature upload process; it's visible on the portal and included in the downloadable transaction report.

Lengthlength <= 100

MerchantId?string

Optional for regular transactions when Multi MID (MMID) is not enabled. Mandatory when MMID is enabled — must be the TPN through which the transaction is intended to be processed. In the iPOSpays environment, each MID is tied to a specific TPN, so the correct TPN must be sent to route the transaction to the appropriate MID, e.g. <AuthKey>12345678</AuthKey><TPN>MasterTPN</TPN><MerchantId>TransactingTPN</MerchantId>.

Lengthlength <= 12

CustomerEmail?string

Used to send the customer's email address.

CustomerMobile?string

Used to send the customer's mobile number. If provided, the country code (extension) is mandatory (e.g. +1) along with a valid 10-digit phone number.

IsTxnStatusScreenRequired?boolean

Indicates whether the terminal should display the transaction status screen after processing.

ReducedStateTax(Hacienda) Specifies the reduced state tax amount applied to transactions subject to Puerto Rico Hacienda tax regulations. Include this field when the transaction contains eligible items, such as prepared or ready-to-eat food, that qualify for a reduced tax rate.

Response Body

`application/xml`

curl -X GET "https://example.com" \  -H "Content-Type: application/xml" \  -d '<request>    <AuthKey/>    <PaymentType>Credit</PaymentType>    <TransType>Sale</TransType>    <Amount>1.00</Amount>    <Tip>0.00</Tip>    <CashbackAmount>0.00</CashbackAmount>    <Frequency>OneTime</Frequency>    <CustomFee>0.00</CustomFee>    <IsvId/>    <ReconId/>    <RefId>12234</RefId>    <RegisterId/>    <TPN/>    <PrintReceipt>No</PrintReceipt>    <ReducedStateTax/>    <StateTax/>    <CityTax/>    <SigCapture>No</SigCapture>    <Tag1/>    <Tag2/>    <Tag3/>    <PerformedBy/>    <MerchantId/>    <CustomerEmail>sai@gmail.com</CustomerEmail>    <CustomerMobile>+15418996990</CustomerMobile>    <IsTxnStatusScreenRequired>true</IsTxnStatusScreenRequired>  </request>'

<response>
  <RefId>12234</RefId>
  <RegisterId>7632070</RegisterId>
  <AuthCode>TAS330</AuthCode>
  <PNRef>532212500069</PNRef>
  <TransNum>6</TransNum>
  <ResultCode>0</ResultCode>
  <Message>Approved</Message>
  <RespMSG>APPROVAL TAS330</RespMSG>
  <PaymentType>Credit</PaymentType>
  <Voided>false</Voided>
  <TransType>Sale</TransType>
  <SN>B17912107210030</SN>
  <Receipt>Merchant Copy</Receipt>
  <ExtData>Amount=1.00,dueAmnt=,isPartialApprovalTxn=false,approvedAmnt=,InvNum=6,CardType=VISA,cardBrandType=,Tip=0.20,Fee=0.04,Disc=0.00,DiscLabel=,BatchNum=10,CashBack=0.00,AcntLast4=5439,AcntFirst4=4012,BIN=401200,Name=DenovoPay,FeeLabel=Custom Fee,BaseAmount=1.00,TxnCode=1,TaxCity=0.20,Tax1Label=Local Tax,customCashMessage=,customCreditMessage=,TaxState=0.10,Tax2Label=State Tax,TaxCommercial=0.00,CDCVMIndicator=D,TipLine=0,RespCode=00,RRN=532212500069,TraceNum=6,HostTxnId=000000000628722,txnId=00000333992531176620251118073720,PrintSaveMsg=,isIbs=false,isSurChargeApplied=false,isFeeAppliedForDebitCard=true,isDiscloseFeeToCustomer=true,isPockytWalletMode=false,L2L3flag=,IsvId=23454,TxnType=1,EntryType=Manual Entry,TotalAmt=1.54,TaxAmount=0.30,isGiftMode=false,GiftBalAmount=,Balance=,EBTFSAvailBalance=,EBTCashAvailBalance=,ebtCashBalAmount=,isWalletMode=false,txnLabel=SALE,surveyQuestion=,surveyAnswer=,walletPayMethod=,walletTxnPaymentNum=,walletTxnData=,deviceId=,walletConfirmationId=,SignLine=,SignPath=,profileId=,profileName=,offlinePin=false,fallBackMode=0,networkMode=WIFI,txnStartTime=1763469440905,txnEndTime=1763469453711,pagoWalletFlashMessage=,pagoConfirmationCode=,pagoCommittedTransactionId=,pagoMerchantTransactionId=,ReducedTax=0.00,ReducedTaxFee=0.00,RTaxLabel=,ExpDate=1225,MSRPLabel=,MSRPAmount=,DateTime=2025-11-18 07:37:20</ExtData>
  <EMVData>AID=A0000000041010,AppName=DEBITMASTERCARD,TVR=0000008001,TSI=A000,IAD=,ARC=</EMVData>
  <iPOSToken>0B44FE32F4032486B0A434BAEBAB001628A71B677407F8D5</iPOSToken>
  <HostResponseCode>00</HostResponseCode>
  <HostResponseMessage>APPROVAL TAS330</HostResponseMessage>
</response>

Transaction Request

Request Body

Response Body

200application/xml

Approval Response from Terminal

Decline Response from Terminal

Timeout Response from Terminal

`application/xml`