Skip to main content

Implement Payment Pages 2.0 to support one-time payment flows

Zuora

Implement Payment Pages 2.0 to support one-time payment flows

You can configure and integrate a Payment Page 2.0 to support processing one-time payments with the Stripe v2 gateway integration. Additional fields can be included to support processing either authorization amounts or invoices.

This support is only available to Stripe v2 gateway integration for now.

Before you begin

Ensure that you have enabled the following features:

Procedure

To implement Payment Pages 2.0 to process one-time payments with Stripe v2, follow the Payment Pages 2.0 implementation process and customize the configuration and client codes according to the following instructions:

  1. In Zuora, set up a Payment Page 2.0 by following instructions in step 1 in Payment Pages 2.0 implementation process and implementing the following configuration:
    • Select Credit Card as the Payment Page type.
    • On the Create New Hosted Page page, select Enable 3D Secure 2.0 and select Stripe v2 gateway as the default payment gateway.
  2. Request from Zuora a signature for the Payment Page. 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. Specify the following parameters when calling the Generate RSA signature REST API operation to generate the digital signature.

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

    {
       "uri":"https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do",
       "method":"POST",
       "pageId":"test808145b3bf9d0145b3c6812b0008",
       "paymentGateway":"Stripe2",
       "authroizationAmount":"100",
       "currency":"USD",
       "accountId":"test808145b3bf9d0145b3c6812b0008"
    }
    
    {
       "uri":"https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do",
       "method":"POST",
       "pageId":"test808145b3bf9d0145b3c6812b0008",
       "paymentGateway":"Stripe2",
       "accountId":"test808145b3bf9d0145b3c6812b0008"
    }
    
  3. Set up your client code to integrate the Payment Page to your web page by following instructions in step 3 in Payment Pages 2.0 implementation process. When rendering the Payment Page form, specify the following additional parameters in the Z.render function.

    • For authorization amount processing, pass in these client parameters:
      • accountId
      • currency
      • authorizationAmount
    • For invoice processing, pass in the accountId client parameter.

    For authorization amount processing, pass in the following additional parameters:

    Parameter Description

    doPayment

    Required

    Type: boolean

    Default: false

    true indicates that this is a one-time payment transaction. The Payment Page will create a payment method as well as process the one-time payment transaction. If it is false, the Payment Page will only create a payment method.

    storePaymentMethod

    Optional

    Type: boolean

    Default: true

    true indicates that the created payment method will be stored in your Zuora customer account.

    field_accountId

    Required

    A client parameter supported for Payment Pages 2.0. See Client parameters for Payment Pages 2.0 for details.

    authorizationAmount

    Required

    A client parameter supported for Payment Pages 2.0. See Client parameters for Payment Pages 2.0 for details.

    field_currency

    Required

    A client parameter supported for Payment Pages 2.0. See Client parameters for Payment Pages 2.0 for details.

    Here is an example.

    var params = {
        doPayment:"true",
        field_accountId:"testc0f87596f2f301759c29443622fa",
        authorizationAmount:"99",
        field_currency:"USD"
    };
    

    For invoice processing, pass in the following additional parameters:

    Parameter Description

    doPayment

    Required

    Type: boolean

    Default: false

    true indicates that this is a one-time payment transaction. The Payment Page will create a payment method as well as process the one-time payment transaction. If it is false, the Payment Page will only create a payment method.

    storePaymentMethod

    Optional

    Type: boolean

    Default: true

    true indicates that the created payment method will be stored in your Zuora customer account.

    field_accountId

    Required

    A client parameter supported for Payment Pages 2.0. See Client parameters for Payment Pages 2.0 for details.

    documents

    Required

    An array of invoices to be paid in this transaction, containing the following fields:

    • type - The value must be invoice.
    • ref - The value must be the invoice number, such as INV0000001.

    Here is an example.

    var params = {
        doPayment:"true",
        field_accountId:"testc0f87596f2f301759c29443622fa",
        documents:“[{\”type\”: \”invoice\”, \”ref\”: \”INV0000001\”}, {\”type\”: \”invoice\”, \”ref\”: \”INV0000002\”}]”
    };
    

Best practice for handling off-session payment attempts requiring user authentication

For the off-session payment attempts that require your users to come back on-session to authenticate the payment, you can also implement a one-time payment flow and configure a payment notification to bring your users on-session.

Follow the preceding procedure to implement a one-time Payment Page. When rendering the Payment Page form, in addition to the additional parameters for authorization amount or invoice processing, pass in the pmId client parameter as well. Use this parameter to allow your users to view and edit their existing credit card payment method information, and re-authenticate the credit card upon submission.

Additional information

You can also pass in additional mandate fields to support processing recurring payments in India through a one-time payment flow. See Implement Payment Pages 2.0 to support processing payments in India for details.