MerchantE API Docs
POST/transaction
Download OpenAPI (this endpoint)JSON|Download OpenAPI (generated)JSON

Process a payment gateway transaction (raw)

Advanced: The Payment Gateway is implemented as a single endpoint. Use `transaction_type` to select the business operation (sale, refund, void, etc.).

Request

This raw endpoint has a large request schema (multiple transaction types). The table shows a shallow overview.

profile_id
profile_id
string
Yes
Validations
pattern=^\d{20}$ · maxLength=20
Description
ID issued by MerchantE
profile_key
profile_key
string
Yes
Validations
maxLength=32
Description
API password assigned by MerchantE
transaction_typeenum
transaction_type
string
Yes
Validations
D
Description
Sale transaction (D)
card_number
card_number
string
No
Validations
pattern=^\d{5,22}$ · minLength=5 · maxLength=22
Description
Payment card number. Do not send if using card_id or card_swipe.
card_id
card_id
string
No
Validations
maxLength=32
Description
Stored customer card information (token from Store Card request)
card_swipe
card_swipe
string
No
Validations
—
Description
Contents of payment card read by electronic device. Always processed as card-present.
card_exp_date
card_exp_date
string
No
Validations
pattern=^\d{4}$ · maxLength=4
Description
Card expiration date, submit as MMYY. Required when using card_number.
cvv2
cvv2
string
No
Validations
pattern=^\d{3,4}$ · minLength=3 · maxLength=4
Description
Card Verification Value:
- Visa: CVV2
- Mastercard: CVC2
- Discover: CID
- American Express: CID (4 digits)
cardholder_name
cardholder_name
string
No
Validations
maxLength=64
Description
Cardholder's full name
cardholder_first_name
cardholder_first_name
string
No
Validations
maxLength=15
Description
Cardholder first name
cardholder_last_name
cardholder_last_name
string
No
Validations
maxLength=30
Description
Cardholder last name
cardholder_street_address
cardholder_street_address
string
No
Validations
maxLength=19
Description
First 19 characters of cardholder's billing address
cardholder_zip
cardholder_zip
string
No
Validations
pattern=^\d{5}(\d{4})?$
Description
Cardholder's ZIP code (5 or 9 digits)
cardholder_city
cardholder_city
string
No
Validations
maxLength=20
Description
Cardholder's city
cardholder_state
cardholder_state
string
No
Validations
maxLength=2
Description
Cardholder's state (2-letter code)
cardholder_country
cardholder_country
string
No
Validations
maxLength=2
Description
Cardholder's country code
cardholder_email
cardholder_email
string
No
Validations
format=email · maxLength=60
Description
Cardholder's billing email
cardholder_phone
cardholder_phone
string
No
Validations
pattern=^\d{10}$ · maxLength=10
Description
Cardholder's billing phone (digits only, no dashes)
card_on_fileenum
card_on_file
string
No
Validations
Y, N
Description
Indicates if the transaction is a card on file transaction
cit_mit_indicatorenum
cit_mit_indicator
string
No
Validations
C101, C102, C103, C104, M101, M102, M103, M104, M205, M206, M207, M208
Description
Card on File transaction indicator (Mastercard):
Cardholder-Initiated:
- C101 = Credential-on-File (ad-hoc)
- C102 = Standing Order (variable amount and fixed frequency)
- C103 = Subscription (fixed amount and frequency)
- C104 = Installment (single purchase with known amount and set frequency)
Merchant-Initiated Recurring/Installment:
- M101 = Unscheduled Credential-on-File (variable amount, no regular intervals)
- M102 = Standing Order (variable amount and fixed frequency at regular intervals)
- M103 = Subscription (fixed amount and frequency)
- M104 = Installment (single purchase with known amount and set frequency)
Merchant-Initiated Industry Practice:
- M205 = Partial Shipment
- M206 = Related/Delayed Charge
- M207 = No Show Charge
- M208 = Resubmission
store_cardenum
store_card
string
No
Validations
Y, y
Description
Store card for future use (creates permanent token)
transaction_amount
transaction_amount
string
Yes
Validations
pattern=^\d+\.\d{2}$ · maxLength=12
Description
Transaction amount (decimal format)
transaction_id
transaction_id
string
No
Validations
maxLength=32
Description
Unique identifier for the transaction (from previous transaction)
invoice_number
invoice_number
string
No
Validations
maxLength=20
Description
Merchant-defined invoice number (no special characters)
purchase_order
purchase_order
string
No
Validations
maxLength=20
Description
Purchase order number
purchase_id
purchase_id
string
No
Validations
maxLength=20
Description
Merchant-defined purchase identifier
tax_amount
tax_amount
string
No
Validations
pattern=^\d+\.\d{2}$ · maxLength=9
Description
Tax amount
shipping_amount
shipping_amount
string
No
Validations
pattern=^\d+\.\d{2}$ · maxLength=9
Description
Shipping/freight amount
tran_fee_amount
tran_fee_amount
string
No
Validations
pattern=^\d+\.\d{2}$ · maxLength=9
Description
Surcharge amount for transaction
currency_code
currency_code
string
No
Validations
maxLength=3
Description
ISO 4217 currency code (default 840 = USD)
moto_ecommerce_indenum
moto_ecommerce_ind
string
Yes
Validations
Z, 1, 2, 3, 5, 6, 7, 07, 8, A
Description
Mail Order / Telephone Order / E-commerce indicator.
Common values:
- 1: MOTO (Mail Order/Telephone Order) - Single transaction
- 2: MOTO (Mail Order/Telephone Order) - Recurring
- 3: MOTO (Mail Order/Telephone Order) - Installment
- 7: E-commerce (Internet/Mobile)
retry_id
retry_id
string
No
Validations
maxLength=16
Description
Enables Inquiry transaction of this request
message_reason_code
message_reason_code
string
No
Validations
maxLength=4
Description
Message reason code for deferred authorizations
rctl_commercial_cardenum
rctl_commercial_card
string
No
Validations
Y, y
Description
Returns commercial card type identification
rctl_account_balanceenum
rctl_account_balance
string
No
Validations
Y, y
Description
Returns prepaid card balance (if offered by issuer)
rctl_partial_authenum
rctl_partial_auth
string
No
Validations
Y, y
Description
Enable partial authorization
rctl_product_levelenum
rctl_product_level
string
No
Validations
Y, y
Description
Returns product level information
rctl_extended_avsenum
rctl_extended_avs
string
No
Validations
Y, y
Description
Returns extended AVS information
merchant_name
merchant_name
string
No
Validations
maxLength=25
Description
DBA Name to appear on cardholder statement (* allowed, must have static prefix)
merchant_phone
merchant_phone
string
No
Validations
pattern=^\d{10}$ · maxLength=10
Description
Customer Service phone number (no dashes or special characters)
merchant_category_code
merchant_category_code
string
No
Validations
pattern=^\d{4}$ · maxLength=4
Description
Merchant Category Code (SIC)
merchant_city
merchant_city
string
No
Validations
maxLength=13
Description
—
merchant_state
merchant_state
string
No
Validations
maxLength=3
Description
—
merchant_zip
merchant_zip
string
No
Validations
maxLength=9
Description
—
recurring_pmt_num
recurring_pmt_num
string
No
Validations
pattern=^\d{1,2}$ · maxLength=2
Description
Payment number of this transaction
recurring_pmt_count
recurring_pmt_count
string
No
Validations
pattern=^\d{1,2}$ · maxLength=2
Description
Total number of payments
hotel_folio_number
hotel_folio_number
string
No
Validations
maxLength=25
Description
Hotel folio number
hotel_check_out_date
hotel_check_out_date
string
No
Validations
pattern=^\d{6}$
Description
Check-out date (MMDDYY)
hotel_room_rate
hotel_room_rate
string
No
Validations
pattern=^\d+\.\d{2}$
Description
Daily room rate
hotel_room_tax
hotel_room_tax
string
No
Validations
pattern=^\d+\.\d{2}$
Description
Room tax amount
hotel_no_showenum
hotel_no_show
string
No
Validations
Y, N
Description
No show indicator
rental_agreement_number
rental_agreement_number
string
No
Validations
maxLength=20
Description
Rental agreement number
rental_date
rental_date
string
No
Validations
pattern=^\d{6}$
Description
Rental date
rental_return_date
rental_return_date
string
No
Validations
pattern=^\d{6}$
Description
Return date
rental_return_city
rental_return_city
string
No
Validations
maxLength=20
Description
Return city
rental_return_state
rental_return_state
string
No
Validations
maxLength=2
Description
Return state
rental_return_country
rental_return_country
string
No
Validations
maxLength=32
Description
Return country
payment_account_reference
payment_account_reference
string
No
Validations
maxLength=35
Description
Payment Account Reference (AMEX=35 chars with all 9s, Other cards=29 chars with all 9s)
account_data_sourceenum
account_data_source
string
Yes
Validations
@, Y
Description
Indicates where credentials came from:
- @ = Manually keyed, not Track capable
- Y = Credentials obtained from file (not from cardholder)

