Moso Docs

Contents 1 General Information 2 Tokenization (What is it?) 2.1 Token Structure 2.2 Account Types 3 FTP Folder Structure and File Name Convention 3.1 Folder Structure 3.2 Request File 3.3 Response File 3.4 Parsing Error File 3.5 Validation Error File 3.6 Return File 4 File Format 4.1 Request File Format (Sale and Credit) 4.2 Response File Format (Sale and Credit) 4.3 Parsing Error File Format 4.4 Validation Error File Format 4.5 Transaction Types 4.6 Additional Notes 4.6.1 Dynamic Descriptor 4.6.2 Capture, Void, and Refund Operation 4.6.3 Service Fees 4.6.4 Re-bill Process 4.6.5 Sequence Number 4.6.6 Transaction Groups 4.6.7 Canada ACH 4.6.8 Retry Fee 4.6.9 Batch Tokenization 4.6.10 Notices of Change (NOCs) 4.6.11 Effective Date 4.7 Examples (Header Records) 5 Integration 5.1 Test Cards & Bank Accounts 5.2 Certification Scenarios 5.2.1 Sale 5.2.2 Credit 6 Response Codes 6.1 Response Type 6.2 Change History 6.3 Codes 7 Exception Codes 8 Related Information

General Information

The MosoPay Batch FTPs Integration provides you with the proper procedures to integrate with MosoPay processing gateway. It includes information on:

• Basic gateway operations
• File name conventions
• File format
• Tokenization.

The batch transaction processing is implemented through FTPs protocol. Batches are submitted as pipe (|), delimited files (one transaction per row). The protocol supports 2 operations: sale and credit and can accept both credit card and ACH/eCheck transactions. Any FTPs enabled customer can communicate with MosoPay and file upload/downloads can be done manually or using timer based automated processes.

Tokenization (What is it?)

MosoPay provides a simple and convenient Tokenization mechanism for merchants that:

• Deal with recurring payments
• Want to avoid storing a customer’s or member's payment information (credit card and bank account numbers) within their own systems.

When a merchant uses any given credit card or bank account for the first time (as part of an authorization, sale, or credit operation), MosoPay will generate a unique identification number ("Token") associated with this payment information. If in the future, the merchant wants to issue another operation (e.g. another sale) on the same credit card or bank account, it is sufficient to pass to MosoPay just the value of the previously generated token and omit all of the account information fields.

Token Structure

A token generated by MosoPay is comprised of 3 logical parts:

1. Two letter account type
2. Tokenized account number
3. Last 4 digits of the actual account number

This structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.

Account Types

 
  VC - visa credit card
  VD - visa debit card
  MC - MasterCard credit card
  MD - MasterCard debit card
  AC - Amex credit card
  DC - Discover credit card
  DD - Discover debit card
  BC - Checking account
  BS - Savings account
 

FTP Folder Structure and File Name Convention

Folder Structure

Each merchant has a Merchant ID issued by the gateway owner. The merchant's base folder's name is equal to the ID and is located in the root of the FTP server. The base folder contains two (2) sub-folders:

• inbox - folder for uploads of the files to be processed.
• outbox - folder that contains processing results.

Example:

 
Merchant ID:		2000
Inbox:			ftps://[server-name]/2000/inbox
Invault:*		ftps://[server-name]/2000/invault
Outbox:			ftps://[server-name]/2000/outbox
 
* If batch tokenization is necessary, files with account numbers should be placed into invault folder. All files in invault folder will get tokenized and subsequently put in inbox folder for regular processing.
 

Request File

All files uploaded to the server must be archived using any standard zip client (e.g. WinZip) and can have any name. It is recommended that the submission date in YYYYMMDD or YYYYMMDDHHSS format is included as part of the name to keep file names unique at all times. The zip file must contain single pipe-delimited text file with the exact same name and .csv extension. The zip file must NOT have any password protection. The zip file must be placed in /inbox folder in order to be processed.

Response file is a zip archive with pipe delimited text file inside. It will have exactly the same name as the request file for which it is generated. Response files are placed in /outbox folder.

