Network Merchants (NMI)
Integration Resources
Direct Post API
Documentation
June 2007
Table of Contents
Methodology........................................................................................................ 2 Direct Post Method (Server to Server) FIG. 1 ................................................................ 2 Transaction Types .............................................................................................. 3 Sale (sale) ........................................................................................................................ 3 Authorization (auth) ........................................................................................................ 3 Capture (capture) ............................................................................................................ 3 Void (void) ...................................................................................................................... 3 Refund (refund) ............................................................................................................... 3 Credit (credit) .................................................................................................................. 3 Update (update) ............................................................................................................... 3 Transaction Variables ......................................................................................... 4 Sale/Authorization/Credit ............................................................................................... 4 Capture ............................................................................................................................ 5 Void................................................................................................................................. 5 Refund ............................................................................................................................. 5 Update ............................................................................................................................. 5 Transaction Response Variables....................................................................... 6 Standard Response .......................................................................................................... 6 Retail Data ........................................................................................................... 6 Passing Unencrypted Retail Magnetic Stripe Data ......................................................... 6 Passing MagTek Magensa encrypted Magnetic Stripe Data .......................................... 6 Testing Information ............................................................................................ 7 Transaction Testing Account .......................................................................................... 7 Transaction POST URL .................................................................................................. 7 Test Transaction Information .......................................................................................... 7 Triggering Errors in Test Mode ...................................................................................... 8 Examples ............................................................................................................. 8 Direct Post Format .......................................................................................................... 8 Changelog ........................................................................................................... 8 Appendix 1 – AVS Response Codes ................................................................. 9 Appendix 2 – CVV Response Codes ................................................................. 9 Appendix 3 – response_code Lookup Table .................................................. 10 Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 1
Methodology
There are two primary options in which transactions can be submitted through the
Payment Gateway API. The simplest, most direct, and transparent method is our
Direct Post Method. This document describes the Direct Post Method.
Direct Post Method (Server to Server) FIG. 1
1. The customer sends their payment
information to the merchant’s web site.
2. The merchant’s web site posts the payment
data to the Payment Gateway.
3. The Payment Gateway responds
immediately with the results of the
transactions.
4. The merchant’s web site displays the
appropriate message to the customer.
The communication method used to send messages to the Payment Gateway’s
server is the standard HTTP protocol over an SSL connection.
In the Direct Post method, the communications with the cardholder (Steps 1 and
4) are developed completely by the merchant and therefore are not defined by the
Payment Gateway. Step 1 should simply collect the payment data from the
cardholder and Step 4 should display the appropriate transaction receipt or
declined message.
In Step 2, transaction details should be delivered to the Payment Gateway using
the POST method with the appropriate variables defined below posted along with
the request.
In Step 3, the transaction responses are returned in the body of the HTTP
response in a query string name/value format delimited by ampersands. For
example: variable1=value1&variable2=value2&variable3=value3
Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 2
Transaction Types
Sale (sale)
Transaction sales are submitted and immediately flagged for settlement.
These transactions will automatically be settled.
Authorization (auth)
Transaction authorizations are authorized immediately but are not flagged
for settlement. These transactions must be flagged for settlement using
the capture transaction type. Authorizations typically remain active for
three to seven business days.
Capture (capture)
Transaction captures flag existing authorizations for settlement. Only
authorizations can be captured. Captures can be submitted for an amount
equal to or less than the original authorization.
Void (void)
Transaction voids will cancel an existing sale or captured authorization.
In addition, non-captured authorizations can be voided to prevent any
future capture. Voids can only occur if the transaction has not been
settled.
Refund (refund)
Transaction refunds will reverse a previously settled transaction. If the
transaction has not been settled, it must be voided instead of refunded.
Credit (credit)
Transaction credits apply a negative amount to the cardholder’s card. In
most situations credits are disabled as transaction refunds should be used
instead.
Update (update)
Transaction updates can be used to update previous transactions with
specific order information, such as a tracking number and shipping carrier.
Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 3
Transaction Variables
Sale/Authorization/Credit
Variable Name
type
Required*
Required
username
password
ccnumber
ccexp
checkname
checkaba
checkaccount
account_holder_type
account_type
sec_code
amount
cvv
payment
currency
processor_id
Required
Required
Required**
Required**
Required**
Required**
Required**
Required**
Required**
Optional**
Required
Recommended
Optional **
Optional
Optional
dup_seconds
Optional
Format
sale / auth / credit
MMYY
business / personal
checking / savings
PPD/WEB/TEL/CCD
x.xx
creditcard / check
3 digit ISO-4217
Description
sale = Transaction Sale
auth = Transaction Auth
credit = Transaction Credit
Username assigned to merchant account
Password for the specified username
Credit card number
Credit card expiration (ie. 0711 = 7/2011)
The name on the customer’s ACH Account.
The customer’s bank routing number
The customer’s bank account number
The customer’s type of ACH account
The customer’s ACH account entity
ACH Standard Entry Class codes
Total amount to be charged (i.e. 10.00)
Card security code
Set Payment Type to ACH or Credit Card
Specify transaction currency defaults to USD
If using Multiple MIDs, route to this
processor. processor_id is obtained under
Options->Load Balancing in the Control Panel
Disable Duplicate checking (in seconds)
(On supported processors)
descriptor
Optional
Set payment descriptor
(On supported processors)
descriptor_phone
Optional
Set payment descriptor phone
(On supported processors)
billing_method
product_sku_#
orderdescription
orderid
ipaddress
tax
shipping
ponumber
firstname
lastname
company
address1
address2
city
state
zip
country
phone
fax
email
validation
Optional
Optional
Optional
Optional
Recommended
Level II
Level II
Level II
Recommended
Recommended
Optional
Recommended
Optional
Recommended
Recommended
Recommended
Recommended
Recommended
Optional
Recommended
Optional
recurring
product_sku_1
xxx.xxx.xxx.xxx
x.xx
x.xx
CC
CC (ISO-3166)
Set Recurring Commerce Indicator
Associate API call with Recurring SKU
Order description
Order Id
IP address of the cardholder
Total tax amount
Total shipping amount
Original Purchase Order
Cardholder’s first name
Cardholder’s last name
Cardholder’s company
Card billing address
Card billing address – line 2
Card billing city
Card billing state (2 character abbrev.)
Card billing zip code
Card billing country (ie. US)
Billing phone number
Billing fax number
Billing email address
Specify which Validation processors to use. If
variable is passed blank, use none.
Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 4
shipping_firstname
shipping_lastname
shipping_company
shipping_address1
shipping_address2
shipping_city
shipping_state
shipping_zip
shipping_country
shipping_email
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
Optional
CC (ISO-3166)
Shipping first name
Shipping last name
Shipping company
Shipping address
Shipping address – line 2
Shipping city
Shipping state
Shipping zip code
Shipping country (ie. US)
Shipping email address
*These fields are required by default. Level II fields are required for Level II processing. Recommended fields help
provide additional address and cardholder verification. Please Note, Certain banks may require some optional fields.
**You can pass only Credit Card or E-Check transaction variables in a request – not both in the same request.
Capture
Variable Name
type
username
password
transactionid
amount
Required
Required
Required
Required
Required
Required
tracking_number
shipping_carrier
orderid
Optional
Optional
Optional
Format
capture
x.xx
ups/fedex/dhl/usps
Description
capture = Transaction Capture
Username assigned to merchant account
Password for the specified username
Original Payment Gateway transaction id
Total amount to be settled (i.e. 10.00)
This amount must be equal to or less than the
original authorized amount.
Shipping Tracking Number
Shipping Carrier
Order Id
Void
Variable Name
type
username
password
transactionid
Required
Required
Required
Required
Required
Format
void
Description
void = Cancel unsettled Transaction
Username assigned to merchant account
Password for the specified username
Original Payment Gateway transaction id
Required
Required
Required
Required
Required
Optional
Format
refund
Description
refund = Refund Transaction
Username assigned to merchant account
Password for the specified username
Original Payment Gateway transaction id
Total amount to be refunded (i.e. 10.00)
This amount may be equal to or less than the
settled amount.
Required
Required
Required
Format
update
Refund
Variable Name
type
username
password
transactionid
amount
x.xx
Update
Variable Name
type
username
Direct Post API
Copyright 2001-2007
Description
update = Update an un-captured Transaction
Username assigned to merchant account
All Rights Reserved.
Page | 5
password
transactionid
tracking_number
shipping_carrier
orderid
Required
Required
Optional
Optional
Optional
ups/fedex/dhl/usps
Password for the specified username
Original Payment Gateway transaction id
Shipping Tracking Number
Shipping Carrier
Order Id
Transaction Response Variables
Standard Response
Variable Name
response
Format
1/2/3
responsetext
authcode
transactionid
avsresponse
cvvresponse
orderid
response_code
C
C
C
Description
1 = Transaction Approved
2 = Transaction Declined
3 = Error in transaction data or system error
Textual response
Transaction authorization code
Payment Gateway transaction id
AVS Response Code (See Appendix 1)
CVV Response Code (See Appendix 2)
The original order id passed in the transaction request.
Numeric mapping of processor responses (See Appendix 3)
Retail Data
Passing Unencrypted Retail Magnetic Stripe Data
The payment gateway supports passing of magnetic strip data collected
from a card reader.
Variable Name
track_1
track_2
track_3
Format
raw
raw
raw
Description
Raw Magnetic Stripe Data
Raw Magnetic Stripe Data
Raw Magnetic Stripe Data
Passing MagTek Magensa encrypted Magnetic Stripe Data
The payment gateway supports passing MagTek’s Magensa hardware
based encryption collected from supported card readers.
Variable Name
magnesafe_track_1
magnesafe_track_2
magnesafe_magneprint
magnesafe_ksn
raw
raw
raw
raw
Format
Description
Raw MagTek Magensa Data
Raw MagTek Magensa Data
Raw MagTek Magensa Data
Raw MagTek Magensa Data
Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 6
magnesafe_magneprint_status
raw
Raw MagTek Magensa Data
Testing Information
Transaction Testing Account
Transactions can be tested using one of two methods. First, transactions
can be submitted to any merchant account that is in test mode. Keep in
mind that if an account is in test mode, all valid credit cards will be
approved but no charges will actually be processed.
The Payment Gateway demo account can also be used for testing at any
time. Please use the following username and password for testing with
this account:
Username:
Password:
demo
password
Transaction POST URL
All transactions should be submitted to the following URL:
https://secure.networkmerchants.com/api/transact.php
This URL is the same for both Live and Test Mode environments.
Test Transaction Information
Test transactions can be submitted with the following information:
Visa
MasterCard
DiscoverCard
Direct Post API
Copyright 2001-2007
4111111111111111
5431111111111111
6011601160116611
All Rights Reserved.
Page | 7
341111111111111
10/10
> 1.00
American Express
Credit Card Expiration:
Amount
Triggering Errors in Test Mode
9
9
9
9
To cause a declined message, pass an amount less than 1.00.
To trigger a fatal error message, pass an invalid card number.
To simulate an AVS Match, pass 888 in the address1 field, 77777 for zip.
To simulate a CVV Match, pass 999 in the cvv field.
Examples
Direct Post Format
Data posted by merchant’s web site to Payment Gateway
username=demo&password=password&type=sale&ccnumber=4111111111
111111&ccexp=0711&cvv=999&amount=10.00
Response data returned to merchant’s web site in HTML body
response=1&responsetext=SUCCESS&authcode=123456&transactionid=2
81719471&avsresponse=&cvvresponse=M&orderid=&type=sale&response_code=100
Changelog
June 2007
January 2007
July 2006
April 2006
February 2006
Direct Post API
Documented product_sku_x Variable
Documented processor_id Variable
Added Transaction Type Update
Added Response Code Appendix
Documented Browser Redirect Capability
Copyright 2001-2007
All Rights Reserved.
Page | 8
Appendix 1 – AVS Response Codes
X
Y
D
M
A
B
W
Z
P
L
N
C
U
G
I
R
E
S
0
O
B
Exact match, 9-character numeric ZIP
Exact match, 5-character numeric ZIP
“
“
Address match only
“
9-character numeric ZIP match only
5-character Zip match only
“
“
No address or ZIP match
“
Address unavailable
Non-U.S. Issuer does not participate
“
Issuer system unavailable
Not a mail/phone order
Service not supported
AVS Not Available
“
“
Appendix 2 – CVV Response Codes
M
N
P
S
U
Direct Post API
CVV2/CVC2 Match
CVV2/CVC2 No Match
Not Processed
Merchant has indicated that CVV2/CVC2 is not present
on card
Issuer is not certified and/or has not provided Visa
encryption keys
Copyright 2001-2007
All Rights Reserved.
Page | 9
Appendix 3 – response_code Lookup Table
Direct Post API
Copyright 2001-2007
All Rights Reserved.
Page | 10
">