Responses

200
Successful transaction response

Successful transaction response

Common3 fields
transaction_idstring
Unique identifier for the transaction
error_codestring
Error/Response code:
- 000 = Approval
- 005 = Do Not Honor
- See full error code table in documentation
auth_response_textstring
Authorization response message
When Provided5 fields
auth_codestring
Authorization code (6 characters)
avs_resultstring
Address Verification Service result
  • 0—AVS Error - Retry
  • A—Address Match Only
  • B—Address Match, Postal Code not verified
  • C—No Match
  • D—Address and Postal Code Match
  • E—AVS Error - Ineligible
  • F—Address and Postal Code Match (UK only)
  • G—Non-US Issuer does not participate
  • I—Address not verified, Postal Code not verified
  • M—Address and Postal Code Match
  • N—No Match
  • P—Postal Code Match, Address not verified
  • R—Issuer System Unavailable
  • S—Service not Supported
  • U—Address unavailable
  • W—9-digit Postal Code Match, Address no match
  • X—Exact match, 9-digit Postal Code
  • Y—Address and 5-digit Postal Code Match
  • Z—5-digit Postal Code Match, Address no match
cvv2_resultstring
CVV2 verification result
  • M—CVV2 Match
  • N—CVV2 No Match
  • P—Not Processed
  • S—CVV2 should be on card but merchant indicates not present
  • U—Issuer not certified
