home

Zuora Payments

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

thumbnailZuora Payments

Manage payment gateway integrations and payment methods

Define and set up payment methods

Learn how to define and set up payment methods for customer accounts, including activation, linking orphan methods, and managing stored credential profiles.

Payment methods are the ways in which customers pay for their subscription services. A customer can choose a payment method based on your company’s list of preferred payment methods. To set up payment methods for the customer accounts, define the payment methods your company can support in Payments settings, and then set up the payment methods for the customer accounts.

Note:

Payment methods replicated from the production environment can not be used for testing with gateway in the sandbox environment because they are scrubbed when refreshing the environments. You must close and delete the payment method and create a new payment method for testing.

Activate payment methods

Navigate to Payment Settings > Payment Method to define and activate payment methods your company supports.

Note that you can create payment methods using the API operations even if the payment method type is not selected on the Customize Payment Methods page.

For more details about the supported payment methods, see Supported Payment Methods.

Best practices

Link to a customer account:

Although Zuora supports creating orphan payment methods that are not associated with customer accounts, it is recommended that you link the payment method with an account when creating the payment method:

  • For payment methods created through API operations, specify the accountKey or accountID field.

  • For payment methods created through hosted payment method pages, specify the field_accountId client parameter in the request.

Pass in city and country information:

It is recommended to provide the city and country information when creating a payment method. The information will be sent to the gateway and be used to process payments with this payment method. If the information is not provided during payment method creation, the city and country data will be missing during payment processing. The bill-to or sold-to address information of your account will not be included in the request to the gateway.

An orphan payment method is a payment method that is not currently associated with any customer account. These payment methods exist in your system but are not linked to a specific customer record.

You can associate an orphan payment method with a customer account in two ways:

  • Updating an existing payment method: Use the Update a payment method operation to link the existing orphan payment method to an established customer account. See Update a payment method for more detailed information.

  • Creating a new payment method: You can specify the account ID during the payment method creation to link it immediately once the account is established. See Create a payment method for more detailed information.

It is important to note that orphan payment methods are not automatically deleted, regardless of whether they are associated with an account.

Manage stored credential profiles for credit cards

A stored credential profile within a payment method is a container for data of a credential that has been stored in accordance with a customer consent agreement. Each stored credential profile includes a transaction identifier, which Zuora sends to the payment gateway whenever the payment method is used in a payment.

When you create a Credit Card, Apple Pay, or Google Pay payment method through the Zuora UI, API operations, or Payment Pages 2.0, Zuora automatically creates a stored credential profile within the payment method. See Stored credential transactions for more information.

Retrieve token information of payment methods

If a payment method is associated with any tokens, the following information about the token is available in the Electronic Payment Methods section on the customer account page:

  • Token Type

    • Gateway : The token is generated and used by a specific payment gateway.

    • Network : The token is generated by the card networks and can be used across gateways if provisioned in the 'On Behalf Of' model.

  • Payment Gateway : The payment gateway that generated the token.

  • Up to three token IDs that are associated with this payment method on a specific gateway.

Last updated: December 3, 2025