triPOS REST API

ReturnRequest

The following routes are available for this service:
POST	/api/v1/return/{transactionId}/{paymentType}	Creates a new card return based on the passed in parameters	Creates a new card return based on the passed in parameters. More»
POST	/api/v1/sale/{transactionId}/return/{paymentType}	[Deprecated] Use /v1/return/{transactionId}/{paymentType} instead

**ReturnRequest** Parameters:
Name	Parameter	Data Type	Required	Description
Configuration	body	ReturnRequestConfiguration	No	Any value included in this section will override the corresponding value set in the triPOS.config
PaymentType	path	string	Yes	The original payment type. Allowable Values credit gift
TransactionAmount	body	decimal	No	The total transaction amount. This is the amount of funds to move on the card
SalesTaxAmount	body	decimal	No	The amount of sales tax for the transaction. This is for Level II, submit amount for tax or 0.00 for tax-exempt.
CommercialCardCustomerCode	body	string	No	The commercial card customer code for the transaction. This is for Level II.
TransactionId	path	string	Yes	The ID of a previous transaction.
Address	body	Address	No	The cardholder address information for the transaction.
StoreCard	body	StoreCard	No	Information necessary to process a StoreCard transaction.
Lodging	body	LodgingAuthorization	No	The lodging parameters to be passed in for a lodging transaction. more»
AutoRental	body	AutoRentalBasic	No	The auto rental parameters to be passed in for an auto rental transaction. more»
GiftProgramType	body	GiftProgramTypes	No	This field is for Valutec gift/loyalty card type. The value 0 is for gift and 1 for loyalty Allowable Values 0 1
GiftCardProgram	body	string	No	This field is for Valutec gift/loyalty card program. '01' = Original Gift Card Program '02' = Promotional Gift Card Program '03' = Original Combo Card Program '04' = Auto Rewards LPR Card Program '05' = Original Loyalty Card Program Allowable Values 01 02 03 04 05
Fleet	body	Fleet	No	The fleet section that contains all applicable fleet. more»

**LaneRequest** Parameters:
Name	Parameter	Data Type	Required	Description
CardHolderPresentCode	form	CardHolderPresentCode?	No	Defines whether the cardholder 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
ClerkNumber	form	string	No	An optional clerk number for reference.
LaneId	form	int	No	Specifies which lane to use.
ReferenceNumber	form	string	No	A user defined reference number.
ShiftId	form	string	No	An optional shift id for reference.
TicketNumber	form	string	No	An optional ticket number.

**ReturnRequestConfiguration** Parameters:
Name	Parameter	Data Type	Required	Description
PromptForSignature	form	BasicSignaturePromptOption	No	Specifies how the signature prompt should be handled for the request. If a value is not provided, Always will be used. See Signature Prompt. Allowable Values Always Never None

**RequestConfiguration** Parameters:
Name	Parameter	Data Type	Required	Description
AllowPartialApprovals	form	bool?	No	If set to false, partial approvals are not allowed
CheckForDuplicateTransactions	form	bool?	No	If set to true, enables duplicate checking logic for the transaction at the host.
MarketCode	form	MarketCode	No	The market code of the transaction. Allowable Values Default AutoRental DirectMarketing ECommerce FoodRestaurant HotelLodging Petroleum Retail Qsr

