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 following gateway integrations. Additional fields can be included to support processing either authorization amounts or posted invoices.

Payment gateway integration Supported payment method type Support for recurring transactions
Braintree Credit Card No
CyberSource 2.0 Credit Card No
GoCardless

SEPA Direct Debit

Implement a Payment Page 2.0 to support processing payments through the GoCardless Instant Bank Pay and Verified Mandates payment flow. This feature is in the Early Adopter phase. To enable it, submit a request at Zuora Global Support.
Yes
Stripe v2
  • Credit Card
  • Credit Card Reference Transactions
Yes

Before you begin

  • Ensure that the following features are enabled:
  • The invoices must be posted before the invoices are paid through the one-time payment.
  • To implement a Payment Page 2.0 to support processing payments through the GoCardless Instant Bank Pay and Verified Mandates Payment payment flow, submit a request at Zuora Global Support to enable this feature.

Procedure

To implement Payment Pages 2.0 to process one-time payments, 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 Configure Credit Card Reference Payment Pages 2.0 for Stripe v2 or Configure Credit Card Type Payment Pages 2.0, and implementing the following configuration:
    • Select the Payment Page type:
      Payment gateway Available Payment Page type
      Braintree Credit Card
      CyberSource 2.0 Credit Card
      GoCardless Bank Transfer-SEPA
      Stripe v2
      • Credit Card
      • Credit Card Reference (CCRef) Transactions

      Note: If you only need to set up your user's card without immediately collecting a payment, create a CCRef Transactions Payment Page. Credit Card Payment Pages do not support this feature.

    • On the Create New Hosted Page page, select Enable 3D Secure 2.0.

    For more information about the optional tasks of setting up a Payment Page, see step 1 in Payment Pages 2.0 implementation process.

  2. 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/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 the following additional parameters:

    Parameter Description

    doPayment

    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 or not specified, the Payment Page will only create a payment method.

    For Credit Card Payment Pages for Stripe v2, if all of the following requirements are met, the network transaction IDs will be generated and stored for the payment methods. The stored payment methods can be used to process the subsequent recurring transactions.

    • doPayment is true
    • storePaymentMethod is true
    • The support for generating stored credential profiles is implemented

    For SEPA Payment Pages for GoCardless, if all of the following requirements are met, the stored payment methods can be used to process the subsequent recurring transactions:

    • doPayment is true
    • storePaymentMethod is true

    storePaymentMethod

    Type: boolean

    Default: true

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

    For Credit Card Payment Pages for Stripe v2, if all of the following requirements are met, the network transaction IDs will be generated and stored for the payment methods. The stored payment methods can be used to process the subsequent recurring transactions.

    • doPayment is true
    • storePaymentMethod is true
    • The support for generating stored credential profiles is implemented

    For SEPA Payment Pages for GoCardless, if all of the following requirements are met, the stored payment methods can be used to process the subsequent recurring transactions:

    • doPayment is true
    • storePaymentMethod is true

    For processing local Indian one-time payments with Credit Cards, to be compliant with the Reserve Bank of India’s (RBI) regulation for storage of payment system datastorePaymentMethod must be set to false.

    field_accountId

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

    This field is required if doPayment is true.

    This field is optional if doPayment is false or not specified:

    • If field_accountId is specified, the payment method will be created for the specified account.
    • If field_accountId is not specified, an orphan payment method will be created.

    authorizationAmount

    Required

    If doPayment is true, this field is used to specify the one-time payment amount sent to the gateway. 

    If doPayment is false, this field is used to specify the initial authorization amount of the payment method. 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.

    paymentDescription

    Required and only applicable to the implementation of GoCardless Instant Bank Pay and Verified Mandates payment flow with SEPA Direct Debit

    Type: string

    The string will be displayed as the description in the subscription information section in the payment flow.

    Here is an example.

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

    For invoice processing, pass in the following additional parameters:

    Parameter Description

    doPayment

    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 or not specified, the Payment Page will only create a payment method.

    For Credit Card Payment Pages for Stripe v2, if all of the following requirements are met, the network transaction IDs will be generated and stored for the payment methods. The stored payment methods can be used to process the subsequent recurring transactions.

    • doPayment is true
    • storePaymentMethod is true
    • The support for generating stored credential profiles is implemented

    For SEPA Payment Pages for GoCardless, if all of the following requirements are met, the stored payment methods can be used to process the subsequent recurring transactions:

    • doPayment is true
    • storePaymentMethod is true

    storePaymentMethod

    Type: boolean

    Default: true

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

    For Credit Card Payment Pages for Stripe v2, if all of the following requirements are met, the network transaction IDs will be generated and stored for the payment methods. The stored payment methods can be used to process the subsequent recurring transactions.

    • doPayment is true
    • storePaymentMethod is true
    • The support for generating stored credential profiles is implemented

    For SEPA Payment Pages for GoCardless, if all of the following requirements are met, the stored payment methods can be used to process the subsequent recurring transactions:

    • doPayment is true
    • storePaymentMethod is true

    For processing local Indian one-time payments with Credit Cards, to be compliant with the Reserve Bank of India’s (RBI) regulation for storage of payment system datastorePaymentMethod must be set to false.

    field_accountId

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

    This field is required if doPayment is true.

    This field is optional if doPayment is false or not specified:

    • If field_accountId is specified, the payment method will be created for the specified account.
    • If field_accountId is not specified, an orphan payment method will be created.

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

    Required and only applicable to the implementation of GoCardless Instant Bank Pay and Verified Mandates payment flow with SEPA Direct Debit

    Type: string

    The string will be displayed as the description in the subscription information section in the payment flow.

    Here is an example.

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

Best practices

Handle 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. For more information about the pmId parameter, see Client parameters for Payment Pages 2.0.

Avoid applying payments to the same invoice through different methods at the same time

To avoid payment processing failure due to applying payments to the same invoice through payment runs and one-time payment flow at the same time, plan your payment collection approach to decide which invoices will be collected through which method, and separate your invoices into different groups. When an invoice is being processed by a payment, it is locked and any further payment against the invoice will fail. If you encounter this problem, wait till the current payment is properly finished and process another payment against the invoice.

Additional information

For Stripe v2, 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.