Additionally, two (2) types of error files might be generated if the system cannot process the request file that was uploaded:

1. If the uploaded file cannot be opened or if it contains damaged content, .error file will be generated.
2. If the uploaded file contains incorrectly formatted transactions or transactions with missing required fields, .validation file will be generated.

Both files are unarchived pipe delimited text files. Both files will have the same name as the original request file, followed by either .error or .validation, followed up by file extension .cvs (NOTE: if any of the two error files is generated, your request file is rejected, transactions are not processed and you will not get a response file). Both error files are placed in /outbox folder.

Response File

Returns, chargebacks and chargeback reversals, as well as results of re-bill process (declines or approvals) can be received in two ways based on merchant's selection:

1. As part of the response file - returns, chargebacks, reversals, and rebill results will be accumulated by the system and included in the standard response file when it is generated.
2. As a separate file - returns, chargebacks, reversals, and re-bill results will be placed in a seperate file, which will be generated on a daily basis.

If on any given day there are no transactions of these types, the file will not be generated. The file is a zip archive that follows regular response file format. The file is placed in /outbox folder. Returns can be delivered by merchant account or for the entire merchant.

• When delivered by merchant account, all of the returns for a single merchant account will be placed in a single file. The name of the file will be comprised of three parts separated by '.' - static part (word 'returns'), dynamic part (date of the file in YYYYMMDD format) and merchant account code.
• When delivered by merchant, all of the returns from all of the merchant accounts under the merchant will be placed in a single file. The name of the file will be comprised of two parts separated by '.' - static part (word 'returns') and dynamic part (date of the file in YYYYMMDD format).

Parsing Error File

When the request file (.zip or .csv) is damaged and cannot be read or processed, the error file is generated, which is going to contain the message, explaining why the file could not be processed.

Validation Error File

Validation Error File takes all the fields from Request File Format and adds an errorCode and errorMessage to each record, explaining the problem with this record. Any transaction, that cannot be parsed or properly persisted, will be placed in the validation error file. Please refer to the definitions of the corresponding file formats for more information.

Return File

Return file is generated daily. It contains ACH returns, chargebacks/reversals and results of the automated retry process (approvals/declines that occured during the day).

Example:

 
Submission Date and Time (optional):	        Dec 15th 2010 at 5:46 AM
 
Request Zip File Name:		    monthly_billing_201012150546.zip
Request CSV (pipe) File Name:	    monthly_billing_201012150546.csv
 
Response Zip File Name:		    monthly_billing_201012150546.zip
Response CSV (pipe) File Name:	    monthly_billing_201012150546.csv
 
Returns Zip File Name:		    returns.20101215.zip
Returns CSV (pipe) File Name:       returns.20101215.csv
 
Parsing Error File Name:	    monthly_billing_201012150546.error.csv
Validation Error File Name:	    monthly_billing_201012150546.validation.csv
 

File Format

Both request and response files must be formatted as standard CSV files only using pipe (|) instead of comma.

Usage:

 
*R – required in request/always present in response for ACH transactions and credit card transactions of all levels (I, II, III)
*R2 – required in request/always present in response for credit card transactions of level II and III only; optional for ACH and level I credit card transactions.
*R3 – required in request/always present in response for credit card transactions of III only; optional for ACH and level I, II credit card transactions.
*O – optional in request/not always present in response
*C – conditionally required; if token value is supplied, account information is not needed
 

Request File Format (Sale and Credit)

Response File Format (Sale and Credit)

Parsing Error File Format

Validation Error File Format

The Validation Error File format combines fields from Request File Format and Parsing Error File Format. Essentially, it will "echo back" all request fields adding errorCode and errorMessage columns at the end (as the final two columns). Please refer to the definitions of the corresponding file formats for more information.

Transaction Types

 
* S - sale
* C - credit
* D - decline sale
* X - decline credit
* E - error
* B - blacklist
* N - return
* G - chargeback
* R - reversal
* U - notice of change
 

Additional Notes

Dynamic Descriptor

An important feature that many merchants require is support for custom defined soft descriptor. Depending on the processor, this feature can be supported as a static value associated with an underlying merchant id or as a dynamic value that can be specified for each transaction processed.