**Address** Parameters:
Name	Parameter	Data Type	Required	Description
BillingAddress1	form	string	No	The street address used for billing purposes.
BillingAddress2	form	string	No	The street address used for billing purposes.
BillingCity	form	string	No	The name of the city used for billing purposes.
BillingEmail	form	string	No	The e-mail address used for billing purposes.
BillingName	form	string	No	The name used for billing purposes.
BillingPhone	form	string	No	The phone number used for billing purposes. The recommended format is (800)555-1212.
BillingPostalCode	form	string	No	The postal code used for billing purposes.
BillingState	form	string	No	The name of the state used for billing purposes. This value may be any 2 character state code or the full state name.
ShippingAddress1	form	string	No	The street address used for shipping purposes.
ShippingAddress2	form	string	No	The street address used for shipping purposes.
ShippingCity	form	string	No	The name of the city used for shipping purposes.
ShippingEmail	form	string	No	The e-mail address used for shipping purposes.
ShippingName	form	string	No	The name used for shipping purposes.
ShippingPhone	form	string	No	The phone number used for shipping purposes. The recommended format is (800)555-1212
ShippingPostalCode	form	string	No	The postal code used for shipping purposes.
ShippingState	form	string	No	The name of the state used for shipping purposes. This value may be any 2 character state code or the full state name.

**StoreCard** Parameters:
Name	Parameter	Data Type	Required	Description
Id	form	string	No	The ID of a StoreCard.
Password	form	string	No	The password of StoreCard.

**LodgingAuthorization** Parameters:
Name	Parameter	Data Type	Required	Description
PrestigiousPropertyCode	form	LodgingPrestigiousPropertyCode	No	The lodging prestigious property code. For an empty or invalid value, this parameter defaults to NonParticipant. Allowable Values NonParticipant FiveHundredDollarLimit OneThousandDollarLimit OneThousandFiveHundredDollarLimit

**Lodging** Parameters:
Name	Parameter	Data Type	Required	Description
Duration	form	int	No	The number of hotel stay days. Set to 1 for no show.

**AutoRentalBasic** Parameters:
Name	Parameter	Data Type	Required	Description
Duration	form	int	No	The number of rental days. Value should be between 0 and 99. Set to 01 for no show rentals.

**Fleet** Parameters:
Name	Parameter	Data Type	Required	Description
SummaryCommodityCode	form	string	No	International description code of overall goods or services.
DiscountAmount	form	string	No	Discount amount applied to the line item total. This field should be 0.00 if the unit cost reflects a discount price or if no line item discount applies.
DestinationZipCode	form	string	No	Postal/Zip Code of the address to where the purchased goods are being shipped. Recommend using merchant zip code for card-present.
ShipFromZipCode	form	string	No	Postal/Zip Code of the address to where the purchased goods are being shipped. Recommend using merchant zip code for card-present.
DestinationCountryCode	form	CountryCode	No	Country code where goods are being shipped. Allowable Values Can Gbr Usa
OrderDate	form	string	No	Purchase order date. YYYYMMDD
LineItemCount	form	string	No	Number of line items included in transaction. Fleet supports 1 to 7 line items.
LineItemDetail	form	FleetLineItemDetail	No	LineItemDetail includes the required Level III LineItem fields to be submitted.

**FleetLineItemDetail** Parameters:
Name	Parameter	Data Type	Required	Description
FleetLineItems	form	List<FleetLineItem>	No	lineItem that required Level III LineItem fields to be submitted.

