Skip to main content

Configure Credit Card Reference Payment Pages 2.0 for Stripe v2


Configure Credit Card Reference Payment Pages 2.0 for Stripe v2

This article describes how to configure Credit Card Reference Payment Pages 2.0 for the Stripe v2 gateway. For details about compatibility with the browsers, see Browser Support Policy.


  • Submit a request at Zuora Global Support to enable the support for Credit Card (CC) Reference Transaction payment methods in Payment Pages 2.0.
  • Activate CC Reference Transaction payment methods for your tenant by navigating to Settings > Payments > Payment Method, clicking Edit, and then selecting CC Reference Transaction.


Before you start any integration work, set up the Payment Page form in Zuora.

  1. In Zuora, navigate to Settings > Payments, and click Setup Payment Page and Payment Link.
  2. On the Payment Pages tab page, configure the tenant-level settings for the hosted payment page.
  3. In the Type dropdown list, select Credit Card Reference. See Payment Methods to learn more about the payment type.
  4. Click create new hosted page.
  5. In the Basic Information area, enter the following information:
    • Page Name: Type a name for your Payment Page form. This name is used to identify your form in Zuora. It is different from the title displayed on the form. You specify the form title in the Page Title field in the Page Configuration section.
    • Hosted Domain: Type the domain address from which your Payment Page will be served. This is also the domain where your callback page resides. The value should be in the format: Zuora validates this field for you. You will see an error message displayed on HPM iframe if the validation fails.

      To allow your hosted payment pages and callback pages to reside in the subdomain of the hosted domain, enable the Allow Subdomain Callback for Hosted Pages setting. See Configure Payment Pages 2.0 for details.

      Note that the Overlay Hosted Page mode does not support the Hosted Domain validation.

    • Callback Path: Type the path on which the callback page file resides. Zuora appends this to the Hosted Domain entry to create the full URL to which the callback is sent. Specify a value in the format: /app/callback_file.jsp. You are not required to include a file extension, for example, .jsp or .php. However, the callback path must begin with a forward slash character ( / ).
      The Callback Path is only required if you are using the advanced implementation option, using the inline style form with an external submit button. The Callback Path setting is ignored when you implement the basic setup, i.e., using the overlay form or the inline form with the submit button inside.
  6. In the Security Information area, configure the page-level security settings. For detailed information about each option, see Security Measures for Payment Pages 2.0.  
  7. In the Payment Gateway area, select and click a Stripe v2 gateway to use. You can override this default gateway in your request by specifying a gateway through the paymentGateway client parameter.
  8. In the Page Configuration area, enter the following information.
    • Page Title: Type a title for the Payment Page form. Select Display to display the Page Tile on this Payment Page form.
    • Page Description: Type a description for the form. Select Display to display the Page Description on this Payment Page form.
    • For each field in the Page Fields section:
      • Label Name: Enter the display label to be shown on this Payment Page.
      • Display: Select the checkbox to display the field on the Payment Page.
      • Required: Select the checkbox to make the field a required field.
      • If you want to change the default display order of the input fields within a section, enter the number representing the display order of the field within the section. 
    • Submit Button: Type the label to display on the submit button. This label is applied only if the button is on the Payment Page form. See Client Parameters for Payment Pages 2.0 for the submitEnabled parameter, which controls the placement of the submit button.
    • Client-Side Validation: Select Enable client-side validation to check the required fields for values.
      • If the client-side validation is enabled, you can specify a custom error message for missing required fields in the Error Message field. 
      • Use the #fieldName variable in the error message to include the missing field name. For example, "Please enter a valid #fieldName to continue." 
    • CSS: Enter the custom CSS code for your page. You can review the CSS id and class names by using View Source or Inspect Element in Firefox or Chrome on the preview page of this Payment Pages form. For example, you can customize the style and format of the field label and error message, as well as the error message texts. However, implementing customized JavaScript is not allowed for security reasons.

      Design Payment Pages CSS provides a CSS pack that you can download and use to design the look and formatting of your Payment Pages 2.0 form.

      Ensure that you enter the valid CSS codes in this field. An error will occur if you include HTML tags or other invalid characters.

    • Credit Card Type DetectionSelect Enable automatic credit card type detection to identify the credit card type based on user's credit card number entry. Supported credit card types are AMEX, Visa, Discover, and MasterCard. See Automatic Detection of Credit Card Type for detail.
  9. Click generate and save page.

The Preview Payment Pages 2.0 page shows the page as it will be displayed on your website. 

Response parameters returned after submission

The following table describes the parameters in the response returned after submission of the hosted payment page. The number of returned parameters varies depending on whether 3DS2 is enabled and the client parameters passed through the submission request.

Parameter Description Example
refId The ID of the payment method created through HPM. 4028818a82391c7201824291e6cb022d

The overall result of the payment method validation. The possible values include:

  • True
  • False
AuthorizeResult The authorization result of the payment method validation. The possible values include:
  • Pending
  • Approved
  • NotApproved
  • Voided
  • Captured
  • NotAttempted
  • Unknown
ThreeDSResult The status of 3DS2 authentication. The possible values include:
  • Pending
  • ChallengeRequired
  • Frictionless
  • NotEnrolled
  • DeviceFingerprint
  • EnrollCheckAttempt
  • EnrollCheckFailed
  • AuthenticationPass
  • AuthenticationFail
  • Error
zThreeDs2TxId The transaction ID of the payment method validation. When submitting 3DS2 related L3 tickets, provide this field to Zuora Gobal Support to investigate the issues. 4028818a82391c72018242914dd2021e
signature A client parameter for validating client-side HPM parameters. See Client parameters for Payment Pages 2.0 and Validate client-side HPM parameters for details. VpCAFL2hHC2irxbhWYGLJmdBigjARsCStwHZiQ78z5LyVuBCFr2lkie0db/7E8n38MXaq12Ng5As5Qj+9Nhz6RBsSEWLod7c7hvwNI28OcgBZtcV/wscbWU69EP/+/XrQnF3ZUbHbqmcmhE8C/zNnc2zvHckfArroDW2HxxmATfMJS0xKUm5TrHi4tiILZVMYY1KIUqQTyuXV6uRWYzkqMkFkZDNCxSxf0XwzuBI/VOgTCmFZb0c3+bk/q6+7d/azFCrrg8C3dquCNJRfUeaBou+SLUa4TW3hV4rGd2zpvSrD/425x4qFNGV6JQ7wvIleIdrXU4qbh9nCmYoApMODA==
token A client parameter for validating client-side HPM parameters. See Client parameters for Payment Pages 2.0 and Validate client-side HPM parameters for details. E2BJEle7YrAlw93SjkaKthTmzMvXF341
responseFrom Please ignore this response field.  
nextStep Please ignore this response field.  
redirectUrl Please ignore this response field.