triPOS REST API

<back to all web services

TokenSaleRequest

The following routes are available for this service:
POST/api/v1/sale/tokenCreates a new card sale using a token based on the passed in amountsSee OmniToken documentation for more information.
TokenSaleRequest Parameters:
NameParameterData TypeRequiredDescription
TokenIdbodystringNoThe token ID used for the sale.
TokenProviderbodyTransactionTokenTypeNoThe type of token ID used for the sale.
VaultIdbodystringNoThe Vault ID used to create the token.
CardLogobodyCardBrandNoThe card logo of the card that the token represents.
ExpirationMonthbodystringNoThe expiration month of the card the token represents. Although this is not required, it is recommended for fraud protection.
ExpirationYearbodystringNoThe expiration year of the card the token represents. Although this is not required, it is recommended for fraud protection.
AddressbodyAddressNoThe cardholder address information for the transaction.
ConfigurationbodyRequestConfigurationNoAny value included in this section will override the corresponding value set in the triPOS.config
ConvenienceFeeAmountbodydecimalNoThe convenience fee amount of the transaction. This amount is added to the TotalAmount before the cardholder is charged
CreditSurchargeAmountbodydecimalNoThe credit surcharge amount of the transaction. This amount is added to the TotalAmount before the cardholder is charged
TipAmountbodydecimalNoThe tip amount of the transaction. This amount is added to the TotalAmount before the cardholder is charged.
TransactionAmountbodydecimalNoThe total transaction amount. This is the amount of funds to move on the card
LaneIdbodyintNoSpecifies which lane to use for the card sale.
ClerkNumberbodystringNoAn optional clerk number for reference.
ReferenceNumberbodystringNoA user defined reference number.
ShiftIdbodystringNoAn optional shift id for reference.
TicketNumberbodystringNoAn optional ticket number.
HealthcarebodyHealthcareNoThe healthcare section that contains all applicable healthcare-qualified amounts. more»
AutoRentalbodyAutoRentalNoThe auto rental parameters to be passed in for an auto rental transaction. more»
EstimatedAmountIndicatorbodystringNoThe EstimatedAmountIndicator can be used by merchants/integrators to define the TransactionAmount submitted to Express either as an Estimated Amount (i.e. amount to charge cardholder may change) or a Final Amount (i.e. amount to charge cardholder will not change). It will be a 1-character request field supporting the following request settings:

Allowable Values

  • (0 or empty/missing) = Default/Unknown
  • 1 = Estimated Amount
  • 2 = Final Amount
Address Parameters:
NameParameterData TypeRequiredDescription
BillingAddress1formstringNoThe street address used for billing purposes.
BillingAddress2formstringNoThe street address used for billing purposes.
BillingCityformstringNoThe name of the city used for billing purposes.
BillingEmailformstringNoThe e-mail address used for billing purposes.
BillingNameformstringNoThe name used for billing purposes.
BillingPhoneformstringNoThe phone number used for billing purposes. The recommended format is (800)555-1212.
BillingPostalCodeformstringNoThe postal code used for billing purposes.
BillingStateformstringNoThe name of the state used for billing purposes. This value may be any 2 character state code or the full state name.
ShippingAddress1formstringNoThe street address used for shipping purposes.
ShippingAddress2formstringNoThe street address used for shipping purposes.
ShippingCityformstringNoThe name of the city used for shipping purposes.
ShippingEmailformstringNoThe e-mail address used for shipping purposes.
ShippingNameformstringNoThe name used for shipping purposes.
ShippingPhoneformstringNoThe phone number used for shipping purposes. The recommended format is (800)555-1212
ShippingPostalCodeformstringNoThe postal code used for shipping purposes.
ShippingStateformstringNoThe name of the state used for shipping purposes. This value may be any 2 character state code or the full state name.
RequestConfiguration Parameters:
NameParameterData TypeRequiredDescription
AllowPartialApprovalsformbool?NoIf set to false, partial approvals are not allowed
CheckForDuplicateTransactionsformbool?NoIf set to true, enables duplicate checking logic for the transaction at the host.
MarketCodeformMarketCodeNoThe market code of the transaction.