**FleetLineItem** Parameters:
Name	Parameter	Data Type	Required	Description
ItemCommodityCode	form	string	No	International description code of the individual good or service being supplied. Recommend using numeric NACS code.
ItemDescription	form	string	No	Item Description.
ProductCode	form	string	No	Numeric NACS code.
Quantity	form	decimal?	No	Quantity of the item. NNNNN.DDD
UnitOfMeasure	form	string	No	Code for units of measurement.
UnitCost	form	decimal?	No	Unit cost of the item. DDDDD.CC
LineItemVatAmount	form	string	No	Amount of any sales or value added taxes associated with the item. Recommend 0.00. DDDDDDDDD.CC
LineItemVatRate	form	string	No	Tax rate used to calculate LineItemVATAmount. Submitted as a percentage. Two-digit implied string. Recommend 0. For example, if 10.42%, submit 1042
LineItemDiscountAmount	form	decimal?	No	Discount amount applied to the line item. This field should be 0.00 if the unit cost reflects a discount price or if no line item discount applies. DDDDDDDDD.CC
LineItemTotalAmount	form	decimal?	No	Total full amount associated with the line item (UnitCost * Quantity) - LineItemDiscountAmount for that item. DDDDDDDDD.CC
AlternateTaxIdentifier	form	string	No	Tax identification number of the merchant reporting the alternate tax amount. Not applicable for US merchants. (tag must be present, but can be empty)
VatType	form	string	No	Type of value added taxes being used. Not applicable for US merchants. (tag must be present, but can be empty)
DiscountCode	form	FleetDiscountCode?	No	Indicates whether discount was applied to the purchase price of the item. Recommend 0. Allowable Values NotSupported AmountIsDiscounted AmountIsNotDiscounted
NetGrossCode	form	FleetNetGrossCode?	No	Indicates whether extended item amount included the tax. Recommend 0. Allowable Values NotSupported ItemAmountIncludesTaxAmount ItemAmountDoesNotIncludeTaxAmount
ExtendedItemAmount	form	string	No	Amount of the item (unit price multiplied by quantity only). DDDDDDDDD.CC
DebitCreditCode	form	FleetDebitCreditCode?	No	Indicates whether extendedItemAmount is a Credit (taking away from the total amount of the sale) or Debit (adding to the total amount of the sale). Recommend 0 Allowable Values NotSupported ExtendedItemAmountIsCredit ExtendedItemAmountIsDebit
ItemDiscountRate	form	string	No	Discount rate for the line item. Submitted as a percentage. Two-digit implied string. Recommend 0. For example, if 10.42%, submit 1042

**ReturnResponse** Parameters:
Name	Parameter	Data Type	Required	Description
GiftPointsBalance	form	string	No	This field provides gift points balance for Valutec gift/loyalty cards.
GiftRewardLevel	form	string	No	This field provides gift reward level for Valutec gift/loyalty cards.

**BaseCardResponse** Parameters:
Name	Parameter	Data Type	Required	Description
AccountNumber	form	string	No	The card account number.
BinValue	form	string	No	The BIN entry that matched the account number.
CardHolderName	form	string	No	The cardholder name.
CardLogo	form	string	No	The card logo. Possible values are: Visa, Mastercard, Discover, Amex, Diners Club, JCB, Carte Blanche, Other.
CurrencyCode	form	CurrencyCode	No	The currency code used in the transaction. Allowable Values None Cad Gbp Usd
CountryCode	form	CountryCode?	No	The country code used in the transaction. Allowable Values Can Gbr Usa
Language	form	LanguageCode?	No	The language used in the transaction. Allowable Values English French Spanish
DebitAccountType	form	DebitAccountType?	No	The account type selected and used in the transaction. Allowable Values None Checking Savings
EntryMode	form	string	No	Description of how card was entered. Allowable Values Unknown Swiped Keyed ContactIcc ContactlessIcc ContactlessMsd
ExpirationYear	form	string	No	The card's expiration year
ExpirationMonth	form	string	No	The card's expiration month
NetworkLabel	form	string	No	Label that shows the network where the transaction was routed for authorization
PaymentType	form	PaymentType	No	Description of payment type utilized. Allowable Values None Credit Debit Gift Ebt
PinVerified	form	bool	No	True if the PIN was verified, false if not verified or undetermined.
Signature	form	Signature	No	The signature data.
TerminalId	form	string	No	The ID of the terminal used during the transaction
TotalAmount	form	decimal	No	The total amount of the transaction.
EBTType	form	EbtTypeSelection?	No	The type of the EBT card
BalanceAmount	form	decimal?	No	The balance of the gift card.
BalanceCurrencyCode	form	CurrencyCode?	No	The balance currency code.
PreReadId	form	Guid	No	Unique ID. If checkForPreReadId field is true, then this ID will be required for the Quick Chip portion of the transaction to be successful.
ForeignCurrencyCode	form	string	No	Currency code of the foreign currency.
ForeignTransactionAmount	form	string	No	Transaction amount shown in the foreign currency.
ConversionRate	form	string	No	Conversion rate for the ForeignCurrencyCode.
Odometer	form	string	No	Fleet Odometer Input On The Device
FleetUserID	form	string	No	Fleet UserID Input On The Device
FleetJobNumber	form	string	No	Fleet Job Number Input On The Device
PurchaseDeviceSequenceNumber	form	string	No	Fleet Purchase Device Sequence Number from the card
VehicleID	form	string	No	Fleet Vehicle ID Input On The Device
BinAttributes	form	Dictionary<string, bool>	No	Available binAttributes of card. more»
DriverID	form	string	No	Fleet DriverID Input On The Device
IsFleetOdometerPrint	form	bool	No	is Fleet Odometer value Print On the Receipt or not

