Skip to main content

Prepare the definition file of the custom payment method type

Zuora

Prepare the definition file of the custom payment method type

Before you submit a request to Zuora Global Support to enable the UPC and OPM services, prepare a definition file for your custom payment method type. You will need to enclose this definition file in your request for review and approval.

Define the fields and validation rules of your custom payment method type with metadata in a JSON file. The following tables describe the JSON schema to follow. An example is provided at the end.

For the fields with the Editable column as No in the below table, they cannot be changed once the custom payment method type is published.

Metadata definition for a custom payment method type

Metadata Required Description Editable
name Yes A string to identify the type of the custom payment method in the API name of the custom payment method type.

This value must be alphanumeric, starting with a capital letter, excluding JSON preserved characters e.g.  * \ ’ ”. '_' or '-' is not allowed, either.

This field is used along with the tenantId field by the system to construct and generate the API name of the custom payment method type in the following way:

name__c_tenantId

For example, if name is AmazonPay, and tenantId is 12368, the API name of the custom payment method type will be AmazonPay__c_12368.

Once created, the name cannot be changed.

Character limit: 18

No
label Yes The label that is used to refer to this type in the Zuora UI.

Alphanumeric, excluding JSON preserved characters e.g.  * \ ’ ” 

Character limit: 40

Yes
tenantId Yes Zuora tenant ID. If multi-entity is enabled in your tenant, this is the ID of the parent tenant of all the sub entities. No
entityId No If an entity UUID is provided, this custom payment method type is specific to this entity only. If no entity UUID is provided, the custom payment method type is available to the global entity and all the sub entities in the tenant.

Note: After a custom payment method type has been shared among entities, you cannot change it to be entity-specific.

No
methodReferenceIdField Yes This field is available in exporting in Zuora’s data sources and Data Query to filter the data.

Select a field name from the fields array.

No
userReferenceIdField No This field is available in exporting Zuora’s data sources and Data Query to filter the data.

Select a field name from the fields array.

No
subTypeField No This field is available in exporting in Zuora’s data sources and Data Query to filter the data.

Select a field name from the fields array.

No
fields Yes

An array containing field metadata of the custom payment method type.

Notes:

  • At least one field must be defined in the fields array for a custom payment method type. 
  • Up to 20 fields can be defined in the fields array for a custom payment method type.

See the below table for details.

Yes

Metadata definition for the "fields" array

Metadata Required Possible values Default value Description Editable
name Yes

An alphanumeric string starting with a capital letter, excluding JSON preserved characters e.g.  * \ ’ ”

Character limit: 18

n/a API name of this field No
label Yes

An alphanumeric string, excluding JSON preserved characters e.g.  * \ ’ ”

Character limit: 40

n/a The label that is used to refer to this field in the Zuora UI. Yes
type Yes
  • String, 
  • Date, 
  • DateTime,
  • Number, 
  • Boolean
n/a For Date type, ISO_LOCAL_DATE format is supported, such as 2011-12-03. The timezone is not expected for the Date type. For example, 2011-12-03+01:00 will be rejected.

For DateTime type, only ISO_OFFSET_DATE_TIME format is supported, such as 2011-12-03T10:15:30+01:00. Timezone must be included. String like 2011-12-03T10:15:30 or 2011-12-03T10:15:30+01:00[Europe/Paris] will be rejected.

If APM requires a Datetime with timezone or requires a Datetime type without timezone, please use String type for now.

No
index Yes Positive integer n/a The order of the field in this type.

Start from 1.

No
defaultValue No   Empty The default value of the field.

After the custom payment method type is published, you cannot change the default value anymore.

No
checksum Yes
  • true
  • false
n/a

The checksum value of a payment method is used to identify if this payment method is the same as another one, or if this payment method is altered to another new payment method.

Set this flag to true for the following scenarios:

  • The field should be part of checksum calculation.
  • The field is a critical differentiator for this type. 

For example, if you select the credit card number and expiration date as the checksum fields for the CreditCard payment method type, when you modified the expiration date, Zuora considers this payment method as a different payment method compared to the original one.

No
maxLength No Integer Empty A maximum length limitation of the field.

maxLength must be greater or equal to minLength.

After the custom payment method type is published, you can only increase the value of maxLength. Decreasing the value is not supported.

Yes
minLength No Integer Empty A minimal length limitation of the field.

0 <= minLength <= maxLength 

After the custom payment method type is published, you can only decrease the value of minLength. Increasing the value is not supported.