Allowable Values

  • Default
  • AutoRental
  • DirectMarketing
  • ECommerce
  • FoodRestaurant
  • HotelLodging
  • Petroleum
  • Retail
  • Qsr
Healthcare Parameters:
NameParameterData TypeRequiredDescription
Totalformdecimal?NoThe total amount of healthcare-qualified goods. If any healthcare values are included, this value is required to be present.
Clinicformdecimal?NoThe total amount of healthcare-qualified goods that fall into the category of 'clinic'.
Dentalformdecimal?NoThe total amount of healthcare-qualified goods that fall into the category of 'dental'.
Prescriptionformdecimal?NoThe total amount of healthcare-qualified goods that fall into the category of 'prescription'.
Visionformdecimal?NoThe total amount of healthcare-qualified goods that fall into the category of 'vision'.
AutoRental Parameters:
NameParameterData TypeRequiredDescription
CustomerNameformstringNoCustomer Name.
AgreementNumberformstringNoAgreement number.
VehicleClassCodeformAutoRentalVehicleClassCode?NoClassification of rental vehicle

Allowable Values

  • Unused
  • Mini
  • Subcompact
  • Economy
  • Compact
  • Midsize
  • Intermediate
  • Standard
  • Fullsize
  • Luxury
  • Premium
  • Minivan
  • Van12Passenger
  • MovingVan
  • Van15Passenger
  • CargoVan
  • Truck12Foot
  • Truck20Foot
  • Truck24Foot
  • Truck26Foot
  • Moped
  • Stretch
  • Regular
  • Unique
  • Exotic
  • TruckSmallMedium
  • TruckLarge
  • SUVSmall
  • SUVMedium
  • SUVLarge
  • SUVExotic
  • FourWheelDrive
  • Special
  • Miscellaneous
NoShowIndicatorformAutoRentalNoShowIndicator?NoNo show indicator. Indicates whether rental vehicle was reserved, but not actually rented.

Allowable Values

  • NotApplicable
  • NoShow
AdjustmentDataformAutoRentalAdjustmentDataNoData related to any auto rental adjustments.
PickupDataformAutoRentalPickupDataNoData related to autorental pickup.
ReturnDataformAutoRentalReturnDataNoData related to autorental return.
DailyRentalRateformdecimalNoRate charged per day Visa/MC – Daily rate required for Corp T&E rate III.
WeeklyRentalRateformdecimalNoRate charged per week Visa/MC – Weekly rate required for Corp T&E rate III.
InsuranceChargesformdecimalNoIf insurance is charged, the insurance amount should be provided.
AutoRentalBasic Parameters:
NameParameterData TypeRequiredDescription
DurationformintNoThe number of rental days. Value should be between 0 and 99. Set to 01 for no show rentals.
AutoRentalAdjustmentData Parameters:
NameParameterData TypeRequiredDescription
AmountformdecimalNoAdjustment amount.
CodeformAutoRentalAuditAdjustmentCode?NoIndicates if adjustment for mileage, fuel, vehicle damage, etc. was made to a rental agreement.

Allowable Values

  • NoAdjustments
  • MultipleAdjustments
  • OneAdjustmentCardmemberNotified
  • OneAdjustmentCardmemberNotNotified
ExtraChargesDetailformAutoRentalExtraChargesDetail[]NoPass in up to 6 values that describe the extra charges. For an empty or invalid value, this parameter defaults to NoExtraCharge.

Allowable Values

  • NoExtraCharge
  • Gasoline
  • ExtraMileage
  • LateReturn
  • OneWayServiceFee
  • ParkingOrMovingViolation
AutoRentalPickupData Parameters:
NameParameterData TypeRequiredDescription
CityformstringNoAuto rental pickup city.
CountryCodeformstringNoCountry code where vehicle was picked up. For US, use 840.
DateformstringNoreturn date in yyyy-MM-ddTHH:mm:ss format.
LocationformstringNoName of business where vehicle was picked up.
StateformstringNoAbbreviation of state, province, or other country subdivision where vehicle was picked up.
AutoRentalReturnData Parameters:
NameParameterData TypeRequiredDescription
CityformstringNoAuto rental return city.
CountryCodeformstringNoCountry code where vehicle was returned. For US, use 840.
DateformstringNoreturn date in yyyy-MM-ddTHH:mm:ss format.
LocationIdformstringNoAuto Rental location ID where vehicle was returned.
StateformstringNoAuto rental return state.
DistanceformintNoNumeric distance traveled during rental period.
DistanceUnitformAutoRentalDistanceUnit?NoUnit of measurement applicable to distance traveled.

