FND681 - Process Vantiv Batch Response for FND680

Personify360 supports recurring gifts. Currently, recurring gifts must be paid by credit card. The FND680 batch process creates order lines and receipt records for recurring gift payments once credit card authorization is received. Organizations using Vantiv's authorization recycling for recurring donations need to run FND681 instead of FND680.

"Authorization Recycling" is the process by which Vantiv attempts to obtain authorizations for declined credit card transactions over a period of 15-28 days, based on the credit card type. For organizations to use “Authorization Recycling” with Personify360, credit-card transactions are submitted to Vantiv for bulk credit-card transaction processing.

The AUTH_RECYCLING_MERCHANT merchant parameter is used to identify how authorization recycling is managed. For more information, please see Vantiv Merchant Parameters.

Processing Logic for Export

When FND681 is run where RUN_MODE = "PROD" and PROCESSING_MODE = "EXPORT", for each recurring gift selected for processing, FND681 performs the following:

·            A record is created for transmission to Vantiv for each recurring gift payment that is due.

·            Updates selected recurring gift from which the next recurring gift will be renewed with a recurring gift status of "IN_PROCESS". This will later be updated based on whether collection is successful or not.

·            Generates an output file that will be transmitted to Vantiv for processing. As of 7.6.2, the process of sending the SFTP export file created by FND681 to the Vantiv site is automatic. For more information, please see Processing the Bulk Transaction Files.

If the fundraising recurring gift product has been defined with a custom billing description, it will be passed to Vantiv in the export file, rather than the order line description.

·            Generates reports

The processing logic when FND681 is run where RUN_MODE = "EDIT" mode uses the same selection logic so that the report can be generated, but no updates to the data are done.

When FND681 is run where RUN_MODE = "PROD" and PROCESSING_MODE = "EXPORT", it generates an output file with the following data elements:

·            <litleRequest> - The root node for the entire batch file. Only one is allowed per batch file. It contains the following attributes:

o           version - Defines the LitleXML schema version against which the XML is validated.

o           xmlns - Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema.

o           numBatchRequests - Defines the total number of <batchRequest> children included in the <litleRequest>.

·            <authentication> - Contains information about the authentication of the merchant. Child of the <litleRequest> node. Only one is allowed per batch file. It has two child nodes:

o           <user> - A unique identifier of the user/merchant used to authenticate that the message is from a valid source.

o           <password> - Used in combination with the <user> element to authenticate that the message is from a valid source.

·            <batchRequest> - Groups together all transactions that are to be processed as part of the same batch. Child of the <litleRequest> node. Each file must contain one or more <batchRequest> elements. It contains the following attributes:

o           id - A unique string to identify this <batchRequest> within the Litle system. Currently not being used.

o           numAuths - Defines the total count of Authorization transactions in the <batchRequest>.

o           authAmount - Defines the total dollar amount of Authorization transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500.

o           merchantSdk – This attribute is undocumented in the Litle Reference Guide

o           merchantId - A unique string to identify the merchant within the Litle system.

·            <authorization> - Each of these elements corresponds to a different receipt for which the merchant is requesting authorization. Child of the <batchRequest> element. Each <batchRequest> must contain one or more <authorization> elements. Each <authorization> has the following attributes:

o           id – A unique identifier equal “FND681_” + to the ORDER_NO field in the Order_Detail table. It will be mirrored back in the response file.

o           reportGroup - Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Set in Merchant Setup in APP014.

In addition, <authorization> contains the following child elements:

o           <orderId> - A unique identifier equal Order_No + Order_Line_No field in the Order_Detail table. It will be mirrored back in the response file.

o           <amount> - Defines the amount of the transaction. The decimal point is implied. For example, you enter $25.00 as 2500.

o           <orderSource> - Defines the order entry source for the type of transaction.

o           <token> - Contains either a Litle generated token or a Paypal generated token.

o           <recyclingRequest> - (Optional) If present, this indicates that the merchant would like Vantiv to reattempt authorizations for failed transactions. This is done automatically by the Litle Recycling Engine if it has been set up for the merchant. The maximum number of retries is 4 attempts in 16 days for VISA, and 8 attempts in 28 days for MasterCard and Discover. It has an optional <recycleBy> child element that indicates whether the merchant or the Litle Recycling Engine will control the recycling of the transaction.

·            <allowPartialAuth>False</allowPartialAuth> - Setting the <allowPartialAuth> element to true in the Authorization request enables the system to return authorizations for a portion of the order amount for cases where the card does not have an adequate credit limit or balance available for the full amount.

·            <billToAddress>

o           <name>

o           <addressLine1>

o           <city>

o           <state>

o           <zip>

o           <country>

o           <phone>

o           <email>

·            <token>

o           <litleToken>

o           <expDate> - The expDate element is a child of the card, token, paypage elements, which specifies the expiration date of the card and is required for card-not-present transactions.

·            <customBilling> - If the fundraising recurring gift product has been defined with a custom billing description, it will be passed to Vantiv in the export file, rather than the order line description.

