Skip to main content

Create payment methods through API or UI with stored credential profiles

Zuora

Create payment methods through API or UI with stored credential profiles

  1. Last updated
  2. Save as PDF

When creating a credit card or Apple Pay payment method, you can specify whether the customer has given consent for their payment credentials to be stored on file for use in subsequent transactions. This enables stored credential transactions for the payment method.

How to specify whether the customer has given consent depends on how you create the payment method.  

Create credit card payment methods through APIs

You can use either the REST or SOAP API operations to create credit card payment methods:

Scenario How to specify customer consent
REST API - Using Create a payment method

Set the following fields in the JSON request body. See Create a payment method in API Reference for details about supported values for these fields.

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

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

REST API - Create payment methods using Create

Note: Creating stored credential profiles with the recurring type is supported through this API, but creating the unscheduled profiles is not supported.

Set the X-Zuora-WSDL-Version request header to 94 or later, and include the following fields and corresponding values in the request body. See  Create in API Reference for details about supported values for these fields.

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

You can also set the MitConsentAgreementRef field if you want to provide your reference for the consent agreement that you have established with the customer.
REST API - Create payment methods using the paymentMethod field in Create account

Set the following fields in the JSON request body. See Create account in API Reference for details about supported values for these fields.

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

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

SOAP API - Creating a PaymentMethod object

Note: Creating stored credential profiles with the recurring type is supported through this SOAP API, but creating the unscheduled profiles is not supported.

Use WDSL version 94 or later. An example of the SOAP endpoint is https://apisandbox.zuora.com/apps/services/a/94.0.

Set the following fields in the request body: 

...
<ns2:MitProfileAction>Activate</ns2:MitProfileAction>
<ns2:MitProfileType>Recurring</ns2:MitProfileType>  
<ns2:MitConsentAgreementSrc>External</ns2:MitConsentAgreementSrc>          
<ns2:MitConsentAgreementRef></ns2:MitConsentAgreementRef>            
<ns2:MitNetworkTransactionId></ns2:MitNetworkTransactionId>

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

Create Apple Pay payment methods through API

You can use the Create an Apple Pay payment method API operation to create a stored credential profile when creating an Apple Pay payment method on the CyberSource v2.0 gateway integration.

Note: The support for stored credential transactions for Apple Pay is only available on CyberSource 2.0 integration.

In the Create an Apple Pay payment method operation, set the following fields in the request body.

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

Create credit card payment methods through UI 

When creating an electronic payment method, select the End user consent agreement received checkbox in the Zuora UI.

End user consent received checkbox

Result

Zuora attempts to create a payment method containing a stored credential profile:

  • Gateway supports stored credential transactions

    If the payment gateway supports stored credential transactions, Zuora sends a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credentials:

    • If the CIT succeeds, Zuora creates a new payment method. Zuora also creates a stored credential profile with Active status.
    • If the CIT does not succeed, Zuora does not create a new payment method. Zuora also does not create a stored credential profile.
  • Gateway does not support stored credential transactions

    If the payment gateway does not support stored credential transactions, Zuora creates a stored credential profile with Agreed status and sends a legacy authentication request to the payment gateway to validate the card details:

    • If the authentication request succeeds, Zuora creates a new payment method. Zuora also creates a stored credential profile with Agreed status.
    • If the authentication request does not succeed, Zuora does not create a new payment method. Zuora also does not create a stored credential profile.

To learn about the differences between Active and Agreed stored credential profiles, see Payments and payment runs.