Migrate an existing payment method

Last updated
Save as PDF

↵

Before enabling stored credential transactions for an existing payment method, ensure that the customer has given consent for their payment credentials to be stored on file.

How to enable stored credential transactions for an existing payment method depends on 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 (see below).

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 (see below).

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.

Create an Agreed stored credential profile through REST API

To create an Agreed stored credential profile through the REST API, use the Create stored credential profile operation with the following request body. 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 through REST API

To create an Active stored credential profile through the REST API, use the Create stored credential profile operation with the following request body. 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.

What's next

You can view the stored credential profile after migrating an existing payment method in Zuora.