Open the Portico Developer Guide site
PosGateway Schema
CreditReturn Element
PosGateway Schema > PosRequest Element > Ver1.0 Element > Transaction Element : CreditReturn Element
Description

CreditReturn allows the merchant to return funds back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.

For added fraud protection, CreditReturn can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.

The following rules apply when returning by GatewayTxnId:

  • The original transaction must be a CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, or RecurringBillingAuth and must be in a batch. It cannot be an open authorization that still needs to be added to a batch.
  • The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
  • A return amount must be greater than zero.
  • The return must be run within 1 year.
  • CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial return has been run.
  • A return can be voided. If this results in the total return amount being adjusted back to zero, CreditVoid, CreditReversal, and CreditTxnEdit are allowed on the original transaction once again.
  • If CardData is also supplied, the supplied card number and the card number of the original transaction must match.

Note: If the original transaction is in the current open batch, a CreditVoid or CreditReversal may be used instead. However, only a return can be used once the batch is closed.

Namespace http://Hps.Exchange.PosGateway
Type
PosCreditReturnReqType Complex Type
Diagram
Block1 Element All CreditReturn Element
Overview
CreditReturn PosCreditReturnReqType Complex Type

CreditReturn allows the merchant to return funds back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.

For added fraud protection, CreditReturn can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.

The following rules apply when returning by GatewayTxnId:

  • The original transaction must be a CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, or RecurringBillingAuth and must be in a batch. It cannot be an open authorization that still needs to be added to a batch.
  • The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
  • A return amount must be greater than zero.
  • The return must be run within 1 year.
  • CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial return has been run.
  • A return can be voided. If this results in the total return amount being adjusted back to zero, CreditVoid, CreditReversal, and CreditTxnEdit are allowed on the original transaction once again.
  • If CardData is also supplied, the supplied card number and the card number of the original transaction must match.

Note: If the original transaction is in the current open batch, a CreditVoid or CreditReversal may be used instead. However, only a return can be used once the batch is closed.

All
Block1 CreditReturnReqBlock1Type Complex Type

Contains a series of required and optional elements

Note: One or both of CardData and GatewayTxnId can be supplied, but it is required that one of these elements be provided.

All
GatewayTxnId optional txnIdType Simple Type

Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the original sale this return is to be run against.

Note: If CardData is also sent, the provided data must match the original.

AuthCode optional authCodeType Simple Type

Authorization code returned by the Issuer on the original transaction.  Supported for GSAP-hosted merchants only; necessary for returns in Mexico.

CardData optional CardDataType Complex Type

Card data

Sequence
Choice
TrackData CardDataTypeTrackData Complex Type

Track data is the full magnetic stripe data.

Note: TrackData is unique in that it has an attribute "method" that is used to indicate how the associated data was obtained.

ManualEntry

This is typically manually entered card data, but can be used in any case where only the card number is used rather than the full track.

TokenData

This is used when the card number from a previous transaction has been tokenized. This supports both multi-use and single-use tokens.

EncryptionData optional EncryptionDataType Complex Type

If the supplied card data was encrypted, this must be supplied.

TokenRequest optional booleanType Simple Type

This is used to request the gateway to return a multi-use token for the supplied card data. If a token is provided in the card data and this flag is set, it will be echoed in the response.

TokenParameters optional TokenParametersType Complex Type

Parameters allowing the client to control aspects of how a requested multi-use token is generated.

Not Applicable for Reward Cash transactions.

Amt amtTypeGlobal Simple Type

The amount to return; this includes all other "Info" amounts provided as part of this request.

PinBlock optional pinBlockType Simple Type

PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.

Note: Only used for UnionPay transactions processing to the GSAP-NA and GSAP-AP authorization platforms. Not for use with EMV transactions. Refer to EMVData.

CardHolderData optional CardHolderDataType Complex Type

Card holder data

All
CardHolderFirstName optional firstNameType Simple Type

First name

CardHolderLastName optional lastNameType Simple Type

Last name

