Send a Simple Transaction to the Server

When using the Payflow SDK, you send transactions to the Gateway server in name-value pair format. Typically, a simple transaction includes connection parameters, user parameters, and transaction data parameters.

About Name-Value Pairs

Name-value pair (NVP) is the format you use to specify the parameter information you send in a transaction request to the Payflow server. A name-value pair consists of the parameter name and its value. The equal sign (=) is a special character that associates the name and its value:

PARAMNAME=value

Typically, you send several name-value pairs as a parameter string to the server. The ampersand (&) is a special character that separates each name-value pair in the parameter string:

PARAM1NAME=value&PARAM2NAME=value&PARAM3NAME=value

Follow the special character and syntax guidelines when creating name-value pairs.

Use Special Characters In Values

Because the ampersand (&) and equal sign (=) characters have special meanings, they are invalid in a name-value pair value.

The following are invalid:

COMPANYNAME=Ruff & Johnson

COMMENT1=Level=5

To include special characters in the value portion of a name-value pair, use a length tag. The length tag specifies the exact number of characters and spaces that appear in the value. The following are valid.

COMPANYNAME[14]=Ruff & Johnson

COMMENT1[7]=Level=5

Note: Do not use quotation marks (") even if you use a length tag.

Name-Value Parameter Syntax Guidelines

Follow these guidelines when creating name-value pair (NVP) parameter strings:

  • Do not use spaces in values.
  • Do not place quotation marks within the body of the NVP parameter string.
  • Separate all NVPs using an ampersand (&).
  • Set the VERBOSITY transaction parameter to HIGH to have the response return detailed information. Act upon the returned values that you need for the transaction.
  • If you duplicate a parameter in your NVP string, the last item will always be the one used and the others will be discarded.

Do Not URL Encode Name-Value Parameter Data

Do not URL encode your NVP data because it can cause problems with authentication and reporting.

This example is incorrect:

TRXTYPE%3DS%26TENDER%3DC%26USER%3DMerchantUserID%26PWD%3DPwd4Gateway%26PARTNER%3DPayPal%26ACCT%3D5105105105105100%26EXPDATE%3D1215%26AMT%3D23.45%26COMMENT1%3DAirport+Shuttle%26BILLTOFIRSTNAME%3DJamie%26BILLTOLASTNAME%3DMiller%26BILLTOSTREET%3D123+Main+St.%26BILLTOCITY%3DSan+Jose%26BILLTOSTATE%3DCA%26BILLTOZIP%3D951311234%26BILLTOCOUNTRY%3DUS
%26CVV2%3D123%26CUSTIP%3D0.0.0.0

This example is correct:

TRXTYPE=S&TENDER=C&VENDOR=MerchantLoginID&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=MerchantPartner&ACCT=5105105105105100&EXPDATE=1215&AMT=23.45
&COMMENT1=Airport Shuttle&BILLTOFIRSTNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.&BILLTOCITY=San Jose
&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=840&CVV2=123&CUSTIP=0.0.0.0

Prohibited Characters

Due to issues with Cross-site scripting (XSS) a type of security vulnerability typically found in web applications the following characters; URL encoded or not, are prohibited. Use of these characters will prevent the hosted checkout page; including the iframe page, from displaying.

  • = equal sign
  • ' apostrophe
  • - dash
  • ; semi-colon
  • < greater than
  • > less than
  • \n new line

Also, the following HTML tags are invalid and should be not used in any fields:

script|applet|embed|form|iframe|img|link|object|body|meta|a|style|font|xss|h1|h2|h3|h4|h5|b|p|canvas|i|input|select|blink|br|button|video

Payflow Connection Parameters

The Payflow SDK passes connection parameters to define the connection to the Payflow server.

Pass the connection parameters in the format and syntax required by the Payflow SDK and programming language that you are using. See your integration documentation for details.

Parameter Description
HOSTADDRESS (Required) Gateway server name.
HOSTPORT (Required) Use port 443.
TIMEOUT (Required) Time-out period for the transaction. PayPal recommends a minimum time-out value of 30 seconds. The client begins tracking from the time that it sends the transaction request to the server.
PROXYADDRESS (Optional) Proxy server address. Use the PROXY parameters for servers behind a firewall. Your network administrator can provide the values.
PROXYPORT (Optional) Proxy server port.
PROXYLOGON (Optional) Proxy server log-on ID.
PROXYPASSWORD (Optional) Proxy server log-on password.

In addition to the connection parameters in the table, you must pass the NVP parameters that specify the payment information for the transaction.

User Parameter Data

All Gateway transactions require the user parameters described as follows.

User parameters

Parameter Description
USER (Required) If you set up one or more additional users on the account, this value is the ID of the user authorized to process transactions. If, however, you have not set up additional users on the account, USER has the same value as VENDOR.
Limitations: 64 alphanumeric, case-sensitive characters
VENDOR (Required) Your merchant login ID that you created when you registered for the account.
Limitations: 64 alphanumeric, case-sensitive characters
PARTNER (Required) The ID provided to you by the authorized PayPal Reseller who registered you for the Gateway gateway. If you purchased your account directly from PayPal, use PayPal.
Limitations: 64 alphanumeric, case-sensitive characters
PWD (Required) The password that you defined while registering for the account.
Limitations: 6 to 32 alphanumeric, case-sensitive characters

Sale Transaction Example

In addition to the required connection and user parameters, each transaction type may require other parameters and can include a number of optional parameters.

To complete a sale transaction involving a credit card, for example, pass the following parameters:

  • TRXTYPE - The type of the transaction, such as S for Sale
  • TENDER - The method of payment, such as C for credit card
  • ACCT - The buyer's credit card number
  • AMT - The amount of the sale, including two decimal places and without a comma separator
  • EXPDATE - The expiration date of the credit card

Typical Sale Transaction

The following is a typical name-value pair string for a sale transaction.

TRXTYPE=S&TENDER=C&USER=MerchantUserID&PWD=Pwd4Gateway&PARTNER=PayPal&ACCT=5105105105105100&EXPDATE=1215
&AMT=23.45&COMMENT1=Airport Shuttle&BILLTOFIRSTNAME=Jamie&BILLTOLASTNAME=Miller&BILLTOSTREET=123 Main St.
&BILLTOCITY=San Jose&BILLTOSTATE=CA&BILLTOZIP=951311234&BILLTOCOUNTRY=840&CVV2=123&CUSTIP=0.0.0.0&VERBOSITY=HIGH

Besides the required sale transaction parameters, the string includes other Payflow parameters typically included in a sale transaction.

When the transaction completes, the Gateway server returns a response string made up of name-value pair response parameters. If the transaction is successful, the Payflow Gateway server returns a RESULT parameter with the value 0. The value of the PNREF parameter is the transaction ID, which helps to identify the transaction in future requests; the RESPMSG parameter is a string indicating whether the transaction was approved.

The following is an example response:

RESULT=0&PNREF=VXYZ01234567&RESPMSG=APPROVED&AVSADDR=Y&AVSZIP=N&IAVS=Y&CVV2MATCH=Y

Format Payflow Gateway Transactions

For details on how to format a Payflow transaction, see the examples and the supporting documentation provided with your SDK or see Submit Credit Card Transactions.