Implement iDEAL on Stripe v2

Overview

iDEAL is the leading online bank transfer payment method in the Netherlands. iDEAL works with all the major Dutch banks. Zuora's Stripe v2 gateway integration supports iDEAL. You can implement a hosted payment page through Payment Pages 2.0 to support iDEAL one-time and recurring payment flows. The created iDEAL payment methods are automatically tokenized. The creation of iDEAL payment methods through Zuora UI or API operations is not supported.

Step 1. Prepare for the integration

Before implementing the iDEAL payment method on Stripe, ensure that all prerequisites outlined in the following sections are fulfilled.

Step 2. Create and configure an iDEAL payment page 

Complete the following steps to create and configure an iDEAL payment page:

1. In Zuora UI, 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 iDEAL.
4. Click Create New Hosted Page.
5. In the Basic Information section, specify the following fields:

   Field	Description
   Page Name	Enter a name for your hosted payment page. This name is used to identify your payment page in Zuora. It is different from the title displayed on the payment page. You can specify the title in the Page Title field in the Page Configuration section.
   Hosted Domain	Enter the domain address from which your payment page is served. This domain also hosts your callback page. The value must be in the format: https://www.domain.com. Zuora validates this field for you. If the validation fails, an error message is displayed on the payment page. Note that the Overlay Hosted Page mode does not support the hosted domain validation. If you want your hosted payment pages and callback pages to reside in the subdomain of the hosted domain, enable the tenant-level Allow Subdomain Callback for Hosted Pages setting.
   Callback Path	Enter 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. The file extension, such as .jsp or .php, is not required. However, the callback path must begin with a forward slash character ( / ). The Callback Path is only required for the advanced implementation option, which uses the inline style form with an external submit button. This setting is ignored for the basic setup, which uses 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 Default Payment Gateway field of the Payment Gateway section, click and select a Stripe v2 instance. Note that Zuora does not validate this setting. You can override this default gateway in your request by specifying a gateway through the paymentGateway client parameter.
8. In the Page Configuration section, complete the field configuration.

   Field	Description
   Page Title	Enter a title for the hosted payment page. Select Display to display the Page Title on this payment page.
   Page Description	Enter the description of the payment page. Select Display to display the Page Description on this payment page.
   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 information about the submitEnabled parameter that 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. In the Error Message field, use #fieldName to include the missing field name in the error message. For example, "Please enter a valid #fieldName to continue."
   Confirmation Dialog	Select Enable Confirmation Dialog to add a step to display a confirmation dialog in the Payment Page workflow. When this step is enabled, your customers get a chance to confirm the information they entered before submitting the payment method. After you select Enable Confirmation Dialog, the template editor appears. Customize the Confirmation Dialog by typing in the desired information in the template editor, such as the page heading, your merchant name, etc. If you want to customize the CSS style of the Confirmation Dialog, add the customized CSS to the CSS field.  The default behavior of the Cancel button is closing the confirmation dialog and allowing the end user to edit the account information again. If you want to customize the logic, you can use the onCancelMandatePage event handler in your client code. Do not select the Retrieve Mandate PDF field to avoid errors. This setting only works for bank transfer type of hosted payment pages on GoCardless.
   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.

9. Click Generate and Save Page.

Subsequently, you can preview the form. 

Step 3. Request a signature for the Payment Page

Follow the instructions in Request a signature for the Payment Page from Zuora. Because the Client-side HPM Parameter Validation feature is enabled, Zuora will validate the additional fields in the request by comparing them with the values specified in the digital signature.

Here are two request examples for the Generate RSA signature REST API operation.

{
    "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do",
    "method":"POST",
    "pageId":"test808145b3bf9d0145b3c6812b0008",
    "paymentGateway":"Stripe",
    "authroizationAmount":"100",
    "currency":"EUR",
    "accountId":"test808145b3bf9d0145b3c6812b0008"
}

{
    "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do",
    "method":"POST",
    "pageId":"test808145b3bf9d0145b3c6812b0008",
    "paymentGateway":"Stripe",
    "accountId":"test808145b3bf9d0145b3c6812b0008"
}

Step 4. Set up your client code

Follow the instructions in Integrate Payment Pages 2.0. When rendering the Payment Page form, specify the following required parameters in the Z.render or Z.renderWithErrorHandler function. For other optional parameters, see Client Parameters for Payment Pages 2.0.

Here is an example for authorization amount processing:

var params = {
    doPayment:"true",
    storePaymentMethod:"true",
    paymentDescription:"First Payment",
    field_accountId:"testc0f87596f2f301759c29443622fa",
    authorizationAmount:"99",
    field_currency:"EUR"
};

Here is an example for invoice processing:

var params = {
    doPayment:"true",
    storePaymentMethod:"true",
    paymentDescription:"First Payment",
    field_accountId:"testc0f87596f2f301759c29443622fa",
    documents:"[{\"type\": \"invoice\", \"ref\": \"INV0000001\"}, {\"type\": \"invoice\", \"ref\": \"INV0000002\"}]"
};

Step 5. Implement the callback response

See Advanced Integration of Payment Pages 2.0 for more information.

Related information

• Overview of Stripe payment gateway integration
• Set up and configure a Stripe payment gateway instance