card_idstring
Permanent token (stored card) identifier returned when store_card=Y is used
maxLength=32
batch_numberstring
Batch number returned for Batch Close responses
maxLength=20
Other Fields12 fields
account_balancestring
Account balance (for prepaid cards)
batch_idstring
Batch ID
batch_statusstring
Batch status
card_exp_datestring
Card expiration date (MMYY)
card_last_fourstring
Last 4 digits of card number
card_typestring
Card type (Visa, Mastercard, Discover, Amex, etc.)
commercial_cardstring
Commercial card type
  • B—Business Card
  • R—Corporate Card
  • S—Purchasing Card
  • 0—Non-commercial card
extended_avs_resultstring
Extended AVS result details
partial_auth_indicatorstring
Partial authorization indicator
payment_account_referencestring
Payment Account Reference returned by processor
product_levelstring
Product level code
transaction_feestring
Transaction fee amount

Example response

transaction_id: 5fc24a2abe160c232a6dccd72ed8c5ba
error_code: "000"
auth_response_text: Approval T02786
avs_result: "0"
cvv2_result: M
auth_code: T02786
400
Bad request - invalid parameters

Bad request - invalid parameters

401
Unauthorized - invalid credentials

Unauthorized - invalid credentials

500
Server error

Server error

Error and result codes

The gateway response includes fields such as error_code,avs_result, andcvv2_result. Use the tables to interpret them.