**BaseResponse** Parameters:
Name	Parameter	Data Type	Required	Description
ApprovalNumber	form	string	No	Approval number from the processor. Depending on card type and processor an approval number might not be returned.
IsApproved	form	bool	No	Set to true if the host approved the transaction.
Processor	form	Processor	No	Response information from the processor.
StatusCode	form	TransactionFlowStatus	No	The 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
TransactionDateTime	form	string	No	Transaction date/time in ISO8601 format
TransactionId	form	string	No	The transaction ID from the processor
MerchantId	form	string	No	The Merchant used to process the transaction.
IsOffline	form	bool	No	A boolean value indicating whether triPOS is disconnected from the host.

**ApiResponse** Parameters:
Name	Parameter	Data Type	Required	Description
Errors	form	List<ApiError>	No	A list of errors that occurred.
HasErrors	form	bool	No	Indicates if there are errors.
Links	form	IEnumerable<ApiLink>	No	A list of resource links
Logs	form	List<string>	No	A list of log entries detailing what happened during the request. Ideally only used during development or troubleshooting as this can be quite verbose.
Type	form	string	No	The type of object held in the result.
Warnings	form	List<ApiWarning>	No	A list of warnings that occurred.

**ApiError** Parameters:
Name	Parameter	Data Type	Required	Description
UserMessage	form	string	No	An error message targeted at the end user of the integrated business application.
DeveloperMessage	form	string	No	An error message targeted at the developer of the integrated business application.
ErrorType	form	string	No	Code associated with the error if it exists.
ExceptionMessage	form	string	No	The body of the exception message.
ExceptionTypeFullName	form	string	No	The full name of the exception.
ExceptionTypeShortName	form	string	No	The short name of the exception.

**ApiLink** Parameters:
Name	Parameter	Data Type	Required	Description
Href	form	string	No	A target (a URI)
Method	form	string	No	The HTTP method to access the HREF target
Relation	form	string	No	The relation aka. 'rel' (the name of the link)

**ApiWarning** Parameters:
Name	Parameter	Data Type	Required	Description
DeveloperMessage	form	string	No	A warning message targeted at the developer of the integrated business application.
UserMessage	form	string	No	A warning message targeted at the end user of the integrated business application.

**Processor** Parameters:
Name	Parameter	Data Type	Required	Description
ProcessorLogs	form	List<string>	No	[DEPRECATED] Use logs.
ProcessorRawResponse	form	string	No	[DEPRECATED] Use rawResponse.
ProcessorReferenceNumber	form	string	No	[DEPRECATED] Use the same reference number passed in the request.
ProcessorRequestFailed	form	bool	No	[DEPRECATED] Use top level properties (e.g. hasErrors).
ProcessorRequestWasApproved	form	bool	No	[DEPRECATED] Use top level properties (e.g isApproved).
ProcessorResponseCode	form	ProcessorResponseCode	No	[DEPRECATED] Use expressResponseCode. Allowable Values Unknown Approved PartialApproval Decline ExpiredCard Duplicate PickUpCard ReferralCallIssuer InvalidData ApprovedExceptCashback NotAllowed
ProcessorResponseMessage	form	string	No	[DEPRECATED] Use expressResponseMessage.
ExpressResponseCode	form	string	No	The response code received from Express.
ExpressResponseMessage	form	string	No	The response message received from Express.
HostResponseCode	form	string	No	The response code received from the host via Express. NOTE: This value is only populated if Express send the request to the host.
HostResponseMessage	form	string	No	The response message received from the host via Express. NOTE: This value is only populated if Express send the request to the host.
Logs	form	List<string>	No	A list of messages pertaining processing the transaction.
RawResponse	form	string	No	The raw processor response. In the case of Express, this is the raw XML returned by the Express platform.
RawRequest	form	string	No
ProcessorName	form	ProcessorName	No

