Skip to main content

Tokenize payment methods on Adyen Integration v2.0

Zuora

Tokenize payment methods on Adyen Integration v2.0

  1. Last updated
  2. Save as PDF

Use the instructions in this article to tokenize the following payment methods on Adyen Integration v2.0:

  • ACH
  • SEPA

The following table describes the token field mappings:

Adyen Field Zuora Field
shopperReference tokens > tokenId
recurringDetailReference tokens > secondTokenId

Tokenize ACH payment methods

To create tokenized ACH payment methods, use one of the following approaches:

Approach Description Example
Use an API operation that supports payment method creation, such as Create a payment method, to tokenize raw account information

Pass in the following required account information and set tokenize to true:

  • type
  • bankABACode
  • bankAccountName
  • bankAccountNumber
  • bankAccountType
  • bankName

Tokens are generated and stored in Zuora, and used in the subsequent recurring payments.

 
{
  "accountKey":"8a8d90b9936821cd0193685a12080000",
  "bankAccountNumber": "123456789",
  "bankABACode": "121000358",
  "bankAccountName": "Test Bank",
  "bankAccountType": "Checking",
  "bankName": "active",
  "phone": "334343",
  "email": "email@test.com",
  "addressLine1": "Test Plaza", 
  "addressLine2": "Byway Street",
  "city": "Fremont",
  "country": "CA",
  "state": "Ontario",
  "zipCode": "94020",
  "type": "ACH",
  "tokenize": true
}

Use an API operation that supports payment method creation, such as Create a payment method, to pass in existing tokens

Pass in the following required fields:

  • type
  • bankABACode
  • bankAccountName
  • bankAccountType
  • bankName

Pass in shopperReference through tokens > tokenId.

Pass in recurringDetailReference through tokens > secondTokenId.

Pass in the masked account number through bankAccountMaskNumber. 

Tokens are stored in Zuora and used in subsequent payments.

 
{
  "accountKey":"8a8d90b9936821cd0193685a12080000",
  "bankABACode": "121000358",
  "bankAccountName": "Test Bank",
  "bankAccountType": "Checking",
  "bankName": "active",
  "phone": "334343",
  "email": "test@email.com",
  "addressLine1": "Test Plaza", 
  "addressLine2": "Byway Street",
  "city": "Fremont",
  "country": "CA",
  "state": "Ontario",
  "zipCode": "94020",
  "type": "ACH",
  "bankAccountMaskNumber": "12***6789",
  "tokens": {
        "gatewayType": "Adyen",
        "tokenId": "A00000001",
        "secondTokenId": "S8P8RZDBMBTVZZ00"
    }
}

Use an API operation that supports payment method creation, such as Create a payment method, to pass in existing tokens and raw card information

 

Pass in the following required card information:

  • type
  • bankABACode
  • bankAccountName
  • bankAccountNumber
  • bankAccountType
  • bankName

Pass in shopperReference through tokens > tokenId.

Pass in recurringDetailReference through tokens > secondTokenId.

Pass in the masked account number through bankAccountMaskNumber.

Tokens are stored in Zuora and used in subsequent payments.

 
{
  "accountKey":"8a8d90b9936821cd0193685a12080000",
  "bankAccountNumber": "123456789",
  "bankABACode": "121000358",
  "bankAccountName": "Test Bank",
  "bankAccountType": "Checking",
  "bankName": "active",
  "phone": "334343",
  "email": "test@email.com",
  "addressLine1": "Test Plaza", 
  "addressLine2": "Byway Street",
  "city": "Fremont",
  "country": "CA",
  "state": "Ontario",
  "zipCode": "94020",
  "type": "ACH",
  "bankAccountMaskNumber": "12***6789",
  "tokens": {
        "gatewayType": "Adyen",
        "tokenId": "A00000001",
        "secondTokenId": "S8P8RZDBMBTVZZ00"
    }
}
Tokenize payment methods when processing payments On the configuration page of your Adyen Integration v2.0 gateway instance, select Tokenize payment method. With this setting enabled, tokens are generated and stored for ACH and SEPA payment methods when processing payments through UI, API, or Payment Pages 2.0.  

 

Tokenize SEPA payment methods

To create tokenized SEPA payment methods, use one of the following approaches:

Approach Description Example
Use the Create a payment method API operation to tokenize IBAN

Pass in IBAN and set tokenize to true.

The tokens will be generated and stored in Zuora, and will be used in the subsequent recurring payments. 

 
{
   "IBAN": "NL13TEST0123456789",
   "accountKey": "402881868ab1b937018ab2314b91234a",
   "accountHolderInfo": {
     …
   },
   "type": "SEPA",
   "tokenize": true
}

Use the Create a payment method API operation to pass in existing tokens

Pass in shopperReference through tokens > tokenId.

Pass in recurringDetailReference through tokens > secondTokenId.

Pass in the masked account number through accountMaskNumber. 

Tokens will be stored in Zuora and used in the subsequent payments.

 
{
   "accountKey": "402881868ab1b937018ab2314b91234a",
   "accountHolderInfo": {
…
   },
   "type": "SEPA",
   "accountMaskNumber": "****1234",
   "tokens": {
     "gatewayType": "Adyen",
     "tokenId": "testTokenId",
     "secondTokenId": "testSecondTokenId"
   }
}

Tokenize payment methods when processing payments

 

 On the configuration page of your Adyen gateway instance, select Tokenize payment method. With this setting enabled, tokens will be generated for SEPA and ACH payment methods when processing payments through UI, API, or hosted payment page on Adyen Integration v2.0.  

 

Tokenizing SEPA payment methods through the preceding approaches is generally available in Sandbox environments. To enable it in Production environments, submit a request at Zuora Global Support.

Validate tokenized payment methods

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:

  • Verify new payment method
  • Verify updated payment method