Payflow Header Parameters

Last updated: October 12th 2021, @ 6:58:00 pm

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:

RESULT=0&RESPMSG=Approved&TOKEN=EC-868676987J8393917&CORRELATIONID=5f817d830101

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:

RESULT=0&RESPMSG=Approved&TOKEN[20]=EC-97J718043X120051H&TIMESTAMP[20]=2012-10-11T15:19:37Z
&CORRELATIONID[13]=274f8d4493dbe&ACK[7]=Success&VERSION[4]=92.0&BUILD[7]=3893058

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

Header Name Description

Header Name	Description
`X-VPS-REQUEST-ID`	(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. `X-VPS-REQUEST-ID` is made up of 1 to 32 printable characters. You must provide the `X-VPS-REQUEST-ID` value in the transaction request. The server uses the `X-VPS-REQUEST-ID` to check for duplicate transaction requests. When a transaction request is received, the server checks the requests table to see if the `X-VPS-REQUEST-ID` has been used before by this merchant. If the `X-VPS-REQUEST-ID` has been used before, the server views it as a retry transaction and the transaction is treated as a duplicate. The response to the original transaction request is returned and "`DUPLICATE=1`" is appended to the response indicating that this transaction is a duplicate. In Manager, you will see these `DUPLICATE` transactions with a `TENDER` type of "`N`". Important: If you send in a NEW transaction with a previously used `X-VPS-REQUEST-ID`, the server ignores the new data and returns the response to the original transaction associated with that `X-VPS-REQUEST-ID`. It is VERY IMPORTANT that you check for `DUPLICATE=1` and if you receive it and the transaction is not a re-attempt of the original request of a failed transaction, you must change the Request ID. If the `X-VPS-REQUEST-ID` has not been used before, the server stores the `X-VPS-REQUEST-ID` to ensure that the `X-VPS-REQUEST-ID` is not reused and then runs the associated transactions. Duplicate checking is designed for short-term retries (a few minutes to a few hours after the original transaction). The `X-VPS-REQUEST-ID` is stored for a minimum of 7 to 8 days; however, retries should not be sent so long after the original transaction. Note: Any transaction with an ID older than 8 days will be treated as a new transaction. The `X-VPS-REQUEST-ID` check is only available if the database is up and available. If for some reason the database is down, transactions (authorizations and sales) will continue to be processed as normal; however, `DUPLICATE=-1` (negative one) will be returned to alert you that the database is down and there is no duplicate check being performed. 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 `DUPLICATE=1`
`X-VPS-CLIENT-TIMEOUT`	(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 `X-VPS-CLIENT-TIMEOUT`. The default value is 45.

X-VPS-REQUEST-ID

(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.
X-VPS-REQUEST-ID is made up of 1 to 32 printable characters. You must provide the X-VPS-REQUEST-ID value in the transaction request. The server uses the X-VPS-REQUEST-ID to check for duplicate transaction requests. When a transaction request is received, the server checks the requests table to see if the X-VPS-REQUEST-ID has been used before by this merchant.
If the X-VPS-REQUEST-ID has been used before, the server views it as a retry transaction and the transaction is treated as a duplicate. The response to the original transaction request is returned and "DUPLICATE=1" is appended to the response indicating that this transaction is a duplicate. In Manager, you will see these DUPLICATE transactions with a TENDER type of "N".

Important: If you send in a NEW transaction with a previously used X-VPS-REQUEST-ID, the server ignores the new data and returns the response to the original transaction associated with that X-VPS-REQUEST-ID.

It is VERY IMPORTANT that you check for DUPLICATE=1 and if you receive it and the transaction is not a re-attempt of the original request of a failed transaction, you must change the Request ID.
If the X-VPS-REQUEST-ID has not been used before, the server stores the X-VPS-REQUEST-ID to ensure that the X-VPS-REQUEST-ID is not reused and then runs the associated transactions. Duplicate checking is designed for short-term retries (a few minutes to a few hours after the original transaction). The X-VPS-REQUEST-ID is stored for a minimum of 7 to 8 days; however, retries should not be sent so long after the original transaction.

Note: Any transaction with an ID older than 8 days will be treated as a new transaction.

The X-VPS-REQUEST-ID check is only available if the database is up and available. If for some reason the database is down, transactions (authorizations and sales) will continue to be processed as normal; however, DUPLICATE=-1 (negative one) will be returned to alert you that the database is down and there is no duplicate check being performed.

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 DUPLICATE=1

X-VPS-CLIENT-TIMEOUT (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 X-VPS-CLIENT-TIMEOUT. The default value is 45.

Header Name	Description
Connection	State of the connection. The server returns the value `close` to close the connection after the response is sent.
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: - Production: `payflowpro.paypal.com` - Pilot: `pilot-payflowpro.paypal.com` Note: Do not include `https://` in the host URL as this would cause an HTTP 400 error due to malformed host field.

Transaction Message

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): https://payflowpro.paypal.com
Pilot (Test): https://pilot-payflowpro.paypal.com

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.

Transaction Request

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[1]=S&ACCT[16]=5105105105105100&EXPDATE[4]=0109&TENDER[1]=C&INVNUM[8]=INV12345&AMT[5]=25.12
&PONUM[7]=PO12345&STREET[23]=123 Main St.&ZIP[5]=12345&USER[6]=jsmith&VENDOR[6]=jsmith&PARTNER[6]=PayPal
&PWD[8]=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.

Transaction Response

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

Integrator-Provided Data

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

Header Name	Description
`X-VPS-VIT-INTEGRATION-PRODUCT`	Identifies the integration product that calls the PayPal server. Format: String Examples: iPayment, ColdFusion, MIVA, shopping cart Default Value: Blank
`X-VPS-VIT-INTEGRATION-VERSION`	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
`X-VPS-VIT-OS-NAME`	Name of operating system on which the client is running. Format: String Examples: Linux, SunOS, Windows 2000, Windows NT, Windows XP, Mac OS X, Free BSD Default Value: Blank
`X-VPS-VIT-OS-VERSION`	Version of operating system on which the client is running. Format: String XXX.X Example: 2.4 Default Value: Blank
`X-VPS-VIT-RUNTIME-VERSION`	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