Allowable Values

  • 0 = Unused
  • 1 = Miles
  • 2 = Kilometers
TokenSaleResponse Parameters:
NameParameterData TypeRequiredDescription
TokenIdformstringNoThe token ID.
AvsResponseCodeformstringNoThe AVS response code.
ApprovedAmountformdecimalNoThe amount approved by the processor. This is the actual amount that will be charged or credited.
CardLogoformstringNoThe card logo. Possible values are: Visa, Mastercard, Discover, Amex, Diners Club, JCB, Carte Blanche, Other.
AccountNumberformstringNoThe card account number.
ConvenienceFeeAmountformdecimalNoThe convenience fee added to the transaction
CreditSurchargeAmountformdecimalNoThe credit surcharge added to the transaction
SubTotalAmountformdecimalNoThe original amount sent for the transaction.
TipAmountformdecimalNoThe tip amount added to the transaction.
TerminalIdformstringNoThe ID of the terminal used during the transaction
TotalAmountformdecimalNoThe total amount of the transaction.
ReferenceNumberformstringNoThe reference number.
BaseResponse Parameters:
NameParameterData TypeRequiredDescription
ApprovalNumberformstringNoApproval number from the processor. Depending on card type and processor an approval number might not be returned.
IsApprovedformboolNoSet to true if the host approved the transaction.
ProcessorformProcessorNoResponse information from the processor.
StatusCodeformTransactionFlowStatusNoThe 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
  • PreReadSuccessful
  • ContactlessMsdDisabled
  • ContactlessEmvDisabled
  • ContactlessMsdNotSupported
  • ProgrammaticallyCancelled
  • DccRequested
TransactionDateTimeformstringNoTransaction date/time in ISO8601 format
TransactionIdformstringNoThe transaction ID from the processor
MerchantIdformstringNoThe Merchant used to process the transaction.
IsOfflineformboolNoA boolean value indicating whether triPOS is disconnected from the host.
ApiResponse Parameters:
NameParameterData TypeRequiredDescription
ErrorsformList<ApiError>NoA list of errors that occurred.
HasErrorsformboolNoIndicates if there are errors.
LinksformIEnumerable<ApiLink>NoA list of resource links
LogsformList<string>NoA list of log entries detailing what happened during the request. Ideally only used during development or troubleshooting as this can be quite verbose.
TypeformstringNoThe type of object held in the result.
WarningsformList<ApiWarning>NoA list of warnings that occurred.
ApiError Parameters:
NameParameterData TypeRequiredDescription
UserMessageformstringNoAn error message targeted at the end user of the integrated business application.
DeveloperMessageformstringNoAn error message targeted at the developer of the integrated business application.
ErrorTypeformstringNoCode associated with the error if it exists.
ExceptionMessageformstringNoThe body of the exception message.
ExceptionTypeFullNameformstringNoThe full name of the exception.
ExceptionTypeShortNameformstringNoThe short name of the exception.
ApiLink Parameters:
NameParameterData TypeRequiredDescription
HrefformstringNoA target (a URI)
MethodformstringNoThe HTTP method to access the HREF target
RelationformstringNoThe relation aka. 'rel' (the name of the link)
ApiWarning Parameters:
NameParameterData TypeRequiredDescription
DeveloperMessageformstringNoA warning message targeted at the developer of the integrated business application.
UserMessageformstringNoA warning message targeted at the end user of the integrated business application.
Processor Parameters:
NameParameterData TypeRequiredDescription
ProcessorLogsformList<string>No[DEPRECATED] Use logs.
ProcessorRawResponseformstringNo[DEPRECATED] Use rawResponse.
ProcessorReferenceNumberformstringNo[DEPRECATED] Use the same reference number passed in the request.
ProcessorRequestFailedformboolNo[DEPRECATED] Use top level properties (e.g. hasErrors).
ProcessorRequestWasApprovedformboolNo[DEPRECATED] Use top level properties (e.g isApproved).
ProcessorResponseCodeformProcessorResponseCodeNo[DEPRECATED] Use expressResponseCode.