• For credit cards, the descriptor is a single value 25 characters length.
• For ACH, the descriptor is comprised of two fields: Merchant Name (16) and Item Descriptor (10), the values should be separated with two colons (:), e.g:

[descriptor]::[merchantName]

When transactions are processed through PSP or an aggregator, it is common to include an identifier of the underlying payment processor or aggregator through a prefix, which is, usually, 3 or 6 characters in length. The prefix is added to the name of the merchant and is generally separated from it by an asterisk (*).

For each transaction processed through a processor, which supports dynamic descriptor feature, submitter can supply the value of the descriptor in the following format:

[item-descriptor]:[prefix]*[merchant-name]

Each part of the descriptor is optional. If respective value is not supplied at the transaction level (as part of the request), the default value will automatically be taken from the profile (if it is configured). When deciding on which value to supply, please make sure that maximum allowed length for each component is respected.

If the descriptor is not formatted correctly, the system is going to make its best attempt to properly truncate the values and process the transaction. A special warning will be issued and returned to the submitter (as warningCode field) explaining how descriptor should be adjusted in the future submissions.

Capture, Void, and Refund Operation

The request file must contain a header record with field names corresponding to the values provided. The response file will also contain a header record. Field order is not important.

Example of a request header record (not all available fields are included):

 
merchantAccountCode|transactionCode|transactionDate|amount|taxAmount|accountType|accountAccessory|accountNumber|holderName|holderType|street|city|state|zipCode|phone|email|itemCode|customerAccountCode|memo
 

Example of a response header record:

 
merchantAccountCode|transactionCode|transactionDate|referenceNumber|responseCode|responseMessage|avsResponseCode|processorCode|isRebillEnabled|token|transactionType|submissionCode|originalReferenceNumber|
accountNumberUpdated|accountAccessoryUpdated|tokenUpdated
 

Example of a .error header record:

 
errorCode|errorMessage
 

Example of a .validation header record:

 
merchantAccountCode|transactionCode|transactionDate|amount|taxAmount|accountType|accountAccessory|accountNumber|holderName|holderType|street|city|state|zipCode|phone|email|itemCode|customerAccountCode|memo|
errorCode|errorMessage
 

Note that transactionDate of the response message is the date when CC transaction was captured/declined or when an ACH return arrived. ACH returns come within 60 days of the processing date. Therefore, response files may contain ACH returns from the prior submission dates. It is recommended to use transactionCode value to correctly identify the original transaction submitted in the past.

For ACH responses will be generated; all valid and non-blacklisted transactions will come back as approved.

Service Fees

Quite often, companies that process transactions on behalf of other organizations may require that they explicitly indicate that the payment amount includes a certain part that constitutes service fees.

For example, a $105 sale is processed, $5 of which represents service fees that the company submitter wants to withhold when the deposits get remitted to the organization on behalf of which the transaction was done (e.g. organization gets $100 and submitter keeps a $5 service fee).

In order to accommodate these needs, Sale operation provides a feeAmount field, which should contain the amount of the processing fee that the submitter wants to withhold from remittance. (NOTE: based on merchant configurations, actual processing/interchange fee will be deducted either from the amount remitted to the organization beneficiary or from the service fee amount of the submitter.)

Re-bill Process

The system provides support for a re-bill process, in which certain card declines can be retried once or several times after the initial attempt. This is often done for declines that indicate a temporary issue with the funding source that might get resolved on the subsequent retry e.g. insufficient balance. Transactions with response codes configured for re-bill, will be automatically selected by the system and retried based on re-bill terms defined for any particular submitter (Merchant).

All responses (initial and re-bill results) will be sent back to the submitter using standard interchange protocol. Transactions that are still part of the re-bill process (and thus will have additional responses, possibly approvals reversing previous declines) are marked with the isRebillEnabled flag (set to 1). Submitter should decide how these transactions are to be handled; whether initial decline is recognized right away or whether final response (with isRebillEnabled set to 0) is to be awaited. All re-bill responses are returned to the submitter in the same way as ACH returns and chargebacks.

