Overview
This page is a detailed listing of the Message Formats used in the MosoPay Real-Time HTTPs Integration.
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; if trackData is supplied, address information is not needed.
- * – Required fields in these specific sections are only required if this specific feature is used.
Authorization, Sale and Credit Request
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| requestType | String | sale-auth, sale, credit-auth, credit | R | |
| userName | String | R | Provided by gateway owner | |
| password | String | R | Provided by gateway owner | |
| merchantAccountCode | Integer | R | Provided by gateway owner | |
| accountAccessory | String | R | expDate or routing number | |
| accountNumber | String | C | Credit card number or bank account number | |
| accountType | String | R – credit card; C – checking; S - savings | R | |
| holderName | String | (optional if trakData is present) | C | |
| holderType | String | P – person; O - organization (optional if trakData is present) | C | |
| street | String | (optional if trakData is present) | C | |
| city | String | (optional if trakData is present) | C | |
| state | String | O | ||
| zipCode | String | (optional if trakData is present) | C | |
| phone | String | (digits only; no special chars) | O | |
| String | O | |||
| cvv2 | String | O | ||
| cvv2Indicator | String | provided, not_provided, illegible, not_present | O | Explains whether cvv2 was provide and if not, why |
| trackData | String | (sale and authorization only) | O | |
| transactionCode | String | O | Value identifying this transaction in submitter’s system | |
| amount | Integer | R | Amount in cents | |
| taxAmount | Integer | O | Amount of tax in cents included in amount field | |
| feeAmount | Integer | authorization and sale only | O | Amount of service fee included in amount field. See additional notes |
| isPartialAuthorization | Boolean | 1 - true, 0 - false: Default = 0 | O | If set to true, partial authorization will happen when full authorization amount is not available. See Additional Notes |
| transactionIndustryType | String | Possible Values | R | |
| itemCode | String | O | May include product/service code in submitter’s system for which this payment is taken | |
| memo | String | O | Notes | |
| customerAccountCode | String | O | Value identifying customer in submitter’s system | |
| token | String | C | token value replacing accountNumber |
Authorization, Sale or Credit Response
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| responseType | String | authorization, sale, credit | R | |
| merchantAccountCode | Integer | R | (echo back) | |
| transactionCode | String | O | (echo back) | |
| transactionDate | Date | yyyymmdd | R | Post date of the transaction |
| referenceNumber | String | R | Transaction identification in gateway | |
| responseCode | String | R | Gateway generated response code | |
| responseMessage | String | R | Gateway generated response message | |
| avsResponseCode | String | O | Address verification code | |
| processorCode | String | O | Authorization number issued by the processor; often shown on credit card receipt | |
| token | String | C | Token generated for the provided payment information |
Capture and Void/Refund Request
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| requestType | String | capture, void, refund | R | |
| userName | String | R | Provided by gateway owner | |
| password | String | R | Provided by gateway owner | |
| merchantAccountCode | Integer | R | Provided by gateway owner | |
| referenceNumber | String | R | Reference code of the transaction to be confirmed or voided | |
| transactionCode | String | for void/refund only | O | Value identifying this transaction in submitter’s system |
| amount | Integer | for capture only | O | Amount that is to be captured; by default is equal to the original authorization amount, but can be set to a lower value. Used traditionally to handle tips in restaurants. |
Capture and Void/Refund Response
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| responseType | String | capture, void, refund | R | |
| merchantAccountCode | Integer | R | (echo back) | |
| referenceNumber | String | R | Transaction identification in gateway | |
| responseCode | String | R | Gateway generated response code | |
| responseMessage | String | R | Gateway generated response message | |
| transactionCode | String | O | (echo back) |
Return Callback Request
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| requestType | String | decline, chargeback, reversal | R | |
| merchantAccountCode | Integer | R | (echo back) | |
| transactionCode | String | O | (echo back from the original transaction) | |
| transactionDate | Date | yyyymmdd | R | Date the return was posted |
| referenceNumber | String | R | Transaction identification in gateway | |
| responseCode | String | R | Gateway generated response code | |
| responseMessage | String | R | Gateway generated response message |
Return Callback Response
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| responseType | String | decline, chargeback, reversal | R | |
| merchantAccountCode | Integer | R | (echo back) | |
| referenceNumber | String | R | (echo back) |
Tokenization Request
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| requestType | String | tokenization | R | |
| userName | String | R | Provided by gateway owner | |
| password | String | R | Provided by gateway owner | |
| merchantAccountCode | Integer | R | Provided by gateway owner | |
| transactionCode | String | O | Value identifying this transaction in submitter’s system | |
| accountType | String | R – credit card; C – checking; S - savings | R | |
| accountAccessory | String | R | expiration date or routing number | |
| accountNumber | String | R | Credit card number or bank account number |
Tokenization Response
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| responseType | String | tokenization | R | |
| merchantAccountCode | Integer | R | (echo back) | |
| transactionCode | String | O | (echo back) | |
| token | String | C | Token generated for the provided payment information |
Export Request
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| requestType | String | export | R | |
| userName | String | R | Provided by gateway owner | |
| password | String | R | Provided by gateway owner | |
| fromDate | Date | yyyymmdd | R | |
| toDate | Date | yyyymmdd | R | |
| zip | String | Y/N (default Y) | O | Whether to gzip the result or send as plain text (recommended on large files) |
Exception Response
| Name | Type | Possible values / Format | Usage | Description |
|---|---|---|---|---|
| responseType | String | exception | R | |
| errorCode | Integer | R | ||
| errorMessage | String | R |
Additional Notes
Capture, Void and Refund Operation:
MosoPay provides an auto-settlement mechanism to all merchants. Settlement occurs once per day at the time designated by a merchant (usually at night). When settlement occurs, all sales processed the same day, as well as all captured authorizations are posted and the money is deposited. Consequently, Capture operations can be issued on authorization if, and only if, the settlement has not yet occurred. The same rule applies to voids issued on sales. If a merchant misses the settlement cut-off time, a new sale (in place of a Capture) or a new credit (in place of a Void) will have to be issued.
Capture operation can be used in cases when the authorization amount and capture amount are different e.g. it is customary in the restaurant business to authorize an additional 20% of the base bill amount to account for tip and then capture that specific amount, once the customer signs the receipt and indicates precise tip amount. Capture operation can be used in such cases to alter the original authorization amount. Capture amount cannot exceed authorization amount.
Void can reverse a sale or credit before settlement for the day occurs. Refund works for Sale transactions ONLY and behaves as a Void, but issues a credit transaction if settlement has already occurred. Consequently, Refund will always succeed in reversing any existing (non-refunded) sale transaction.
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.)
Callbacks:
Merchants who would like to be notified in real time when a credit card chargeback or an ACH decline occurs can provide a callback URL to which MosoPay will post a response with appropriate information.
The callback page will normally extract the information sent by MosoPay through HTTP parameters, execute appropriate business logic, and "echo back" the referenceNumber to confirm successful callback consumption. MosoPay will repeat callback posting unless a successful response (echo back) is received.
Once a chargeback has occurred, it may still be possible for it to be reversed and the money returned back to the merchant. Therefore, it is important not only to handle chargebacks, but also deal appropriately with reversals.
Transaction Export:
As an alternative to callback notifications, MosoPay provides a way for merchants to load the response history of all transactions that were processed. Using the export request format, a merchant can request a history of returns (bank account returns, chargebacks and reversals) that occurred during the specified time period. The result is a pipe (|) delimited file (gzip or plain text) with the column names corresponding to fields in Return Callback Response Fields format. Merchants can use this operation for auditing purposes or if they feel that the callbacks logic on their end may have malfunctioned.
NOTE: To avoid performance issues, the date range for export should not exceed a one month period.
Related Information
| MosoPay | ||
|---|---|---|
MosoPay Real-Time HTTPs Integration | System Configuration | |