Allowable Values

  • Unknown
  • Approved
  • PartialApproval
  • Decline
  • ExpiredCard
  • Duplicate
  • PickUpCard
  • ReferralCallIssuer
  • InvalidData
  • ApprovedExceptCashback
  • NotAllowed
ProcessorResponseMessageformstringNo[DEPRECATED] Use expressResponseMessage.
ExpressResponseCodeformstringNoThe response code received from Express.
ExpressResponseMessageformstringNoThe response message received from Express.
HostResponseCodeformstringNoThe response code received from the host via Express. NOTE: This value is only populated if Express send the request to the host.
HostResponseMessageformstringNoThe response message received from the host via Express. NOTE: This value is only populated if Express send the request to the host.
LogsformList<string>NoA list of messages pertaining processing the transaction.
RawResponseformstringNoThe raw processor response. In the case of Express, this is the raw XML returned by the Express platform.
RawRequestformstringNo
ProcessorNameformProcessorNameNo

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

HTTP + JSON

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

POST /json/reply/TokenSaleRequest HTTP/1.1 
Host: triposqa.vantiv.com 
Content-Type: application/json
Content-Length: length

{"tokenId":"String","tokenProvider":"OmniToken","vaultId":"String","cardLogo":"Visa","expirationMonth":"String","expirationYear":"String","address":{"billingAddress1":"String","billingAddress2":"String","billingCity":"String","billingEmail":"String","billingName":"String","billingPhone":"String","billingPostalCode":"String","billingState":"String","shippingAddress1":"String","shippingAddress2":"String","shippingCity":"String","shippingEmail":"String","shippingName":"String","shippingPhone":"String","shippingPostalCode":"String","shippingState":"String"},"configuration":{"allowPartialApprovals":false,"checkForDuplicateTransactions":false,"marketCode":"Default"},"convenienceFeeAmount":0,"creditSurchargeAmount":0,"tipAmount":0,"transactionAmount":0,"laneId":0,"clerkNumber":"String","referenceNumber":"String","shiftId":"String","ticketNumber":"String","healthcare":{"total":0,"clinic":0,"dental":0,"prescription":0,"vision":0},"autoRental":{"CustomerName":"String","AgreementNumber":"String","VehicleClassCode":"Unused","NoShowIndicator":"NotApplicable","AdjustmentData":{"Amount":0,"Code":"NoAdjustments","ExtraChargesDetail":["NoExtraCharge"]},"PickupData":{"City":"String","CountryCode":"String","Date":"String","Location":"String","State":"String"},"ReturnData":{"City":"String","CountryCode":"String","Date":"String","LocationId":"String","State":"String","Distance":0,"DistanceUnit":"Unused"},"DailyRentalRate":0,"WeeklyRentalRate":0,"InsuranceCharges":0,"Duration":0},"estimatedAmountIndicator":"String"}

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

{"tokenId":"String","avsResponseCode":"String","approvedAmount":0,"cardLogo":"String","accountNumber":"String","convenienceFeeAmount":0,"creditSurchargeAmount":0,"subTotalAmount":0,"tipAmount":0,"terminalId":"String","totalAmount":0,"referenceNumber":"String","approvalNumber":"String","isApproved":false,"_processor":{"processorLogs":["String"],"processorRawResponse":"String","processorReferenceNumber":"String","processorRequestFailed":false,"processorRequestWasApproved":false,"processorResponseCode":"Unknown","processorResponseMessage":"String","expressResponseCode":"String","expressResponseMessage":"String","hostResponseCode":"String","hostResponseMessage":"String","logs":["String"],"rawResponse":"String","rawRequest":"String","processorName":"Unknown"},"statusCode":"None","transactionDateTime":"String","transactionId":"String","merchantId":"String","isOffline":false,"_errors":[{"userMessage":"String","developerMessage":"String","errorType":"String","exceptionMessage":"String","exceptionTypeFullName":"String","exceptionTypeShortName":"String"}],"_hasErrors":true,"_links":[],"_logs":["String"],"_type":"String","_warnings":[{"developerMessage":"String","userMessage":"String"}]}