o           <phone>Telephone Number</phone>

o           <descriptor>Billing Descriptor</descriptor>

Processing Logic for Import

After the FND681 output file has been submitted to Vantiv’s SFTP server, a response file will be posted within a few minutes that has authorizations and initial decline information. This file will be processed by the FND681 batch process and will create new recurring donation line if payment is approved. If payment results in a soft decline, then it’s not going to do anything except create a new entry in CCP_REQ_ANS table with the soft decline response. If the response is a hard decline, then it’s going to update Recurring Gift Status to “Rejected” on the “Renewed from” recurring gift order line. Also, the system will insert a hard decline response in the CCP_REQ_ANS table. There will be no insert or update on FAR_RECEIPT / FAR_TXN/ FAR_BATCH/FAR_BATCH_DETAIL table.

Currently, FND681 in Export mode picks the recurring orders where Recurring Gift Status code is “Active” OR “Rejected”. Therefore, if your organization does not want to process “Rejected” Recurring donation order lines in future processing, you need to update the Recurring Gift Status code to “Cancelled”.

For step-by-step instructions on processing the bulk transaction files, please see Processing the Bulk Transaction Files.

The response file provided by Vantiv contains the following data elements:

·            <litleResponse> - The root node for the entire response file. Only one is allowed per response file. It contains the following attributes:

o           version - Defines the LitleXML schema version against which the XML is validated.

o           xmlns - Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema.

o           response - Indicates whether your XML syntax passed validation. If this value is nonzero, then FAR681 will fail and the XML validation error message will be logged. Expected values are as follows:

§            0 - XML validation succeeded.

§            1 - XML validation failed. See the message attribute for more details.

§            2 - Indicates that the submitted content was either improperly formatted XML or non-XML content.

§            3 - Indicates that the submission contains empty or invalid credentials (user and password).

§            4 - Indicates that the merchant has reached the maximum number of concurrent connections.

§            5 - Indicates that Litle systems may have detected message content that violates certain restrictions.

o           message - XML validation error message. Expected values are as follows:

§            If the response attribute returns 0, the message attribute returns the text “Valid Format.”

§            If the response attribute returns 1, the message attribute returns an error message that helps you to identify and troubleshoot the syntax problem.

§            If the response attribute returns 2, the message attribute is "System Error - Call Litle & Co."

§            If the response attribute returns a value of 3, 4, or 5, the message attribute is "There is a problem with the Litle System. Contact support@litle.com."

o           litleSessionId - A unique value assigned by Litle to identify the session.

·            <batchResponse> - Groups together all transactions that were processed as part of the same batch. Child of the <litleResponse> node. It contains the following attributes:

o           id - Returns the same value submitted in the <batchRequest>. Currently not being used.

o           litleBatchId - A unique value assigned by Litle to identify the batch.

o           merchantId - Returns the same value submitted in the <batchRequest>.

·            <authorizationResponse> - Each of these elements corresponds to an authorization request that was submitted as part of the initial batch file. Child of the <batchResponse> element. Each <authorizationResponse> has the following attributes:

o           id - A unique identifier equal to the FND681_ORDER_NO-ORDER_LINE_NO field in the Order_Detail table. It is equal to the value submitted in the <authorization> transaction.

o           reportGroup - Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. It is equal to the value submitted in the <authorization> transaction.

In addition, <authorizationResponse> contains the following child elements:

o           <litleTxnId> - A unique value assigned by Litle to identify the transaction.

o           <orderId> - The Order_no-order_line_no of the renewed_from_order_line_no from the fnd681_processed table.

o           <response> - A three digit numeric code which specifies either that the transaction is approved (000 code) or declined.

o           <responseTime> - A date/time stamp of the response. The format of the element is YYYY-MM-DDTHH:MM:SS.

o           <message> - A brief definition of the response code returned for the transaction.

o           <authCode> - (Optional) Specifies the authorization code from the associated Authorization transaction.

o           <fraudResult> - (Optional) Contains elements defining any fraud checking results.

o           <tokenResponse> - The parent element for several children defining the registered token, as well as the card type and BIN.

o           <enhancedAuthResponse> - (Optional) Can provide information concerning whether the card used for the transaction is Prepaid and if so, the available balance. Depending upon the card used, other elements can indicate affluence, card product type, prepaid card type, reloadability and whether or not it is a virtual account number.

§            The specific enhancedAuthResponse data elements implemented for Personify360 include:

1.       <enhancedAuthResponse>

a.      <fundingSource>

b.      <type>PREPAID</type>

c.       </fundingSource>

d.      <affluence>AFFLUENT</affluence>

e.      <issuerCountry>MEX</issuerCountry>

f.         <cardProductType>CONSUMER</cardProductType>

g.      </enhancedAuthResponse>

o           <recycling> - (Optional) Contains a child element that specifies either the recommended date and time for the next recycling attempt for the declined Authorization/Sale transaction or a statement that no further advice is available for merchants using the Recycling Advice feature. For merchants using the Recycling Engine feature, there is a child element that specifies whether or not the engine is recycling the declined transaction.