Sequence Number

A single sale transaction might have more than one chargeback/reversal pair associated with it. Sequence number indicates sequential number of the chargeback or reversal as they are received. Initial chargeback/reversal will have a value of 1 and the value will get incremented each subsequent round. Use this value to avoid misinterpretation of a new chargeback/reversal as a duplicate of a previously processed chargeback/reversal.

Transaction Groups

Transaction Groups is a concept used by the batch validation process, which validates deviations in amounts between recurring batches on any two subsequent months. Merchants not interested in this validation logic, should ignore this concept.

Transactions can be logically divided into groups. To assign a transaction to a group, it is sufficient to specify transactionGroupCode when a sale or credit request is made. When an incoming batch is validated and compared to the transactions processed in the previous month, the Transaction Group concept is taken into account. For example, if a merchant sends 2 files per month (on or around 1st and on or around 15th), and the transactions sent on the 1st are marked as "1st billing", while transactions sent on the 15th are marked as "15th billing" the validation mechanism will match (and calculate deviation) current month's "1st billing" with last month's "1st billing" and current month's "15th billing" with last month's "15th billing". When deviation exceeds allowable threshold, the batch is automatically placed in review queue.

Canada ACH

For ACH transaction processing in the US two fields are used:

• Routing Number
• Account Number

For ACH (EFT) transaction processing in Canada, three fields are required:

• Three-digit Institution Number
• Five-digit Branch Number
• Account Number

For processing purposes of Canadian ACH, the Institution Number and Branch Number are combined in a single routing number value using the rules below:

• The Canadian routing number is comprised of three (3) parts: a leading zero (0), three-digit institution number (YYY), and five-digit branch number (XXXXX), which go respectively all together with no dashes: 0YYYXXXX.
• The XXXXX-YYY format with a dash between the branch number and the institution number is only valid for paper-type transactions, such as checks. Thus, if a check reads XXXXX-YYY, the corresponding EFT code will be 0YYYXXXXX.

Retry Fee

The Retry Fee (or Re-bill Fee) is a feature giving the merchant the ability to apply a surcharge on approvals that result from retry process (see Re-bill Process for additional information]]). If a retry fee is defined, it will be added to the transaction amount when a reattempt of a previous decline is made. In the case of successful decline recycling (approval), the amount of the surcharge (retry fee) will be passed back in the standard response through retryFee field. This fee is not cumulative, and will be added to the original amount only once, no matter how many reattempts are made.

Batch Tokenization

When batch file is processed it is recommended to use tokens instead of actual account numbers. In such cases, the file is placed in an inbox folder and processed in a regular manner. However, in circumstances when unencrypted account numbers (credit card numbers, bank account numbers) are placed into a file, it is recommended that you put the file in an invault folder as opposed to inbox folder.

The Tokenization process is subsequently applied on all of the files in invault folder. All card numbers are converted into tokens and replaced with respective records in a request file and the new request file containing tokens only is automatically placed in an inbox folder for regular processing. Files will automatically be removed from invault folder after processing.

Notices of Change (NOCs)

When ACH transactions in the US and Canada are processed, the real-time approval information is not available like it is for credit cards. For this purpose many companies will verify accounts against blacklists and, if an account is not blacklisted, return an approval response by default. Subsequently, when any types of returns come back from the bank, they are forwarded over to the transaction's submitter/merchant.

Under some circumstances (e.g. bank mergers), a bank may need to update information about an account such as bank account number, routing number, or the name on the account. It is done through a "notice of change" mechanism, which is similar to the mechanism used to deliver ACH returns (see below). <p>IMPORTANT NOTE...do NOT confuse the two previous concepts!

• ACH Return implies that a payment was not honored (response file transaction type = N).
• Notice of Change implies a payment was processed successfully but some information (which is provided within the NOC) should be updated in any future payment requests for this account (response file transaction type = U).

Effective Date

Transactions with an effective date (transaction date) in the past as well as in the future can be processed. Any transactions with dates in the past are processed with the effective date of today, while any future dated transactions are processed on the specified effective date in the future. The only limitation is that a single file should not mix transactions with past, current, and future effective dates i.e. all transactions in the file must be either in the past, effective today, or effective in the future.