CardHolderAddr optional addrType Simple Type

Address

CardHolderCity optional cityType Simple Type

City

CardHolderState optional stateType Simple Type

State

CardHolderZip optional zipType Simple Type

Zip or postal code; see the associated Type pattern for restrictions.

Note: Canadian postal codes should be sent in the format "A0A0A0".

CardHolderPhone optional phoneType Simple Type

Phone number; see the associated Type pattern for restrictions.

CardHolderEmail optional emailType Simple Type

Email address

CardHolderLanguage optional languageIndicatorType Simple Type

CardHolder preferred language.

Note:This field is required for Canadian merchants.

DirectMktData optional DirectMktDataType Complex Type

Direct marketing data; eCommerce

All
DirectMktInvoiceNbr directMktInvoiceNbrType Simple Type

Invoice number

Note: The elements in the direct marketing data group are passed on through the settlement process.

DirectMktShipMonth monthType Simple Type

Ship month

DirectMktShipDay dayType Simple Type

Ship day

AllowDup optional booleanType Simple Type

This is important in cases where the client processes a large number of similar transactions in a very short period of time; sending "Y" will skip duplicate checking on this transaction

Ecommerce optional eCommerceType Simple Type

Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.

AdditionalTxnFields optional AdditionalTxnFieldsType Complex Type

A common group of optional fields that are supported in several different transaction types for Merchant use.

All
Description optional descriptionType Simple Type

Free-form description field. This must not contain sensitive information.

InvoiceNbr optional Restriction of xs:string

Used to log the invoice number on transactions that are not eCommerce.

CustomerID optional customerIDType Simple Type

Used to log Merchant specific customer identification.

Note: For GETI check transactions, this is sent in the CUSTOM3 field.

SurchargeAmtInfo optional amtTypeGlobal Simple Type

Surcharge amount information; this defines the portion of the total amount provided as part of this request that was specifically for a surcharge. This is informational only and will not alter the amount processed as part of the transaction.

Note: This field is limited to 8 digits with implied decimal.

EMVData optional EMVDataType Complex Type

When processing with an EMV capable client, this element may need to be provided. It consists of certain online authentication data or the reason for not utilizing the EMV capabilities. EMV tag data should be sent in the separate TagData field.

All
EMVTagData optional emvTagDataType Simple Type

EMV tag data in TLV format.

Note: This field has been obsoleted.See the TagData field for the alternative.

EMVChipCondition optional emvChipConditionType Simple Type

This must be provided when the POS was not able to successfully communicate to the chip card and was required to fall back to a magnetic stripe read on an EMV capable terminal.

The values can indicate multiple factors:

  • The EMV chip read failed
  • Did the previous attempt fail

See enumerations for specific values supported

PINBlock optional pinBlockType Simple Type

Chip card PIN block for online authentication

TagData optional TagDataType Complex Type

EMV or Non-EMV tag data in TLV format

All
TagValues optional Extension of xs:string

This field holds the tag data values.

x_global_transaction_id optional x_global_transaction_idType Simple Type

Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.

Note: This is for internal use only.

CardOnFileData optional CardOnFileDataType Complex Type

Card On File Data

All
CardBrandTxnId optional restrictedStringType Simple Type

Network Transaction Identifier

CardOnFile optional CardOnFileType Simple Type

Card On File Indicator

Valid values include:

  • 'C' - Cardholder initiated transaction
  • 'M' - Merchant initiated transaction

CategoryInd optional CategoryIndType Simple Type

Mastercard CIT/MIT indicator subcategory

Valid values include:

  • 01 - Unscheduled Credential-on-file
  • 02 - Standing Order (variable amount and fixed frequency)
  • 03 - Subscription (fixed amount and frequency)
  • 06 - Related/Delayed Charge
  • 07 - No Show Charge
  • 08 - Resubmission

Note: Future use for GSAP-AP merchants

CurrencyConversion optional CurrConversionDataType Complex Type

Data block for Currency Conversion.

Integration must be through GP-API