Yes
required Yes
  • true
  • false
n/a Specify if this field is required.

After the custom payment method type is published, you can only update it from true to false. Updating from false to true is not supported.

Yes
description No Any string Empty An explanation of this field. Yes
deprecated Yes
  • true
  • false
n/a Specify if this field is not used anymore.
  • A field is not allowed to be deleted, but it can be marked as deprecated
  • The API will not expect to get it for a new payment method, but no error will be reported if it exists in request.
  • The validation is not applied to it. 
  • Its value cannot be leveraged by other components.
Yes
editable Yes
  • true
  • false
n/a

A field can be updated through PUT API or UI if editable is true.

Note: If editable is set to falsefor a field, you can specify the value of this field in the UI and POST API when creating a payment method. However, after you created the payment method, you cannot edit this field through PUT API or UI.

Yes
visible Yes
  • true
  • false
n/a

A field can be retrieved through GET API or UI for displaying payment method details if visible is true.

Notes: 

  • If visible is set to false, you can still specify the value of this field in the UI and POST API when creating the payment method.
  • If visible is set to false and editable is set to true, this field is not accessible through GET API or UI for displaying details, but you can still see it and edit the value in the UI and PUT API when updating this payment method.
Yes
representer Yes
  • true
  • false
n/a

This flag determines which field(s) will be used for identifying this payment method in the Zuora UI, i.e. which field(s) will be shown for the Payment Method field in the UI.

Here are two examples:

PAY-OPMT-representer-1.png

PAY-OMPT-representer-2.png

Notes:

  • In one custom payment method type, set representer of at least one field to true
  • In one custom payment method type, representer of multiple fields can be true
  • A field with representer as true should not be a deprecated one. 
Yes

Example

Here is an example of the definition for a custom payment method type, showing five custom fields for a particular payment method.

{
 "name": "AmazonPay",
 "label": "Sample Amazon Pay",
 "tenantId": "12368",
 "entityId": "8239075c-d056-4fa2-b501-1cf9b53248ad",
 "methodReferenceIdField": "AmazonToken",
 "userReferenceIdField": "AmazonAccount",
 "subTypeField": "AmazonTokenType",
 "fields": [
   {
     "name": "AmazonToken",
     "label": "AmazonToken",
     "type": "string",
     "index": 1,
     "defaultValue": null,
     "checksum": true,
     "maxLength": 100,
     "minLength": 1,
     "required": true,
     "description": "The Token value",
     "deprecated": false,
     "editable": true,
     "visible": true,
     "representer": true
   },
   {
     "name": "AmazonTokenType",
     "label": "Amazon TokenType",
     "type": "string",
     "index": 2,
     "defaultValue": null,
     "checksum": true,
     "maxLength": 100,
     "minLength": 1,
     "required": true,
     "description": "The Type of Token, e.g. GoCardlessToken",
     "deprecated": false,
     "editable": true,
     "visible": true,
     "representer": true
   },
   {
     "name": "AmazonAccount",
     "label": "Amazon Account",
     "type": "string",
     "index": 3,
     "defaultValue": null,
     "checksum": false,
     "maxLength": 100,
     "minLength": 1,
     "required": true,
     "description": "A name of shopper account",
     "deprecated": false,
     "editable": true,
     "visible": true,
     "representer": false
     
   },
   {
     "name": "ShopperEmail",
     "label": "Shopper Email",
     "type": "string",
     "index": 4,
     "defaultValue": null,
     "checksum": false,
     "maxLength": 100,
     "minLength": 1,
     "required": false,
     "deprecated": false,
     "description": "An email of shopper",
     "editable": true,
     "visible": true,
     "representer": false
   },
   {
     "name": "ShoppingDate",
     "label": "Shopping Date",
     "type": "datetime",
     "index": 5,
     "defaultValue": null,
     "checksum": false,
     "maxLength": 100,
     "minLength": 1,
     "required": false,
     "deprecated": false,
     "description": "The date this shopper placed order",
     "editable": true,
     "visible": true,
     "representer": false
   }
 ]
}

What to do next

  1. After you have completed the definition file for your custom payment method type, submit a request to Zuora Global Support to enable the UPC and OPM services. Along with your request, enclose the following information.

    • The definition file of your custom payment method type
    • The target environment

    Once the review by Zuora is completed, Zuora will configure the custom payment gateway and payment method type to the requested environment.

  2. Set up a payment hub.