Payflow Header Parameters

Last updated: Sept 18th, 7:45pm

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

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:

    1RESULT=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:

      1RESULT=0&RESPMSG=Approved&TOKEN[20]=EC-97J718043X120051H&TIMESTAMP[20]=2012-10-11T15:19:37Z
      2&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.

      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
      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".
      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.
      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.
      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

      Transaction Request

      The transaction request consists of a transaction request header and body.

      Name-Value Pair Transaction Request Header
        1Content-Type: text/name value
        2Content-Length: 233
        3Connection: close
        4Host: payflowpro.paypal.com
        5X-VPS-REQUEST-ID: [See Required Payflow Headers]
        6X-VPS-CLIENT-TIMEOUT: 45
        7X-VPS-VIT-[See Integrator-Provided Data]
        8X-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.

          1TRXTYPE[1]=S&ACCT[16]=5105105105105100&EXPDATE[4]=0109&TENDER[1]=C&INVNUM[8]=INV12345&AMT[5]=25.12
          2&PONUM[7]=PO12345&STREET[23]=123 Main St.&ZIP[5]=12345&USER[6]=jsmith&VENDOR[6]=jsmith&PARTNER[6]=PayPal
          3&PWD[8]=testing1

          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.

            1Connection: close
            2Server: VPS-3.028.00
            3Date: Mon, 16 May 2005 22:48:06 GMT
            4Content-Type: text/name value
            5Content-Length: 145
            6X-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.

              1RESULT=0&PNREF=V53A0A30B542&RESPMSG=Approved&AUTHCODE=882PNI&AVSADDR=X&AVSZIP=X&IAVS=X
              2&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.

              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

              We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies