Manage stored credential profiles

View stored credential profiles

You can retrieve the information of stored credential profiles of a payment method through either the UI or REST API operation.

To view stored credential profiles of a payment method through the UI, navigate to Customer Accounts > Electronic Payment Methods section. The stored credential profile is presented in the Stored Credential Profile List field.
To retrieve stored credential profiles of a payment method through the API operation, use the List stored credential profiles of a payment method API operation.

Create a stored credential profile for a payment method

Since the 2023.07.R2 release in July 2023, Zuora has rolled out the automatic creation of stored credential profiles for Credit Card, Debit Card, Apple Pay and Google Pay payment methods. For payment methods newly created through UI, API operations, or Payment Pages, and for existing payment methods without stored credential profiles, the stored credential profiles, including the network transaction ID (NTI) or equivalent, will be created and activated for all supported card brands. See Overview of support for stored credential transactions for more information.

While it is possible to create stored credential profiles manually through UI or API operations, we do not recommend doing so because of the complexity involved. For example, before creating stored credential profiles for payment methods, consider whether the payment gateway supports merchant-initiated stored credential transactions (MITs) without transaction IDs:

MITs without transaction IDs are supported

If the payment gateway supports MITs without transaction IDs, for example, Chase Paymentech Orbital Gateway, you should create an Agreed stored credential profile within the payment method. You can create an Agreed stored credential profile through the REST API.

When you create the Agreed stored credential profile, Zuora does not immediately validate the stored credentials with the payment gateway. Instead, Zuora validates the stored credentials by sending a merchant-initiated transaction to the payment gateway when the payment method is used in the next payment transaction. The status of the stored credential profile changes to Active at this point, provided the payment succeeds. If the payment does not succeed, the stored credential profile remains in the Agreed status.
MITs without transaction IDs are not supported

If the payment gateway supports stored credential transactions, but does not support MITs without transaction IDs, you should create an Active stored credential profile within the payment method. You can create an Active stored credential profile through the REST API or Zuora UI.

When you create the Active stored credential profile, Zuora immediately validates the stored credentials with the payment gateway. Zuora validates the stored credentials by sending a cardholder-initiated transaction (CIT) to the payment gateway.

If the payment gateway does not support stored credential transactions, it does not matter whether you create an Agreed stored credential profile or an Active stored credential profile. In either case, Zuora sets the status of the stored credential profile to Agreed.

To learn more about the differences between Active and Agreed stored credential profiles, see Stored credential profiles in payments and payment runs.

The following sections describe different approaches to manually creating stored credential profiles for different scenarios.

Scenario: Create a stored credential profile when creating a payment method

When creating a payment method through any of the following API operations, pass in the required fields to create the stored credential profile.

API operation	Required fields	Notes
Create a payment method	mitProfileAction mitProfileType mitConsentAgreementSrc
Create a credit card payment method (No longer under active development)	mitProfileAction mitProfileType mitConsentAgreementSrc
Create an Apple Pay payment method	mitProfileAction mitProfileType mitConsentAgreementSrc
Create an account	The following nested fields in the `paymentMethod` field: mitProfileAction mitProfileType mitConsentAgreementSrc
Create an order	The following nested fields in the `newAccount` > `paymentMethod` or `subscriptions` > `orderActions` > `createSubscription` > `newSubscriptionOwnerAccount` > `paymentMethod` field: mitProfileAction mitProfileType mitConsentAgreementSrc
Create an order asynchronously
Sign up	The following nested fields in the `accountData` > `paymentMethod` field: mitProfileAction mitProfileType mitConsentAgreementSrc
Create a payment method using the Create Action	MitProfileAction MitProfileType MitConsentAgreementSrc	Set the X-Zuora-WSDL-Version request header to 94 or later. Creating stored credential profiles with the recurring type is supported through this API, but creating the unscheduled profiles is not supported.
CRUD: Create a payment method (No longer under active development)	MitProfileAction MitProfileType MitConsentAgreementSrc	Creating stored credential profiles with the recurring type is supported through this SOAP API, but creating the unscheduled profiles is not supported.
Create a PaymentMethod object using the create() SOAP API operation (No longer under active development)	MitProfileAction MitProfileType MitConsentAgreementSrc	Use WDSL version 94 or later. An example of the SOAP endpoint is https://apisandbox.zuora.com/apps/services/a/94.0. Creating stored credential profiles with the recurring type is supported through this SOAP API, but creating unscheduled profiles is not supported.
Create a payment method using the Subscribe Action (No longer under active development)	The following nested fields in the `subscribes`> `PaymentMethod` field: MitProfileAction MitProfileType MitConsentAgreementSrc	Creating stored credential profiles with the recurring type is supported through this SOAP API, but creating the unscheduled profiles is not supported.

Optionally, you can also set the following fields to pass in additional information for your stored credential profile:

mitConsentAgreementRef: Provide your reference for the consent agreement that you have established with the end customer.
mitNetworkTransactionId: Provide the ID of a network transaction. Only applicable if you set the mitProfileAction field to Persist.

The following examples show how to specify the required fields in the request body of an API operation.

Example 1: Create a payment method REST API

{
    "type": "CreditCard",
    ...
    "mitProfileAction": "Activate",
    "mitProfileType": "Recurring",
    "mitConsentAgreementSrc": "External"
}

Example 2: Create a payment methods using the Create Action

"objects": [
    {
        ...
        "MitProfileAction": "Activate",
        "MitProfileType": "Recurring",
        "MitConsentAgreementSrc": "External",
        "Type": "CreditCard"
    }
    ],
    "type": "PaymentMethod"
}

Example 3: Create a payment method using Create an account

{
    ...
    "paymentMethod":
        {
            "type": "CreditCard",
            ...
            "mitProfileAction": "Activate",
            "mitProfileType": "Recurring",
            "mitConsentAgreementSrc": "External"
        },
    ...
}

Scenario: Create a stored credential profile for an existing payment method

Create a stored credential profile through REST API

Use the Create stored credential profile operation to create an Agreed or Active stored credential profile.

Create an Agreed stored credential profile

The value of status must be Agreed. The value of type can be Recurring or Unscheduled.

{
  "consentAgreementSrc": "External",
  "status": "Agreed",
  "type": "Recurring"
}

You can also set the consentAgreementRef field if you want to provide your reference for the consent agreement that you have established with the customer.

Create an Active stored credential profile

The value of status must be Active. The value of type can be Recurring or Unscheduled.

{
  "consentAgreementSrc": "External",
  "status": "Active",
  "type": "Recurring",
  "cardSecurityCode": "123"
}

You can also set the consentAgreementRef field if you want to provide your reference for the consent agreement that you have established with the customer.

If you want to create an Active stored credential profile, we strongly recommend that you provide CVV in the request because Zuora will immediately send an authorization request to the gateway as a cardholder present transaction. If the request sent to the gateway does not contain CVV, the transaction will highly likely be declined and the subsequent transactions will be impacted.

Create an Active stored credential profile through the Zuora UI

To create an Active stored credential profile through the Zuora UI:

Locate the payment method in the Electronic Payment Methods section of the customer account, and then click Add Profile.
In the opened dialog, select End user consent agreement received, select Recurring or Unscheduled for Profile type, and optionally enter the card security code (CVV) in Card Security Code. If you enter CVV, Zuora will retrieve the network transaction ID by making a grandfathering call, and use it for the subsequent payment transactions.
Click Confirm.

Create a stored credential profile through Payment Pages 2.0

You can use the pmId parameter in your Payment Pages 2.0 implementation, which allows end customers to edit and re-authenticate their existing credit card upon submission. A stored credential profile can be created during the re-authentication through Payment Pages 2.0, and CVV is required in this case.

To use this parameter in Payment Pages 2.0, specify the parameters in a JavaScript object with key-value pairs and pass them to the Z.render function in your client. The following code snippet provides an example:

var params = {
    pmId: "402881e4739fb89601739ff596180040"
    ...
    };
    ...
    Z.render(
      params,
      prepopulateFields,
      callback
    );

For more information about the pmId parameter, see Client parameters for Payment Pages 2.0.

Scenario: Create stored credential profiles for Credit Card payment methods on Stripe v2 through MOTO transactions

For credit card payment methods on Stripe v2, you can use MOTO transactions to create stored credential profiles while creating payment methods or processing recurring payments. To enable this support, complete the following steps:

Click your username in the upper right and navigate to Settings > Payments > CIT/MIT Configuration.
In the MOTO Support section, click Edit and then select any or all of the following settings:
- Always use MOTO transaction to create stored credential profiles when payment methods are created from Zuora UI
  The MOTO transaction indicator will be included in the payment method validation request to the gateway and a recurring stored credential profile will be created for the card. The NTI will be returned in the authorization response.
- Allow using MOTO transaction as grandfathering transaction to create stored credential profiles
  The MOTO transaction indicator will be included in the recurring payment request to the gateway and a recurring stored credential profile will be created for the card used to process the payment. The NTI will be returned in the authorization response.

Cancel or expire a stored credential profile

To cancel or expire a stored credential profile through the UI, navigate to Customer Accounts > Electronic Payment Methods > Stored Credential Profile List, and then use the actions in the Operation column.
To cancel or expire a stored credential profile through the API operation, use the following API operations:
- Cancel a stored credential profile
- Expire a stored credential profile

You cannot reactivate the stored credential profile after you cancel or expire it.

Export data for stored credential profiles

Use the Stored Credential Profile data source to export data for stored credential profiles. If you want to export the Network Transaction IDs, ensure Stored Credential Profile Data is selected.