triPOS REST API

<back to all web services

BalanceRequest

The following routes are available for this service:
POST/api/v1/balanceRequests a balance for a gift card.
BalanceRequest Parameters:
NameParameterData TypeRequiredDescription
ConfigurationbodyRequestConfigurationNoAny value included in this section will override the corresponding value set in the triPOS.config
LaneRequest Parameters:
NameParameterData TypeRequiredDescription
CardHolderPresentCodebodyCardHolderPresentCode?NoDefines whether the card holder is present at the transaction. This value is optional, but recommended to be set. If this value is not set in the request, it will be automatically set based on the market code.

Allowable Values

  • Default
  • Unknown
  • Present
  • NotPresent
  • MailOrder
  • PhoneOrder
  • StandingAuth
  • ECommerce
ClerkNumberbodystringNoAn optional clerk number for reference.
LaneIdbodyintNoSpecifies which lane to use.
ReferenceNumberbodystringNoA user defined reference number. This reference number is returned in the response
ShiftIdbodystringNoAn optional shift id for reference.
TicketNumberbodystringNoAn optional ticket number.
RequestConfiguration Parameters:
NameParameterData TypeRequiredDescription
AllowPartialApprovalsbodybool?NoIf set to true, partial approvals are allowed
CheckForDuplicateTransactionsbodybool?NoIf set to true, enables duplicate checking logic for the transaction at the host.
CurrencyCodebodyCurrencyCode?NoThe currency code of the transaction.

Allowable Values

  • None
  • Cad
  • Usd
  • Eur
MarketCodebodyMarketCodeNoThe market code of the transaction.

Allowable Values

  • Default
  • AutoRental
  • DirectMarketing
  • ECommerce
  • FoodRestaurant
  • HotelLodging
  • Petroleum
  • Retail
  • Qsr
BalanceResponse Parameters:
NameParameterData TypeRequiredDescription
AccountNumberbodystringNoThe card account number.
BalanceAmountbodydecimalNoThe balance of the gift card.
BalanceCurrencyCodebodystringNoThe balance currency code.
BinValuebodystringNoThe BIN entry that matched the account number.
CardLogobodystringNoThe card logo (e.g. Visa, Mastercard, etc).
EntryModebodystringNoDescription of how card was entered: Keyed, Swiped, Chip.
ExpirationYearbodystringNoThe card's expiration year. NOTE: Not all cards that support balance inquiry will have an expiration date.
ExpirationMonthbodystringNoThe card's expiration month. NOTE: Not all cards that support balance inquiry will have an expiration date.
PaymentTypebodystringNoDescription of how card payment type: None, Credit, Debit.
TerminalIdbodystringNoThe ID of the terminal used during the transaction
BaseResponse Parameters:
NameParameterData TypeRequiredDescription
ApprovalNumberbodystringNoApproval number from the processor. Depending on card type and processor an approval number might not be returned.
IsApprovedbodyboolNoSet to true if the host approved the transaction.
ProcessorbodyProcessorNoResponse information from the processor.
StatusCodebodyTransactionFlowStatusNoThe status code for the transaction.

Allowable Values

  • None
  • Success
  • Declined
  • Approved
  • Restart
  • Failed
  • HostError
  • Timeout
  • FailedVerification
  • CardError
  • UnknownCard
  • UnsupportedCard
  • DeviceError
  • Cancelled
  • ChipError
  • PinPadError
  • PinPadTimeout
  • InvalidLane
  • SwipedCardIsChipCapable
  • ApprovedByMerchant
  • ChipReaderError
  • UseChipReader
  • UseMagneticStripe
  • CardRemoved
  • CardBlocked
  • CardNotSupported
  • BadCard
  • CandidateListEmpty
  • IssuerAuthenticationFailed
  • CardDataEncryptionNotEnabled
  • ApprovedExceptCashback
  • ApplicationBlocked
TransactionDateTimebodystringNoTransaction date/time in ISO8601 format
TransactionIdbodystringNoThe transaction ID from the processor
MerchantIdbodystringNoThe Merchant used to process the transaction.

To override the Content-type in your clients, use the HTTP Accept Header, append the .xml suffix or ?format=xml

HTTP + XML

The following are sample HTTP requests and responses. The placeholders shown need to be replaced with actual values.

POST /xml/reply/BalanceRequest HTTP/1.1 
Host: booking.pufferdayspa.com 
Content-Type: application/xml
Content-Length: length

<balanceRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://tripos.vantiv.com/2014/09/TriPos.Api">
  <cardHolderPresentCode>Default</cardHolderPresentCode>
  <clerkNumber>String</clerkNumber>
  <laneId>0</laneId>
  <referenceNumber>String</referenceNumber>
  <shiftId>String</shiftId>
  <ticketNumber>String</ticketNumber>
  <configuration>
    <allowPartialApprovals>false</allowPartialApprovals>
    <checkForDuplicateTransactions>false</checkForDuplicateTransactions>
    <currencyCode>None</currencyCode>
    <marketCode>Default</marketCode>
  </configuration>
</balanceRequest>

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length

<balanceResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://tripos.vantiv.com/2014/09/TriPos.Api">
  <_errors>
    <error>
      <developerMessage>String</developerMessage>
      <errorType>String</errorType>
      <exceptionMessage>String</exceptionMessage>
      <exceptionTypeFullName>String</exceptionTypeFullName>
      <exceptionTypeShortName>String</exceptionTypeShortName>
      <userMessage>String</userMessage>
    </error>
  </_errors>
  <_hasErrors>true</_hasErrors>
  <_links />
  <_logs xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:string>String</d2p1:string>
  </_logs>
  <_type>String</_type>
  <_warnings>
    <warning>
      <developerMessage>String</developerMessage>
      <userMessage>String</userMessage>
    </warning>
  </_warnings>
  <_processor>
    <expressResponseCode>String</expressResponseCode>
    <expressResponseMessage>String</expressResponseMessage>
    <hostResponseCode>String</hostResponseCode>
    <hostResponseMessage>String</hostResponseMessage>
    <logs xmlns:d3p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <d3p1:string>String</d3p1:string>
    </logs>
    <processorLogs xmlns:d3p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <d3p1:string>String</d3p1:string>
    </processorLogs>
    <processorRawResponse>String</processorRawResponse>
    <processorReferenceNumber>String</processorReferenceNumber>
    <processorRequestFailed>false</processorRequestFailed>
    <processorRequestWasApproved>false</processorRequestWasApproved>
    <processorResponseCode>Unknown</processorResponseCode>
    <processorResponseMessage>String</processorResponseMessage>
    <rawResponse>String</rawResponse>
  </_processor>
  <approvalNumber>String</approvalNumber>
  <isApproved>false</isApproved>
  <merchantId>String</merchantId>
  <statusCode>None</statusCode>
  <transactionDateTime>String</transactionDateTime>
  <transactionId>String</transactionId>
  <accountNumber>String</accountNumber>
  <balanceAmount>0</balanceAmount>
  <balanceCurrencyCode>String</balanceCurrencyCode>
  <binValue>String</binValue>
  <cardLogo>String</cardLogo>
  <entryMode>String</entryMode>
  <expirationMonth>String</expirationMonth>
  <expirationYear>String</expirationYear>
  <paymentType>String</paymentType>
  <terminalId>String</terminalId>
</balanceResponse>