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

Create a pre-authorization

Authorizes payment without capture (transaction_type=P).

Request Parameters

Content type: application/x-www-form-urlencoded

Required9 fields
Conditional: Provide one of: card_number + card_exp_date OR card_id OR card_swipeProvide exactly one credential source. card_exp_date is required when using card_number.
profile_idstring
ID issued by MerchantE
pattern=^\d{20}$ · maxLength=20
profile_keystring
API password assigned by MerchantE
maxLength=32
transaction_typestringenum
Pre-Authorization transaction (P)
transaction_amountstring
Transaction amount (decimal format)
pattern=^\d+\.\d{2}$ · maxLength=12
account_data_sourcestringenum
Indicates where credentials came from:
- @ = Manually keyed, not Track capable
- Y = Credentials obtained from file (not from cardholder)
maxLength=1
card_numberstring
Payment card number. Do not send if using card_id or card_swipe.
pattern=^\d{5,22}$ · minLength=5 · maxLength=22
card_idstring
Stored customer card information (token from Store Card request)
maxLength=32
card_swipestring
Contents of payment card read by electronic device. Always processed as card-present.
moto_ecommerce_indstringenum
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)
maxLength=2
Recommended5 fields
card_exp_datestring
Card expiration date, submit as MMYY. Required when using card_number.
pattern=^\d{4}$ · maxLength=4
cvv2string
Card Verification Value:
- Visa: CVV2
- Mastercard: CVC2
- Discover: CID
- American Express: CID (4 digits)
pattern=^\d{3,4}$ · minLength=3 · maxLength=4
cardholder_street_addressstring
First 19 characters of cardholder's billing address
maxLength=19
cardholder_zipstring
Cardholder's ZIP code (5 or 9 digits)
pattern=^\d{5}(\d{4})?$
invoice_numberstring
Merchant-defined invoice number (no special characters)
maxLength=20

Example request

Starter values are pre-filled; replace with your own credentials and test data.

profile_id: YOUR_PROFILE_ID_HERE
profile_key: YOUR_PROFILE_KEY_HERE
transaction_type: P
account_data_source: "@"
card_number: "4012301230121237"
card_exp_date: "1225"
cvv2: "999"
transaction_amount: "100.00"
cardholder_street_address: 456 Oak Ave
cardholder_zip: "10001"
moto_ecommerce_ind: "7"

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" \
  --data-urlencode "profile_id=YOUR_PROFILE_ID_HERE" \
  --data-urlencode "profile_key=YOUR_PROFILE_KEY_HERE" \
  --data-urlencode "transaction_type=P" \
  --data-urlencode "account_data_source=@" \
  --data-urlencode "card_number=4012301230121237" \
  --data-urlencode "card_exp_date=1225" \
  --data-urlencode "cvv2=999" \
  --data-urlencode "transaction_amount=100.00" \
  --data-urlencode "cardholder_street_address=456 Oak Ave" \
  --data-urlencode "cardholder_zip=10001" \
  --data-urlencode "moto_ecommerce_ind=7"