Skip to main content

Create payment methods on FiservCommerceHub

Zuora

Create payment methods on FiservCommerceHub

  1. Last updated
  2. Save as PDF

This payment gateway integration can be requested through the Specialized Payment Connections service at an additional cost.

To create Credit Card payment methods on FiservCommerceHub, use one of the following approaches:

REST API approach

You can create tokenized Credit Card payment methods through the Create a payment method API operation. Use one of the following options.

Option 1: Pass in your existing token

In your request, pass in the following required fields. A Credit Card payment method is created by using the provided token, and the token is used in processing subsequent payment transactions.

Required Field Type Description

accountKey

 string

Zuora internal ID of the customer account that will own the payment method.

cardMaskNumber

 string

The masked card number.

cardType

 string

The type of the credit card.
expirationMonth integer

One or two-digit expiration month (1-12) of the credit card.
expirationYear integer

Four-digit expiration year of the credit card.

tokens

 object

Pass in your existing token information through the following nested fields in this container:

  • gatewayType

    Type: string

    The type of payment gateway to generate the token. This field is case-sensitive. Specify FiservCommerceHub  in this field. 

  • tokenId

    Type: string

    Specify the value of tokenData.

  • secondTokenId

    Type: string

    Pass in the second token of the payment method if available.

  • thirdTokenId

    Type: string

    Pass in the third token of the payment method if available.

type

 string

Type of the payment method. Specify CreditCard in this field.

For other optional fields, see Create a payment method.

Here is an example of the API request:

{
    "type": "CreditCard",
    "cardType": "Visa",
    "expirationMonth": 9,
    "expirationYear": 2025,
    "cardMaskNumber": "*******1111",
    "tokens": {
        "gatewayType": "FiservCommerceHub",
        "tokenId": "0000030002410000"
    },
    "accountKey": "8ac680458ed1c4ba018ed2237bfa416a"
}

Option 2: Pass in card information and your existing tokens

In your request, pass in the following required fields. Both the card information and the token are stored for the payment method but the token is used in processing subsequent payment transactions.

Required Field Type Description

accountKey

 string

Zuora internal ID of the customer account that will own the payment method.

cardMaskNumber

 string

The masked card number.
cardHolderInfo object

Container for cardholder information. 

The nested cardHolderName field is required. Pass in the card holder's full name as it appears on the card, such as "Amy Lawrence", 50 characters or less.

cardType

 string

The type of the credit card.
expirationMonth integer

One or two-digit expiration month (1-12) of the credit card.
expirationYear integer

Four-digit expiration year of the credit card.

tokens

 object

Pass in your existing token information through the following nested fields in this container:

  • gatewayType

    Type: string

    The type of payment gateway to generate the token. This field is case-sensitive. Specify FiservCommerceHub  in this field. 

  • tokenId

    Type: string

    Specify the value of tokenData.

  • secondTokenId

    Type: string

    Pass in the second token of the payment method if available.

  • thirdTokenId

    Type: string

    Pass in the third token of the payment method if available.

type

 string

Type of the payment method. Specify CreditCard in this field.

For other optional fields, see Create a payment method.

Here is an example of the API request:

{
    "type": "CreditCard",
    "cardHolderInfo": {
        "cardHolderName": "John Doe"
    },
    "cardType": "Visa",
    "expirationMonth": 9,
    "expirationYear": 2025,
    "cardMaskNumber": "*******1111",
    "tokens": {
        "gatewayType": "FiservCommerceHub",
        "tokenId": "0000030002410000"
    },
    "accountKey": "8ac680458ed1c4ba018ed2237bfa416a"
}

Option 3: Pass in card information and the tokenize flag

In your request, pass in the following required fields. A token is generated when validating the payment method with the gateway. Both the card information and the token are stored for the payment method but the token is used in processing subsequent payment transactions.

Required Field Type Description

accountKey

 string

Zuora internal ID of the customer account that will own the payment method.

cardNumber

 string

Credit card number.
securityCode string

CVV or CVV2 security code of the credit card. To ensure PCI compliance, this value is not stored and cannot be queried.

cardHolderInfo

 object

Container for cardholder information.

The nested cardHolderName field is required. Pass in the card holder's full name as it appears on the card, such as "Amy Lawrence", 50 characters or less.

cardType

 string

The type of the credit card.

expirationMonth

 integer

One or two-digit expiration month (1-12) of the credit card.

expirationYear

 integer

Four-digit expiration year of the credit card.

type

 string

Type of the payment method. Specify CreditCard in this field.

tokenize

 boolean

Default: false

Specify true for this field to tokenize the payment method with the card number. 

Here is an example of the API request for creating a tokenized Credit Card payment method:

{
    "type": "CreditCard",
    "accountKey": "402880e58fbd6560018fbd73d76c00b4",
    "cardType": "Visa",
    "cardHolderInfo": {
        "cardHolderName": "Joe Bloggs"
    },
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2025,
    "securityCode": 977,
    "tokenize": true
}

For other optional fields, see Create a payment method.

Hosted payment page approach

You can implement a hosted payment page through the Payment Pages 2.0 solution to collect your customer's payment method data and create the payment method in Zuora. When creating a payment method through the hosted payment page, a token is generated and stored for the payment method.

For more information about the implementation of hosted payment pages, see Payment Pages 2.0 implementation overview.

Zuora UI approach

See Set up the payment method through the Zuora UI for more information. When creating payment methods through the UI, a token is generated and stored for the payment method.

Required configuration settings

For tokenized payment methods, you must validate them in Zuora so that payments made with these payment methods are successful. To validate tokenized payment methods, enable the following settings on the gateway instance configuration page. For more information about the configuration settings, see Set up and configure a FiservCommerceHub payment gateway instance.

  • Verify new payment method
  • Verify updated payment method