Skip to main content

Migrate an existing payment method

Zuora

Migrate an existing payment method

  1. Last updated
  2. 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 next used in a payment. 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 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 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. 

With status set to Agreed, Zuora will retrieve the network transaction ID by making a grandfathering call, and use it for the next payment run.

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

With status set to Active,CVV must be entered because Zuora will immediately send an authorization request to the gateway as a cardholder present transaction that requires CVV. If the request sent to the gateway without CVV, it is highly likely the transaction will be declined and the future processing is impacted.

Create an Active stored credential profile through the Zuora UI

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

  1. Locate the payment method in the Electronic Payment Methods section of the customer account, then click add profile.
  2. 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 do not enter CVV, Zuora will retrieve the network transaction ID by making a grandfathering call, and use it for the next payment run. 
  3. 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.