Examples (Header Records)

The request file must contain a header record with field names corresponding to the values provided. The response file will also contain a header record. Field order is not important.

.

Example of a request header record (not all available fields are included):

 
merchantAccountCode|transactionCode|transactionDate|amount|taxAmount|accountType|accountAccessory|accountNumber|holderName|holderType|
street|city|state|zipCode|phone|email|itemCode|customerAccountCode|memo
 

Example of a response header record:

 
merchantAccountCode|transactionCode|transactionDate|referenceNumber|responseCode|responseMessage|avsResponseCode|processorCode|
isRebillEnabled|token|transactionType|submissionCode|originalReferenceNumber|
accountNumberUpdated|accountAccessoryUpdated|tokenUpdated
 

Example of a .error header record:

 
errorCode|errorMessage
 

Example of a .validation header record:

 
merchantAccountCode|transactionCode|transactionDate|amount|taxAmount|accountType|accountAccessory|accountNumber|holderName|holderType|
street|city|state|zipCode|phone|email|itemCode|customerAccountCode|memo|
errorCode|errorMessage
 

Example of a .return header record:

 
merchantAccountCode|transactionCode|transactionDate|referenceNumber|responseCode|responseMessage|avsResponseCode|processorCode|token|
accountNumberUpdated|accountAccessoryUpdated|tokenUpdated|transactionType|submissionCode|originalReferenceNumber|isRebillEnabled|sequenceNumber|
transactionInternalCode|accountTypeUpdated|holderNameUpdated|retryFeeAmount|expectedEffectiveDate|warningCode|amount|accountNumberMasked|accountAccessory|
accountType|holderName
 

Note that transactionDate of the response message is the date when the Credit Card transaction was captured/declined or when an ACH return arrived. ACH returns come in within 60 days of the processing date. Therefore, response files may contain ACH returns from the prior submission dates. It is recommended to use transactionCode value to correctly identify the original transaction submitted in the past.

For ACH responses that will be generated - all valid and non-blacklisted transactions will come back as approved.

Integration

Below is all of the information that you will need to test your integration with the gateway and to get certified with the gateway owner.

Test Cards & Bank Accounts

The following accounts will be accepted by the test server's validation mechanism and thus can be used for preliminary testing (they are also used as part of the certification process):

Certification Scenarios

Below are certification scenarios that you can use for testing. The specified field values must be included in the corresponding request fields. If integration is done correctly, you will get specified values in the corresponding response fields. If you use any account number not listed as Test account above, you are likely to get a validation error (unless you use a real account). If use any valid test account, but don't include all of the fields listed for any given certification scenario, you will get a D01 - Denied by customer's bank(Issuer Unavailable) decline.

When you are ready to get certified, you need to submit a single file with all of the certification scenarios below for review. For each review (even repeated ones) you must resubmit all scenarios. When you request the certification team to review your submission, always include the file name that you want to be checked.

Sale

Credit

Response Codes

These codes are configured on the Response Codes & Reversal Reason Mappings configuration.

Response Type

• Good – transaction request was successful.
• Soft – transaction request was declined, but a subsequent request may result in approval.
• Hard – transaction request was permanently declined.

Change History

Codes

Below is a list of the available response codes in the application. Click the appropriate link to go to that specific section on the MosoPay Response Codes page.

• Credit Card Response
• ACH/eCheck Response
• ACH/eCheck Notification of Change (US)
• ACH/eCheck Response (Canada)
• Address Verification Result
• CVV2 Response

Exception Codes

• Process Error Codes
• Transaction Error Codes
• Extension Specific Codes
  • MosoPay Real-Time Authorization Capture

Related Information

MosoPay
MosoPay Real-Time HTTPs Integration MosoPay Real-Time HTTPs Integration-Message Formatting MosoPay Batch FTPs Integration MosoPay Response Codes Response Codes & Reversal Reason Mappings		System Configuration The MosoMRM User Interface The MosoMRM Glossary Setting Up Your MosoMRM System