When FND681 is run where PROCESSING_MODE = "IMPORT", FND681 identifies whether the credit card transaction is (1) successfully authorized, (2) initially declined but is going through sales recycling, or (3) declined and will not go through additional authorization recycling. This is done whether FND681 is being run in PROD or EDIT mode.

·            If a credit card transaction for a recurring gift is successful authorized, if the RUN_MODE = "PROD", FND681 will:

o           Either create a new receipt batch or open the receipt batch specified by the user in the FND681 Batch parameter.

o           Create Order_Detail and Order_Fnd_Detail record for each paid recurring gift with Order_Fnd_Detail.RECURRING_GIFT_STATUS_CODE set to "ACTIVE".

o           Update Order_Fnd_Detail.RECURRING_GIFT_STATUS_CODE on the “renewed from” (previous successfully collected recurring gift order line) from "IN_PROCESS" to "RENEWED".

o           For each recurring gift order or order line, create receipt records in:

§            Order_Detail_CC_Info

§            Far_Receipt

§            Far_Txn (TXN_TYPE_CODE = 1)

§            Appropriate records in Far_Txn_Detail based on GL account setup (will include TXN_FUNCTION_CODE values of REVENUE and CASH; there may be DUETO and DUEFROM transactions)

o           Create appropriate hard and soft credit records in Fnd_Credit.

o           Create record in CCP_Req_Ans with REQ_TYPE_CODE = ‘PRE-SALE’, APPROVED_FLAG = ‘Y’ and CC_AUTHORIZATION, CC_REFERENCE, SETTLEMENT_NO and other field values populated (unlike most records in CCP_Req_Ans that involve two steps, this will be a single record for the credit card transaction).

§            If response is a Hard or Soft decline, then APPROVED_FLAG is set to 'N' and SETTLEMENT_NO gets updated by the CCP610 process.

o           If the record has a token, update Cus_Credit_Card_Profile with the token and update the PROFILE_DATE.

·            If credit card transactions are declined and the recycling element is true, it means that the credit card transaction has been declined but the transaction will go through authorization recycling, and FND681 does not need to do any data updates for that transaction, but it should appear on the decline report, with the phrase “; pending authorization recycling” after the decline reason.

·            If credit card transactions are declined and the recycling element is false, it either means that the initial credit card decline was a hard decline or the credit card transaction has gone through the authorization recycling process and could not be successfully authorized, so the decline is a final decline. In that scenario, FND681 will:  

o           Update RECURRING_GIFT_STATUS_CODE on the "renewed from" (previous recurring gift order line) from "IN_PROCESS" to "REJECTED".

o           Create record in Ccp_Req_Ans to record the credit card decline (Note that the Ccp_Req_Ans.RECEIPT_NO value should be generated from App_Next_Number_Far_Receipt.NEXT_ID, but no Far_Receipt record will be created).

If the import fails, please see Troubleshooting Vantiv Import Failures.

Parameters

Sample Reports

FND681_RecurringGiftsProcessedReceipts

This report is generated when FND681 is run in IMPORT processing mode and in EDIT or PROD run mode. In some scenarios, the Vantiv response/recycling file will include information on recurring donation/payment schedule orders and responses on orders belonging to different org/org units. In this case, the FND681 process is going to import only recurring orders based on the selected org/org unit. This information also gets printed on report and log file.

FND681_RecurringGiftsFailedReceipts

This report is generated when FND681 is run in IMPORT processing mode and in EDIT or PROD run mode. This report displays information of recurring donation orders where the Vantiv response is either a soft decline or hard decline.  

FND681_RecurringGiftsExceptionReceipts

This report is generated when FND681 is run in IMPORT processing mode and in EDIT or PROD run mode. While processing response files, if any recurring donation order had a data error, then those recurring orders will display in this report. All the responses get added to the CCP_REQ_ANS table, but later on, the CCP610 process will void them.

If a record in the Vantiv import file cannot be successfully processed, this will NOT cause the FND681 import process to fail. Rather, the record will be written to an exceptions table and included in this FND681 exceptions report. If a response file received from Vantiv contains a record with a "Response" value that is not 0, the batch process cannot import the file. The failure of the process to be able to import the file will be included in the job log, and the final job status record will appear in the "Status" tab with a Status Code of "FAILED". The log message will say, “Import File contained a non-zero response code".

FND681_RecurringGiftsExportProcessed

This report is generated when FND681 is run in EXPORT processing mode and in EDIT or PROD run mode.

FND681_RecurringGiftsExportFailed

This report is generated when FND681 is run in EXPORT processing mode and in EDIT or PROD run mode if there are any recurring gifts that cannot be processed. This report displays the records in exception file if:

·            Credit card information is not found or Auto Pay Method is not CC for recurring donation orders

·            Credit card is expired on recurring donation orders when the Process_Expired_CC merchant parameter is set to "N"