**Signature** Parameters:
Name	Parameter	Data Type	Required	Description
SignatureData	form	byte[]	No	The byte array of the signature in the format specified by Format.
SignatureFormat	form	string	No	The format of the signature. Allowable Values PointsLittleEndian PointsBigEndian Ascii3Byte
SignatureStatusCode	form	SignatureStatusCode	No	Indicates why a signature is or is not present. Allowable Values Unknown SignatureRequired SignaturePresent SignatureRequiredCancelledByCardholder SignatureRequiredNotSupportedByPinPad SignatureRequiredPinPadError SignatureNotRequiredByThresholdAmount SignatureNotRequiredByPaymentType SignatureNotRequiredByTransactionType SignatureRequiredButPromptSuppressedByMerchant SignatureNotRequiredByUnattendedPinPad

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/ReturnRequest HTTP/1.1 
Host: triposqa.vantiv.com 
Content-Type: application/json
Content-Length: length

{"configuration":{"promptForSignature":"Always","allowPartialApprovals":false,"checkForDuplicateTransactions":false,"marketCode":"Default"},"paymentType":"None","transactionAmount":0,"salesTaxAmount":0,"commercialCardCustomerCode":"String","transactionId":"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"},"storeCard":{"Id":"String","Password":"String"},"lodging":{"prestigiousPropertyCode":"NonParticipant","duration":0},"autoRental":{"Duration":0},"giftProgramType":"gift","giftCardProgram":"String","fleet":{"summaryCommodityCode":"String","discountAmount":"String","destinationZipCode":"String","shipfromZipCode":"String","destinationCountryCode":"Can","orderDate":"String","lineItemCount":"String","lineItemDetail":{"lineItem":[{"itemCommodityCode":"String","itemDescription":"String","productCode":"String","quantity":0,"unitOfMeasure":"String","unitCost":0,"lineItemVatAmount":"String","lineItemVatRate":"String","lineItemDiscountAmount":0,"lineItemTotalAmount":0,"alternateTaxIdentifier":"String","vatType":"String","discountCode":"NotSupported","netGrossCode":"NotSupported","extendedItemAmount":"String","debitCreditCode":"NotSupported","itemDiscountRate":"String"}]}},"cardHolderPresentCode":"Default","clerkNumber":"String","laneId":0,"referenceNumber":"String","shiftId":"String","ticketNumber":"String"}

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

{"giftPointsBalance":"String","giftRewardLevel":"String","accountNumber":"String","binValue":"String","cardHolderName":"String","cardLogo":"String","currencyCode":"None","countryCode":"0","language":"English","accountType":"None","expirationYear":"String","expirationMonth":"String","networkLabel":"String","paymentType":"None","pinVerified":false,"signature":{"data":"AA==","format":"String","statusCode":"Unknown"},"terminalId":"String","totalAmount":0,"ebtType":"None","balanceAmount":0,"balanceCurrencyCode":"None","foreignCurrencyCode":"String","foreignTransactionAmount":"String","conversionRate":"String","odometer":"String","fleetUserID":"String","fleetJobNumber":"String","purchaseDeviceSequenceNumber":"String","vehicleID":"String","binAttributes":{"String":false},"driverID":"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"}]}

triPOS REST API

ReturnRequest

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

HTTP + JSON