Payflow / Integration Guide / Secure Token

Payflow Gateway Secure Token


Secure Token

This section describes the secure token.

Important: Use only the Payflow parameters described in this guide with the Secure Token. If you are using the legacy Payflow Link HTML input tag integration, refer to the Payflow Link User's Guide for information on legacy Payflow Link features supported by your integration.

About the Secure Token

Use a secure token to send non-credit card transaction data to the Gateway server for safer storage. The secure token prevents anyone from intercepting or manipulating the data. You must use a secure token if you use hosted checkout pages. The token is good for a one-time transaction and is valid for 30 minutes.

Note: PayPal Payments Pro and Payflow Pro merchants who do not use a secure token must host their own payment pages. When hosting your own pages, you are responsible for meeting PCI requirements by handling data securely. PayPal Payments Advanced and Payflow Link merchants must use a secure token with hosted checkout pages.

To obtain a secure token, pass a unique, 36-character secure token ID and set CREATESECURETOKEN=Y in a request to the Gateway server. The Gateway server associates your ID with a secure token and returns the token as a string of up to 32 alphanumeric characters.

To pass the transaction data to the hosted checkout page, you pass the secure token and secure token ID in an HTTP form post. The token and ID trigger the Gateway server to retrieve your data and display it for customer approval.

Note: You cannot modify the data sent with a secure token, with one exception. You can configure PayPal Manager to allow you to modify billing and shipping information.

Integrate the Secure Token With the Hosted Checkout Pages

To create a secure token, pass all parameters that you need to process the transaction except for payment details parameters such as the credit card number, expiration date, and check number. For details on transaction parameters, see Submit Credit Card Transactions. In addition, pass the following Payflow parameters to create the secure token.

Note: The secure token is valid for 30 minutes, and you can only use it one time. If you attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, "Secure Token Expired." If you attempt to reuse the token, you receive an error.

Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

Set CREATESECURETOKEN to the value Y to request that Payflow gateway return a token.

CREATESECURETOKEN=Y

Secure Token Example

The following is an example of a request parameter string that creates a secure token.

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=23.45&CURRENCY=USD&INVNUM=INV12345 &PONUM=PO9876&CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

The Gateway server returns SECURETOKEN and SECURETOKENID in the response. A tag follows the SECURETOKEN to indicate the length of the token value returned.

RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==
&SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

Integrate the Secure Token Without the Hosted Checkout Pages - Transparent Redirect

To use your own checkout pages while complying with PCI guidelines (sending the customer's sensitive data directly to the Gateway server), pass all parameters that you need to process the transaction except for sensitive payment details such as the credit card number, expiration date, and check number. For details on sending transactions, see Submit Credit Card Transactions.

In addition, pass the following 3 Payflow parameters in your request. The first 2 parameters obtain a secure token. The third parameter implements Transparent Redirect, which suppresses hosted pages.

Note: The secure token is valid for 30 minutes, and you can only use it one time. If you attempt to use the token after the time limit has expired, your transaction will fail with Result value 7, "Secure Token Expired." If you attempt to reuse the token, you receive an error.

Set SECURETOKENID to a unique alphanumeric value up to 36 characters in length.

SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

Set CREATESECURETOKEN to the value Y to request that the Gateway server return a token.

CREATESECURETOKEN=Y

Set SILENTTRAN to the value TRUE to suppress the display of hosted pages.

SILENTTRAN=TRUE

Transparent Redirect Example

The following is an example of an authorization parameter string that suppresses hosted pages.

TRXTYPE=A&BILLTOSTREET=123 Main St.&BILLTOZIP=95131&AMT=24.35&INVNUM=INV12345&PONUM=PO12345&CURRENCY=USD &CREATESECURETOKEN=Y&SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5&SILENTTRAN=TRUE

The Gateway server returns a SECURETOKEN and SECURETOKENID in the response. A tag follows the SECURETOKEN to indicate the length of the token value returned.

RESULT=0&RESPMSG=Approved&SECURETOKEN[25]=Fj+1AFUWft0+I0CUFOKh5WA==
&SECURETOKENID=9a9ea8208de1413abc3d60c86cb1f4c5

When the customer enters their sensitive data into the credit card fields on your website and clicks Submit, the browser posts the data to the Gateway server rather than to your website.

Note: It is highly recommended that you add scripting to ensure the browser posts the sensitive data directly to the PayPal Gateway server rather than to your website.

Secure Token Errors

A successful Payflow transaction will return RESULT=0 in the response. If your secure token transaction is unsuccessful, you can pass the token 2 more times to Payflow before the token expires.

A Payflow secure token will expire:

  • If the same secure token is passed to Payflow a total of 3 times.
  • 30 minutes after the secure token was generated.
  • When the token is used in a successful transaction.

If you receive one of the following error codes in the RESULT response parameter, then your secure token has expired.

  • 160. Secure Token already been used. Indicates that the secure token has expired due to either a successful transaction or the token has been used three times while trying to successfully process a transaction. You must generate a new secure token.
  • 161. Transaction using secure token is already in progress. This could occur if a customer hits the submit button two or more times before the transaction completed.
  • 162. Secure Token Expired. The time limit of 30 minutes has expired and the token can no longer be used.

If you see a different error code in the RESULT parameter, refer to the RESULT Values and RESPMSG Text section for more information.

Post to the Hosted Checkout Page

To display the transaction information to the Gateway hosted checkout page, you perform an HTTP form post.

Direct the HTTP post to the Gateway applications server at the following URL.

https://payflowlink.paypal.com

Send the following parameter data:

  • SECURETOKEN returned in the transaction response
  • SECURETOKENID

HTTP Form Post Examples

The following is an example request string that displays the transaction information to the hosted checkout page.

<html> <head> <title>PageTitle</title> </head> <body> <form method="post" action="https://payflowlink.paypal.com"> <input type=hidden value="Fj+1AFUWft0+I0CUFOKh5WA==" name=SECURETOKEN/> <input type=hidden value="9a9ea8208de1413abc3d60c86cb1f4c5" name=SECURETOKENID/> </form> </body> </html>

For more information on the Payflow parameters used to pass information to the Gateway hosted checkout pages, see Using a Secure Token to Pass Hosted Pages Customization Parameters.

The following example uses Payflow name-value pairs to pass values in a form post to the hosted checkout pages. For details on the name-value pair strings used in this example, see Send a Simple Transaction to the Server.

<html> <head> <title>PageTitle</title> </head> <body> <form method="post" action="https://payflowlink.paypal.com"> <input type="text" name="SECURETOKEN" value="FvwEnHTYRNUSVsZRlhFpudA=="/> <input type="text" name="SECURETOKENID" value="9a9ea8208de1413abc3d60c86cb1f4c5"/> <input type="hidden" name="PARMLIST" value="INVNUM[8]=INV123&AMT[5]=25.50&CURRENCY[3]=USD"/> <input type="submit"/> </form> </body> </html>
ReferencePayPal.comPrivacyCookiesSupportLegalContact