Gateway error codes
visa
CodeMeaning
19Re-enter Transaction
28File Temporarily Unavailable
39No Credit Account
58Transaction Not Permitted on Terminal
68Response Received Too Late
78Blocked - First Use
82Negative CAM, dCVV, iCVV, or CVV results
85No Reason to Decline
91Issuer or Switch Inoperative
92Routing Error
93Violation of Law
94Duplicate Transaction
96System Malfunction
000Approval
005Do Not Honor
012Invalid Transaction
013Invalid Amount
014Invalid Card Number
015Invalid Issuer
021Unable to Back Out Transaction
023Unacceptable Transaction Fee
025Unable to Locate Record
041Lost Card
043Stolen Card
046Closed Account
051Insufficient Funds
052No Checking Account
053No Savings Account
054Expired Card
055Incorrect PIN
056No Card Record
057Transaction Not Permitted to Cardholder
061Exceeds Withdrawal Limit
062Restricted Card
063Security Violation
065Exceeds withdrawal frequency
075PIN Try Exceeded
076Unable to Locate Previous Message
0N4Exceeds Issuer Withdrawal Limit
0N7CVV2 Failure
0N0Unable to Authorize
0P5PIN Change/Unblock Request Declined
0Q1Invalid Card Authentication Data
0R0Stop Payment Order
0R1Revocation of Authorization Order
0R3Revocation of All Authorizations Order
0TALocal Transaction; Time-Out at Issuer System Detected
0XAForward to Issuer
0XDForward to Issuer
mastercard
CodeMeaning
1922 Mer Not Qual or Re-enter Transaction
2822 Mer Not Qual or File Temporarily Unavailable
3922 Mer Not Qual or No Credit Account
58Function Not Permitted to Merchant
68Response Received Too Late
78Blocked, First Used
79Transaction Not Permitted to Acquirer/Terminal
82Transaction Not Permitted to Acquirer/Terminal
83Transaction Not Permitted to Acquirer/Terminal
85No Reason to Decline
91Issuer or Switch Inoperative
92Routing Error
94Duplicate Transaction
96System Malfunction
000Approval
00322 Mer Not Qual or Honor with Identification
004Not used at this time
00522 Mer Not Qual or Do Not Honor
01222 Mer Not Qual or Invalid Transaction
01322 Mer Not Qual or Invalid Amount
01422 Mer Not Qual or Invalid Card Number
01522 Mer Not Qual or Invalid Issuer
02122 Mer Not Qual or Unable to Back Out Transaction
02522 Mer Not Qual or Unable to Locate Record On File
041Lost Card - Pick Up (Fraud Account)
043Stolen Card - Pick Up (Fraud Account)
046Closed Account
051Insufficient Funds
052No Checking Account
053No Savings Account
054Expired Card
055Incorrect PIN
056No Card Record
057Function Not Permitted to Cardholder
061Exceeds Approval Amount Limit
062Restricted Card
063Security Violation
065Exceeds Withdrawal Frequency Limit
075Allowable number of PIN-Entry tries exceeded - Card Locked
0N0Unable to Authorize
0N3Cash Back Service Not Available
0N4Exceeds Issuer Withdrawal Limit
0N7CVV2 Failure
0P5PIN Change/Unblock Request Declined
0Q1Invalid Card Authentication Data
0R0Stop Payment Order
0R1Revocation of Authorization Order
0R3Revocation of All Authorizations Order
0XAForward to Issuer
0XDForward to Issuer
AVS result codes
CodeMeaning
0AVS Error - Retry, System unavailable or Timed out
AAddress Match Only
BAddress Match, Postal Code not verified
CNo Match
DAddress and Postal Code Match
EAVS Error - Ineligible (not a mail/phone order)
FAddress and Postal Code Match (UK only)
GNon-US Issuer does not participate
IAddress not verified, Postal Code not verified
MAddress and Postal Code Match
NNo Match
PPostal Code Match, Address not verified
RIssuer System Unavailable
SService not Supported
UAddress unavailable
W9-digit Postal Code Match, Address no match
XExact match, 9-digit Postal Code
YAddress and 5-digit Postal Code Match
Z5-digit Postal Code Match, Address no match
CVV result codes
CodeMeaning
MCVV2 Match
NCVV2 No Match
PNot Processed
SCVV2 should be on card but merchant indicates not present
UIssuer not certified

Code samples

Copy-paste ready code in your preferred language for the Test environment.

API call

Copy/paste friendly
curl -X POST "https://cert.merchante-solutions.com/mes-api/transaction" \
  -H "Content-Type: application/x-www-form-urlencoded"