All
CurrConvOptOutFlag booleanType Simple Type

This setting indicates if the Customer has decided Opt Out of currency conversion and have the amount remain in the Merchants currency. If the customer does not opt out, the amount will be converted to currency associated with the card.

RateLookupTxnId optional guidType Simple Type

The Retrieval Reference Number (RRN) of the RateLookup or Incremental Authorization that provided the rate used for the calculations in this transaction, if it is different from the original Authorization.

CardHolderCurrCode optional currCodeType Simple Type

Indicates the currency associated with the cardholder card.

CardHolderAmt optional amtTypeGlobal Simple Type

The charge amount in the cardholder currency.

ExchangeRateApplied optional exchangeRateType Simple Type

The exchange rate used for currency conversion.

MarkupFee optional Restriction of xs:decimal

The mark up percentage applied to the transaction, resulting in the commission fee.

SubMerchantData optional SubMerchantDataType Complex Type

Allows for sending Sub-Merchant data associated with the transaction. For Future Use.

Note: For internal use only.

All
SubMerchantId Restriction of xs:long

The ID assigned by the payment facilitator or aggregator to the sub-merchant.

Note: For internal use only.

Addr1 Restriction of xs:string

The street address of the sub-merchant.

Note: For internal use only.

City Restriction of xs:string

The city of the sub-merchant.

Note: For internal use only.

StateProvinceRegion optional Restriction of xs:string

The state or province of the sub-merchant.

Note: For internal use only.

ZipPostalCode Restriction of xs:string

The ZIP/Postal Code of the sub-merchant.

Note: For internal use only.

CountryCode Restriction of xs:int

The 3-digit ISO Numeric Country Code of the sub-merchant (eg, 840)

Note: For internal use only.

CustomerSvcPhone Restriction of xs:string

Sub-merchant phone number.

Note: For internal use only.

CustomerSvcEmail optional Restriction of xs:string

Sub-merchant email address.

Note: For internal use only.

TerminalId Restriction of xs:string

The sub-merchant Terminal ID assigned by the payment facilitator.

Note: For internal use only.

MCC Restriction of xs:string

Sub-merchant MCC.

Note: For internal use only.

TxnDescriptor optional TxnDescriptorType Simple Type

Transaction description that is concatenated to a configurable merchant DBA name. The resulting string is sent to the card issuer as the Merchant Name.

Note: Updates to the device are required to utilize this feature. See your Heartland representative for more details.

Source
<xs:element name="CreditReturn" type="PosCreditReturnReqType" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation>
    <xs:documentation>
      <p xmlns="http://Hps.Exchange.PosGateway">CreditReturn allows the merchant to return funds back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.</p>
      <p xmlns="http://Hps.Exchange.PosGateway">For added fraud protection, CreditReturn can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.</p>
      <p xmlns="http://Hps.Exchange.PosGateway">
                            The following rules apply when returning by GatewayTxnId:
                            <ul><li>The original transaction must be a CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, or RecurringBillingAuth and must be in a batch. It cannot be an open authorization that still needs to be added to a batch.</li><li>The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.</li><li>A return amount must be greater than zero.</li><li>The return must be run within 1 year.</li><li>CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial return has been run.</li><li>A return can be voided. If this results in the total return amount being adjusted back to zero, CreditVoid, CreditReversal, and CreditTxnEdit are allowed on the original transaction once again.</li><li>If CardData is also supplied, the supplied card number and the card number of the original transaction must match.</li></ul></p>
      <p xmlns="http://Hps.Exchange.PosGateway" />
      <p xmlns="http://Hps.Exchange.PosGateway">
        <strong>Note:</strong> If the original transaction is in the current open batch, a CreditVoid or CreditReversal may be used instead. However, only a return can be used once the batch is closed.
                          </p>
    </xs:documentation>
  </xs:annotation>
</xs:element>
See Also
Transaction Element | Ver1.0 Element | PosRequest Element | PosGateway Schema

 

 

© 2024 Heartland Payment Systems, Inc.