Payflow Header Parameters
This section includes information on the Payflow header parameters. These header parameters can be used to bypass Payflow to send a request message directly to PayPal. They can also be used to post transactions to the Payflow servers directly without installing an SDK. This section includes:
- Sending Requests Directly to PayPal Bypassing Payflow
- Posting Transactions Directly Without the Payflow SDK
Sending Requests Directly to PayPal Bypassing Payflow
Payflow will ignore the request parameters you pass and will forward them to PayPal when you declare
PAYPAL-NVP:Y in the request header. Declaring
PAYPAL-NVP:Y in the request header is required when passing negative discount amounts to PayPal through Payflow.
Please note that passing
PAYPAL-NVP:Y in the request header changes the format of the response message you receive from Payflow. For example, if
PAYPAL-NVP:Y is NOT declared in the header, the Payflow response message is formatted as follows:
If the request header
PAYPAL-NVP:Y is declared, the response returned from Payflow includes bracketed numbers next to the names of the response parameters. These bracketed numbers are length tags that indicate the length of the values returned. The following is a response message that contains length tags:
You can also use length tags in the Payflow request message to pass the special characters of "&" and "=" in the values sent. See Using Special Characters In Values for more information.
Express Checkout for Payflow
For information on using the PayPal Express Checkout API with Payflow, see the Express Checkout for Payflow integration guide.
Posting Transactions Directly Without the Payflow SDK
The Payflow SDK is recommended for .NET and Java users - to simplify the Payflow integration.
Developers also have the option to post transactions directly to the Payflow servers using the Payflow message protocol, without the need to install an SDK. This section describes the HTTP headers that are required to post transactions directly to the Payflow servers.
The Payflow Message Protocol
What is the Payflow message protocol and what are its advantages?
The Payflow message protocol is an HTTP-compatible protocol for transactions. The HTTP-compliant implementation of this protocol has the following goals:
To enhance flexibility to developers integrating with the Payflow Service. Merchants can use the protocol in either by:
- Using a Payflow SDK such as .NET or Java that uses this protocol, or
- Integrating this protocol directly into your own client application without using an SDK.
- To increase reliability through adherence to open standards.
- To provide built-in tools to prevent duplicate transactions and authorizations.
- The Payflow message protocol provides the underlying transport for application-level transactions, using either the Payflow name-value pair or XMLPay 2.0 format. All transaction data as documented in this guide is embedded in the body of a standard HTTPS POST and POSTed to the URLs specified.
What is the disadvantage of building your own integration?
Since you are building your own integration, you will need to add your own error handling, retry logic and duplicate transaction handling within your code.
You can find examples on GitHub.
Note: If you prefer not to write your own client, you can use the .NET SDK or the Java SDK. See Payflow SDK for more information about the SDKs.
What code changes are required when migrating from a previous Payflow SDK to this service?
The Payflow HTTPS service uses the same name-value-pair parameters or XMLPay schema as found in the current SDKs. The only code change needed is the way you communicate with the Payflow servers. Instead of using an SDK to send the data, you use the methods available in your programming language of choice to send the data through HTTPS. For example, if you use PHP, you might choose to use cURL.
Payflow Message Protocol Headers
In addition to the Payflow parameters that you pass in your request, you must set the request headers described in the following table.
Required Payflow Headers
||(Required) A unique identifier for each request, whether the request is a single name-value transaction or an XMLPay 2.0 document with multiple transactions. This identifier is associated with all the transactions in that particular request.
Important: If you send in a NEW transaction with a previously usedIt is VERY IMPORTANT that you check for
Note: Any transaction with an ID older than 8 days will be treated as a new transaction.The
Note: Buyer Authentication: E-Verify Enrollment, Z-Validate Authentication transactions and PayPal Express Checkout: SetExpressCheckout and GetExpressCheckout transactions do not use duplicate suppression and will not return
||(Required) Time-out value in seconds. A transaction times out if the elapsed time between ending the original transaction request and receiving the transaction response exceeds the value of
|Connection||State of the connection. The server returns the value
|Content-Length||(Required) Size of message body.|
|Content-Type||(Required) Provide one of the following values:
- text/name value, transaction request body is in name-value pair format.
- text/xml, transaction request body is in XMLPay 2.0 format.
|Host||(Required) Provide one of the two host URLs:
The transaction message communicates the initial transaction data to the server and contains the transaction request and response.
URLs for Sending Messages
Use the following URLs for sending transactions to the Payflow servers:
- Production (Live):
- Pilot (Test):
Note Since Payflow is operating out of multiple data centers we highly suggest that all API calls are done using the host URLs above. Should you hard code the IP addresses to send transactions via the Payflow API, PayPal cannot be responsible should your transactions fail should a data center be offline due to any issues or any scheduled maintenances.
The transaction request consists of a transaction request header and body.
Name-Value Pair Transaction Request Header
Content-Type: text/name value Content-Length: 233 Connection: close Host: payflowpro.paypal.com X-VPS-REQUEST-ID: [See Required Payflow Headers] X-VPS-CLIENT-TIMEOUT: 45 X-VPS-VIT-[See Integrator-Provided Data] X-VPS-VIT-[See Integrator-Provided Data]
The following is an example of a transaction request header associated with a message in name-value format. For XMLPay, it would follow the same format except the content-type would be text/xml and the body of the request and response would contain the XML document.
Name-Value Pair Transaction Request Body
The transaction request body contains the transaction information. The following is an example transaction request body in name-value pair format.
TRXTYPE=S&ACCT=5105105105105100&EXPDATE=0109&TENDER=C&INVNUM=INV12345&AMT=25.12 &PONUM=PO12345&STREET=123 Main St.&ZIP=12345&USER=jsmith&VENDOR=jsmith&PARTNER=PayPal &PWD=testing1
Note: The bracketed numbers are length tags which allow you to use the special characters of "&" and "=" in the value sent. See Using Special Characters In Values for more information.
The Request Body should NOT be URL-encoded. Pass the data as a standard data and use the length tags if needed.
The transaction response consists of a transaction response header and body.
Name-Value Pair Transaction Response Header
The following is an example transaction response header associated with a message in name-value format.
Connection: close Server: VPS-3.028.00 Date: Mon, 16 May 2005 22:48:06 GMT Content-Type: text/name value Content-Length: 145 X-VPS-REQUEST-ID: [Same ID as sent]
Name-Value Pair Transaction Response Body
The transaction response body contains the response to the request. The following is an example response body in name-value format.
RESULT=0&PNREF=V53A0A30B542&RESPMSG=Approved&AUTHCODE=882PNI&AVSADDR=X&AVSZIP=X&IAVS=X &PREFPSMSG=No Rules Triggered&POSTFPSMSG=No Rules Triggered
These headers are extensions to the Payflow message protocol. The extension parameters describe the specific version of a client and the client's environment. Send the applicable parameters to PayPal in the transaction request headers.
Note: The parameters in this section are not required, but we highly recommend you send them.
Payflow Recommended Headers
||Identifies the integration product that calls the PayPal server.
Examples: iPayment, ColdFusion, MIVA, shopping cart
Default Value: Blank
||Version of the software as defined by the integrator/vendor. Limited to the major version and one digit of the minor version (can include alphanumeric characters, not just digits).
Format: String <Major Version>.<Minor Version>
Examples: 1.1, 4.5, 10.0, Linux2.1
Default Value: Blank
||Name of operating system on which the client is running.
Examples: Linux, SunOS, Windows 2000, Windows NT, Windows XP, Mac OS X, Free BSD
Default Value: Blank
||Version of operating system on which the client is running.
Format: String XXX.X
Default Value: Blank
||Version of runtime environment of the language in which the client is written and is running.
Format: String XXX.XE
Examples: 10.1, 2.5
Default Value: Blank