IBM FINANCIAL TRANSACTION MANAGER FOR ACH SERVICES. ZELLE RESTful API DOCUMENTATION

Transcription

1 IBM FINANCIAL TRANSACTION MANAGER FOR ACH SERVICES ZELLE RESTful API DOCUMENTATION 1

2 Before you use this information and the product it supports, read the information in "Notices" on page 170. Fourth edition (May 2018) Copyright International Business Machines Corporation 2017,2018. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 2

3 TABLE OF CONTENTS Commonly Used Fields... 7 CXCParticipant... 8 Attributes... 8 Key... 8 Fields... 8 Web Services Create (POST) Read (GET) Update (PUT) Delete (DELETE) Error Codes Possible Error Codes CXCToken Attributes Key Fields Web services Create (POST) Read (GET) Update (PUT) Delete (DELETE) Error Codes Possible Error codes CXCRecipient Attributes Key Fields Web Services Create (POST) Read (GET)

4 Update (PUT) Delete (DELETE) Error Codes Possible Error Codes CXCPayment Attributes Key Fields Web Services Create (POST) Read (GET) Update (PUT) Error Codes Possible Error Codes Payment Processing Error Codes CXCPaymentRequest Attributes Key Fields Web Services Create (POST) Read (GET) Update (PUT) Error Codes Possible Error Codes CXCParticipantView Attributes Fields Web Services Read (GET) Error Codes Possible Error Codes CXCTokenView Attributes Fields

5 Web Services Read (GET) Error Codes Possible Error Codes CXCMultiToken Attributes Key Fields Web services Update (PUT) CXCMultiRecipient Attributes Key Fields Web services Update (PUT) CXCPendingPayment Attributes Fields JSON CXCPendingPaymentRequest Attributes Fields JSON CXCTokenHistory Attributes Fields JSON CXCRequestorDetails Attributes Fields JSON CXCTokenData Attributes Key

6 Fields JSON CXCRecipientData Attributes Key Fields JSON CXCFraudDetectionData Attributes Fields JSON Errors Missing Required Field Invalid Value Specified Unauthorized Forbidden Not Found Invalid Key Internal Server Error Custom Errors Query Feature Parameters _where Parameter Notices Trademarks Terms and conditions for product documentation Applicability Personal use Commercial use Rights

7 COMMONLY USED FIELDS Name auditsource hostname organizationid participantid partnerid partnertype paymentid paymentprofileid token tokentype Description A 128-byte string that represents the audit source that is logged in the FTM audit log database tables NOTE: This value is the name of the logged in user or the system component invoking the web service. A 128-byte string that represents the name of the host (or IP address) that is logged in the FTM audit log database tables NOTE: This value is the IP address or host name from which the request originated. A 20-byte string used to identify identify an organization participant in the Zelle network. NOTE: While Zelle organization IDs are only 3 characters in length, FTM supports up to 20 characters for organization IDs. A 64-byte string used to uniquely identify a Zelle participant. NOTE: This value corresponds to the ID of the Zelle participant in the Zelle Shared Directory. This value may or may not be the same as the partner ID of the Zelle participant. When possible, it is recommended that the participant ID match the partner ID. A 20-byte string used to uniquely identify a Zelle participant in FTM. NOTE: This value corresponds to the ID of the Zelle participant in the FTM Shared Directory. This value may or may not be the same as the participant ID of the Zelle participant. When possible, it is recommended that the partner ID match the participant ID. An integer used to identify the partner type for the Zelle participant in FTM. NOTE: The value 1 represents a CustomerID and is currently the only supported value. A 12-byte string used to identify Zelle payments. NOTE: When creating a new payment, the paymentid is generated by FTM. A 255-byte string used to identify a payment profile for a Zelle participant. NOTE: When creating a new token, the paymentprofileid is generated by FTM. A 255-byte string that is a normalized value containing either the address or mobile phone number of a Zelle participant. A single-byte string used to identify the type of token ( E : or M : mobile ). NOTE: For additional terms, please refer to the Glossary in the most recent version of the Early Warning Services (EWS) Shared Directory specification. 7

8 CXCPARTICIPANT The CXCParticipant entity represents a Zelle participant. The base URL for this service is ATTRIBUTES KEY partnerid : partnertype FIELDS activateifexists Name Description Type Filter Sort Len Req auditsource channeltype customertype effectivedate The activateifexists attribute is used to reactivate a participant that already exists in the FTM database when invoking the CXCParticipant.Create web service. When set to Y, the CXCParticipant.Create web service does not fail if the participant already exists, but, instead, re-activates the existing participant. NOTE: This attribute only applies to the CXCParticipant.Create web service. The auditsource attribute is the name of the logged in user or the system component invoking the web service. NOTE: Any value can be specified by the calling application. The channeltype attribute is the channel (for example, mobile, web portal, etc.) from which the request originated. NOTE: Any value can be specified by the calling application. The customertype attribute represents the system customer type from the FTM CUSTOMER_TYPES table associated with this participant. This attribute may be used in the Risk Global Monitor Limit Change Conditions. The value can be either empty or a valid customer type, and will default blank if not provided. The effectivedate attribute represents the date on which the Zelle participant is active. The effective date defaults to immediate. The date should be in ISO 8601 format (for example T19:20:30+01:00). String No No 1 No String No No 128 Yes String No No 16 No String No No 1 No Timestamp No Yes N/A No 8

9 expirationdate frauddata hostname ingoodstanding instandingsince organizationid participantid participantname partnerid partnertype requestid The expirationdate attribute represents the date on which the Zelle participant is no longer active. The expiration date defaults to never. Date should be in ISO 8601 format (for example T19:20:30+01:00). The frauddata attribute is the list of CXCFraudDetectionData used for fraud detection. The hostname attribute is the IP address or host name from which the request originated. NOTE: Any value can be specified by the calling application. The ingoodstanding attribute represents if this participant is in good standing. This attribute may be used in the Risk Global Monitor Limit Change Conditions. The value can be either "Y" or "N", and will default to "Y" if not provided. The instandingsince attribute represents the date that the participant entered this good or bad standing. This attribute may be used in the Risk Global Monitor Limit Change Conditions. The value can be a valid date in ISO 8601 format (e.g T00:00:00+00:00), and will default to the current date if not provided. The organizationid attribute represents the 3-character identifier of the organization that the Zelle participant belongs to. NOTE: While Zelle organization IDs are only 3 characters in length, FTM supports up to 20 characters for organization IDs. The participantid attribute represents the ID of the Zelle participant. The participantname attribute represents the name of the Zelle participant. The partnerid attribute represents the participant ID of the Zelle participant in FTM. The partnertype attribute represents the partner type of the Zelle participant in FTM. 1 (CustomerID) The requestid attribute is the ID for the request made to this entity. Timestamp No Yes N/A No List of CXCFraudDetectionData No No N/A No String No No 128 No String No No 1 No Timestamp No Yes N/A No String Yes Yes 20 No String Yes Yes 64 Yes String Yes Yes 50 Yes String Yes Yes 20 Yes Integer Yes Yes N/A Yes String No No 255 No startoffirelationship The startoffirelationship attribute Timestamp No Yes N/A No 9

10 status vip represents the date of the beginning of the relationship with this Financial Institution. This attribute may be used in the Risk Global Monitor Limit Change Conditions. The value can be a valid date in ISO 8601 format (e.g T00:00:00+00:00), and will default to the current date if not provided. The status attribute represents the status of the Zelle participant. A (active) I (inactive) The VIP attribute represents if this participant is a VIP. This attribute may be used in the Risk Global Monitor Limit Change Conditions. The value can be either "Y" or "N", and will default to "N" if not provided. String Yes Yes 1 Yes String No No 1 No WEB SERVICES CREATE (POST) DESCRIPTION The CXCParticipant.Create web service adds a Zelle participant to the FTM database. The web service creates a single transaction limit check, a multi-day transaction limit check, and, if one does not already exist, adds the participant to the FTM database. It returns the location (URL) of the newly-created CXCParticipant with an HTTP status of 201 (CREATED). If the participant already exists in the FTM database and the attribute activateifexists is not set to Y, the web service will return the HTTP 500 error code with an error description that includes the duplicate participant custom error code for the CXCParticipant web service. If an error occurs, the web service will return one of the HTTP 4xx error codes. Or, if the error is specific to the web service, such as a duplicate participant, the web service will return the HTTP 500 error code with an error description that includes the relevant custom error code. REQUEST { auditsource : details, frauddata : [ See CXCFraudDetectionData JSON ], organizationid : FGB, 10

11 } participantid : Id123, partnerid : partner123, partnertype : 1, status : A RESPONSE { Location : urltonewparticipant } 11

12 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCRecipient.Create web service. MAIN FLOW: NEW PARTICIPANT 12

13 ALTERNATE FLOW: EXISTING PARTICIPANT 13

14 READ (GET) DESCRIPTION The CXCParticipant.Read web service retrieves Zelle participants from the FTM database. This service returns the CXCParticipants requested with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. QUERY This web service allows filtering, sorting, and paging. To read a single CXCParticipant, use the entire key. However, if reading more than one CXCParticipant, use the query feature without specifying a key. Refer to the Fields table above to identify which fields can be used for filtering and sorting. Below are examples of how to use each feature individually, as well as in combination with each other. FILTERING The example below shows how to filter results where partnerid is equal to id123 and partnertype is equal to 1. SORTING The example below shows how to sort results by effectivedate in ascending (+) order. PAGING The example below shows how to page results by specifying the range (inclusive). FILTERING, SORTING, AND PAGING The example below shows how to combine all of the above queries. The results are a list of no more than 10 CXCParticipants ordered by effectivedate, where the partnerid is equal to id123 and partnertype is equal to 1. _sort=+effectivedate&_range=0-9 REQUEST This web service does not accept any JSON input. RESPONSE 14

15 [ { auditsource : details, channeltype : mobile, customertype : C, effectivedate : T04:56: :00, expirationdate : T04:56: :00, frauddata : [ See CXCFraudDetectionData JSON ], ingoodstanding : Y instandingsince : T04:56: :00, hostname : hostinfo, organizationid : FGB, participantid : Id123, participantname : Bob, partnerid : Id123, partnertype : 1, requestid : reqid123, startoffirelationship : T04:56: :00, status : A, vip : N } ] UPDATE (PUT) DESCRIPTION The CXCParticipant.Update web service updates a Zelle participant in the FTM database This service returns the number of CXCParticipants updated with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. REQUEST { } auditsource : details, organizationid : FGB, participantid : Id123, status : A RESPONSE 15

16 { } rowsaffected : 1 DELETE (DELETE) DESCRIPTION The CXCParticipant.Delete web service deletes a Zelle participant from the FTM database. First, the web service invokes the Zelle Deactivate Customer call and passes the participant ID. Upon Zelle successfully deactivating the participant and all associated payment profiles and tokens, FTM asynchronously receives an On Customer Change (Deactivated), On Payment Profile Change (Inactive), and On Token Status Change (Inactive) Zelle call. Upon receipt of all three calls, FTM marks the payment profiles and tokens of participants as inactive and returns a successful response back to the user interface. A status of inactive designates a participant as having been deleted. This service returns the number of CXCParticipants deleted with an HTTP status of 200 (OK) if executed successfully, one of the HTTP 4xx error codes if an error occurs, or the HTTP 500 error code with an error description that contains a custom error code. REQUEST This service does not accept any JSON input. RESPONSE { } rowsaffected : 1 16

17 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCParticipant.Delete web service. MAIN FLOW: DELETE CUSTOMER, NO ACTIVE PAYMENTS 17

18 ALTERNATE FLOW: DELETE PARTICIPANT, OUTGOING PAYMENT (PENDING ACCEPTANCE) 18

19 ALTERNATE FLOW: DELETE PARTICIPANT, INCOMING PAYMENT (PENDING ACCEPTANCE) 19

20 ALTERNATE FLOW: DELETE PARTICIPANT, PENDING PAYMENTS AS INDICATION OF DEACTIVATION 20

21 ALTERNATE FLOW: RECIPIENT DELETED, NO ACTIVE PAYMENTS ERROR CODES POSSIBLE ERROR CODES Error Code Description Invalid Configuration value for <key>: <value> Reason: <msg> General failure while adding a new participant A participant with the supplied partnerid and partnertype already exists The participant is inactive No participant matching the supplied partnerid and partnertype exists No participant matching the supplied participantid and organizationid exists General failure while adding a new partner General failure while adding multi-day transaction limit to partner General failure while adding single transaction limit to partner Failure while deleting participant. <reason> A participant with the supplied participantid and organizationid already exists The partnertype specified does not exist 21

22 No organization with the supplied organizationid exists No customer type matching the supplied customertype exists The ingoodstanding field can only have a value of Y or N The vip field can only have a value of Y or N 22

23 CXCTOKEN A CXCToken entity represents a Zelle token and its associated Zelle payment profile. The base URL for this service is ATTRIBUTES KEY partnerid : partnertype : participantid : token : paymentprofileid FIELDS acceptancemode accountbankcode accountnumber accounttype Name Description Type Filter Sort Len Req auditsource canreceiveexpeditedpayment The acceptancemode attribute indicates the acceptance mode of the payment profile associated with a Zelle participant. A (auto) M (manual) The accountbankcode is the bank code (for example, routing transit number) associated with the payment profile of a Zelle participant. The accountnumber attribute is the account number associated with the payment profile of a Zelle participant. The accounttype attribute is the account type associated with the payment profile of a Zelle participant. C (checking) S (savings) The auditsource attribute is the name of the logged in user or the system component invoking the web service. NOTE: Any value can be specified by the calling application. The canreceiveexpeditedpayment attribute indicates whether or not the participant associated with the payment profile can receive expedited payments. Y (yes) N (no) String Yes Yes 1 No String Yes Yes 20 Yes String Yes Yes 35 Yes String Yes Yes 1 Yes String No No 128 Yes String Yes No 1 No 23

24 changereason NOTE: The default value is Y The changereason attribute is the reason of a change to the token associated with the payment profile of a Zelle participant. U (user-action) C (carrier-disconnect) String Yes No 1 No channeltype firstname The channeltype attribute is the channel (for example, mobile, web portal, etc.) from which the request originated. NOTE: Any value can be specified by the calling application The firstname attribute is the first name of the participant associated with the payment profile. NOTE: This field is required when registering a token (Create). If attempting an update, the first name is required when changing a token from Inactive to Active. String No No 16 No String Yes Yes 50 Conditional; See Description frauddata The frauddata attribute is the list of CXCFraudDetectionData used for fraud detection. List of CXCFraudDetectionData No No N/A No hostname ignorenamematching iscustomerservice The hostname attribute is the IP address or host name from which the request originated. NOTE: Any value can be specified by the calling application. The ignorenamematching attribute indicates whether or not name matching logic is used when performing the Match Recipient operation for a Zelle participant associated with the payment profile. Default value is Y (yes). NOTE: Setting this field to Y (yes) will make firstname and lastname not required. Y (yes) N (no) The iscustomerservice attribute indicates whether or not the participant is a customer service representative. Y (yes) N (no) NOTE: This field must be Y (yes) 24 String No No 128 No String Yes No 1 Conditional; See Description String No No 1 No

25 lastname organizationid participantid partnerid partnertype paymentprofileid paymentprofilestatus requestid when updating any personal payment profile field. The lastname attribute is the last name of the participant associated with the payment profile. NOTE: This field is not required when ignorenamematching is Y (yes). The organizationid attribute is the ID of the organization used to uniquely identify a Zelle participant across organizations. NOTE: This field defaults to the organizationid of the Zelle participant with the given partnerid and partnertype. NOTE: While Zelle organization IDs are only 3 characters in length, FTM supports up to 20 characters for organization IDs. The participantid attribute is the organization-unique ID of a Zelle participant, spanning all of their payment profiles and tokens. The partnerid attribute represents the participant ID of the Zelle participant in FTM. The partnertype attribute represents the partner type of the Zelle participant in FTM. 1 (CustomerID) The paymentprofileid attribute is the organization-unique identifier of the payment profile of a Zelle participant. NOTE: generated must be passed as the paymentprofileid value when performing a Create for the CXCToken entity in order for the paymentprofileid to be auto generated and returned in the response. The paymentprofilestatus attribute is the status of the payment profile associated with a Zelle participant. A (active) I (inactive) The requestid attribute is the ID for the request made to this entity. String Yes Yes 50 Conditional; See Description String Yes Yes 20 No String Yes Yes 64 Yes String Yes Yes 20 Yes Integer Yes Yes N/A Yes String No No 255 Yes String Yes Yes 1 Yes String No No 255 No 25

26 token tokenstatus tokentype The token attribute is the token associated with the payment profile of a Zelle participant. The tokenstatus attribute is the status of the token associated with the payment profile of a Zelle participant. A (active) I (inactive) The tokentype attribute is the type of token associated with the payment profile of a Zelle participant. E ( ) M (mobile) String Yes Yes 255 Yes String Yes Yes 1 Yes String Yes Yes 1 Yes WEB SERVICES CREATE (POST) This service returns the location (URL) of the newly-created CXCToken with an HTTP status of 201 (CREATED) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCToken.Create web service registers a token for a participant present in the FTM database. To register a new participant token, the FTM web service checks to ensure that the maximum number of active tokens has not been reached and, if not, invokes four web services. First, the web service invokes the Zelle Match Recipient to determine if the token already exists. If the token does not already exist, the CXCToken.Create web service calls the Client Service to refresh the fraud detection data provided from the user interface. Next, a call is made to the fraud application to perform fraud detection, storing the fraud check result in the FTM database. If no fraud is detected, the web service creates a payment profile ID and invokes the Zelle Change Token Status web service. For a new participant token, Zelle creates the payment profile and returns a response to FTM to indicate that the participant token was successfully added. Then, the CXCToken.Create web service updates the payment profile and associated token to the FTM database and returns a response to the user interface to indicate that the participant token was successfully added. FTM then calls the Client Service to notify the participant of successful token registration. REQUEST { 26

27 accountbankcode : bank123, accountnumber : acct123, accounttype : C, auditsource : details, frauddata : [ See CXCFraudDetectionData JSON ], participantid : participant123, partnerid : partner123, partnertype : 1, paymentprofileid : generated, paymentprofilestatus : A token : token@my .com, firstname : Jim, tokenstatus : A, tokentype : E } RESPONSE { Location : urltonewtoken } 27

28 SEQUENCE DIAGRAMS MAIN FLOW: NEW PARTICIPANT TOKEN 28

29 ALTERNATE FLOW: MAXIMUM NUMBER OF ACTIVE TOKENS ALTERNATE FLOW: INVALID TOKEN 29

30 ALTERNATE FLOW: EXISTING PARTICIPANT TOKEN ACTIVE IN ZELLE 30

31 ALTERNATE FLOW: FRAUD DETECTED 31

32 ALTERNATE FLOW: POSSIBLE FRAUD DETECTED FRAUD DETECTED 32

33 ALTERNATE FLOW: POSSIBLE FRAUD DETECTED NO FRAUD DETECTED 33

34 READ (GET) This service returns the CXCTokens requested with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCToken.Read web service retrieves a Zelle token from the FTM database. This service returns the CXCTokens requested with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. QUERY This service allows filtering, sorting, and paging. To read a single CXCToken, use the entire key. However, if reading more than one CXCToken, use the query feature without specifying a key. Refer to the Fields table above to identify which fields can be used for filtering and sorting. Below are examples of how to use each feature individually, as well as in combination with each other. FILTER The example below shows how to filter results where partnerid is equal to id123 and partnertype is equal to 1. SORT The example below shows how to sort results by organizationid in ascending (+) order. PAGING The example below shows how to page results by specifying the range (inclusive). FILTER, SORT, AND PAGING The example below shows how to combine all of the above queries. The results are a list of no more than 10 CXCTokens ordered by organizationid, where the partnerid is equal to id123 and partnertype is equal to 1. _sort=+organizationid&_range=0-9 REQUEST This service does not accept any JSON input. RESPONSE 34

35 [ { acceptancemode : A, accountbankcode : bank123, accountnumber : acct123, accounttype : C, auditsource : details, canreceiveexpeditedpayment : Y, channeltype : mobile, changereason : U, firstname : John, frauddata : [ See CXCFraudDetectionData JSON ], hostname : hostinfo, ignorenamematching : N, iscustomerservice : N, lastname : Doe, organizationid : org123, participantid : participant123, partnerid : partner123, partnertype : 1, paymentprofileid : profile123, paymentprofilestatus : A, requestid : reqid123, token : token@my .com, tokenstatus : A, tokentype : E } ] UPDATE (PUT) This service returns the number of CXCTokens updated with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCToken.Update web service can be used to update the profile information of a Zelle token or to change the token status. 35

36 The CXCToken.Update web service begins by validating the requested operation. If the token status has changed to active, the web service validates that the maximum number of tokens allowed has not already been reached. The web service also validates that the payment profile status has not been changed. If the CXCToken profile information has been updated, the web service validates that this operation is allowed before invoking Zelle Update Personal Payment Profile. If the call was successful, the web service then invokes Zelle Change Token Status if the token status has been updated. If everything has completed successfully, the changes are stored in the database before returning a success response to the user interface. This service returns the number of CXCTokens updated with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. REQUEST { } accountbankcode : bank123, accountnumber : acct123, accounttype : C, auditsource : details, paymentprofilestatus : A, tokenstatus : A, tokentype : E RESPONSE { rowsaffected : 1 } 36

37 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCToken.Update web service. MAIN FLOW: PARTICIPANT REQUESTS TOKEN TRANSFER 37

38 ALTERNATE FLOW: PARTICIPANT TOKEN TRANSFER VIA CUSTOMER SERVICE 38

39 ALTERNATE FLOW: PAYMENT PROFILE STATUS CHANGED 39

40 ALTERNATE FLOW: MAXIMUM NUMBER OF TOKENS REACHED DELETE (DELETE) This service returns the number of CXCTokens deleted with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCToken.Delete web service deletes a Zelle token from the FTM database. First, the web service validates that the requested operation is allowed. If it is, the web service invokes the Zelle Delete Payment Profile web service to remove the payment profile and its associated token. If the request was successful, the web service updates the database and returns a successful response to the user interface. A payment profile status of inactive designates a token as having been deleted. This service returns the number of CXCTokens deleted with an HTTP status of 200 (OK) if executed successfully, one of the HTTP 4xx error codes if an error occurs, or the HTTP 500 error code with an error description that contains a custom error code. 40

41 REQUEST This service does not accept any JSON input. RESPONSE { rowsaffected : 1 } 41

42 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCToken.Delete web service. MAIN FLOW: DELETE ACTIVE TOKEN, NO ACTIVE PAYMENTS OR PAYMENT REQUESTS 42

43 ALTERNATE FLOW: PARTICIPANT OUTGOING PAYMENT (SENT) 43

44 ALTERNATE FLOW: PARTICIPANT INCOMING PAYMENT (PENDING ACCEPTANCE) 44

45 ALTERNATE FLOW: PARTICIPANT INCOMING PAYMENT (SENT) 45

46 ALTERNATE FLOW: PROFILE NOT FOUND ALTERNATE FLOW: TOKEN NOT FOUND 46

47 ALTERNATE FLOW: NOT AUTHORIZED ERROR CODES POSSIBLE ERROR CODES Error Code Description Invalid Configuration value for <key>: <value> Reason: <msg> General failure while adding a new token No participant matching the supplied partnerid and partnertype exists The participant is inactive The maximum number of tokens has been reached The value of paymentprofileid was not equal to "generated" The token <name> is already active in Zelle The payment profile status cannot be changed during an update entity operation 47

48 The field <name> can only be updated by a customer service representative The field organizationid was not specified for the given participant The token <token> does not match the tokentype <tokentype> The value of <name> can only contain integers AccountBankCode can only have a length of 8 or 9 digits No token matching the supplied key could be found The payment profile is inactive The field organizationid cannot be changed during an update operation 48

49 CXCRECIPIENT A CXCRecipient entity represents the CXCRecipient of a CXCParticipant. The base URL for this service is ATTRIBUTES KEY partnerid : partnertype : token : currentrecipientfirstname : currentrecipientlastname FIELDS acceptancemode activateifexists Name Description Type Filter Sort Len Req auditsource canreceiveexpeditedpayment The acceptancemode attribute indicates the acceptance mode of the payment profile associated with a Zelle recipient. This is a read-only attribute that represents a value provided by Zelle. A (auto) M (manual) The activateifexists attribute is used to re-activate a participant that already exists in the FTM database when invoking the CXCRecipient.Create web service. When set to Y, the CXCRecipient.Create web service does not fail if the recipient already exists, but, instead, reactivates the existing recipient. NOTE: This attribute only applies to the CXCRecipient.Create web service. The auditsource attribute is the name of the logged in user or the system component invoking the web service. NOTE: Any value can be specified by the calling application. The canreceiveexpeditedpayment attribute indicates whether a Zelle recipient can receive expedited payments. This is a read-only attribute that represents a value provided by Zelle. Y (yes) N (no) String Yes Yes 1 No String No No 1 No String No No 128 Yes String Yes No 1 Conditional; See Description 49

50 channeltype currentrecipientfirstname currentrecipientlastname enforcenamematching firstname fraudcheckreason The channeltype attribute is the channel (for example, mobile, web portal, etc.) from which the request originated. NOTE: Any value can be specified by the calling application The currentrecipientfirstname attribute is the provided first name of the recipient. NOTE: The default value is an empty string. The currentrecipientlastname attribute is the provided last name of the recipient. NOTE: The default value is an empty string. The enforcenamematching attribute is used as a flag to indicate whether name matching is enforced. If the value Y is passed, the status of the recipient token is determined by the matchsuccessful flag returned in the Match Recipient response. For example, if match-successful is false, the status is returned as inactive. However, if a value of N is passed, name matching is not taken into account when determining the status of the recipient token. NOTE: The default value for this attribute is Y. The firstname attribute is the optional first name of a Zelle recipient. NOTE: This field is not required when ignorenamematching is Y (yes). NOTE: This field is used when invoking the Zelle MatchRecipient web service. The value returned in the Zelle MatchRecipient response is the value stored in the FTM database. The fraudcheckreason attribute is a description of the reason for the current fraud check status of a Zelle recipient. This is a read-only attribute that represents a value String No No 16 No String Yes Yes 50 No String Yes Yes 50 No String No No 1 No String Yes Yes 50 Conditional; See Description String No No 255 No 50

51 fraudcheckstatus fraudcheckversion frauddata hostname ignorenamematch isdeleted ismatchrecipientpassthrough provided by a fraud detection application. The fraudcheckstatus attribute is the status of the fraud check of a Zelle recipient. This is a read-only attribute that represents a value provided by a fraud detection application. Y (yes) N (no) U (undetermined) The fraudcheckversion attribute is the version of the fraud check. This is a read-only attribute that represents a value provided by a fraud detection application. The frauddata attribute is the list of CXCFraudDetectionData used for fraud detection. The hostname attribute is the IP address or host name from which the request originated. NOTE: Any value can be specified by the calling application. The ignorenamematch attribute indicates whether or not name matching logic is used when performing the Match Recipient operation for a Zelle recipient. This is a read-only attribute that represents a value provided by Zelle. NOTE: The value returned in the Zelle MatchRecipient response is the value stored in the FTM database. The isdeleted attribute is a flag that represents whether the Recipient has been deleted by FTM. Y (yes) N (no) NOTE: If this value is Y, then the recipient has been deleted internally by FTM. The ismatchrecipientpassthrough attribute is a flag that indicates whether the match recipient call will be made to reveal information about a recipient. 51 String Yes No 1 No String Yes No 128 No List of CXCFraudDetectionData No No N/A No String No No 128 No String Yes No 1 No String Yes Yes 1 No String No No 1 No

52 isoutofnetwork lastname newrecipientfirstname newrecipientlastname organizationid NOTE: No recipient will be created (stored in the database). NOTE: Setting this field to Y (yes) will result in this functionality taking place. The isoutofnetwork attribute indicates whether the recipient is an out-of-network recipient. This is a read-only attribute that is determined by the ONS values provided by Zelle. NOTE: Y (yes) indicates that the recipient is out-of-network. The lastname attribute is the optional last name of a Zelle recipient. NOTE: This field is not required when ignorenamematching is Y (yes). NOTE: This field is used when invoking the Zelle MatchRecipient web service. The value returned in the Zelle MatchRecipient response is the value stored in the FTM database. The newrecipientfirstname attribute is the provided first name of the recipient to be used to update the currentrecipientfirstname attribute. NOTE: This field is only applicable when updating the first name of the recipient. The newrecipientlastname attribute is the provided first name of the recipient to be used to update the currentrecipientlastname attribute. NOTE: This field is only applicable when updating the first name of the recipient. The organizationid attribute is the ID of the organization to which a Zelle recipient belongs. This is a read-only attribute that represents a value provided by Zelle. NOTE: While Zelle organization IDs are only 3 characters in length, String Yes Yes 1 No String Yes Yes 50 Conditional; See Description String No No 50 No String No No 50 No String Yes Yes 20 No 52

53 partnerid partnertype paymentprofileid recipientid requestid status token tokengroup FTM supports up to 20 characters for organization IDs. The partnerid attribute represents the participant ID of the Zelle participant in FTM. The partnertype attribute represents the partner type of the Zelle participant in FTM. 1 (CustomerID) The paymentprofileid attribute is the organization-unique identifier of the payment profile of a Zelle recipient. This is a read-only attribute that represents a value provided by Zelle. The recipientid attribute is the participant ID of a Zelle recipient. This is a read-only attribute that represents a value provided by Zelle. The requestid attribute is the ID for the request made to this entity. The status attribute is the status of the token associated with a Zelle recipient. This is a read-only attribute that represents a value provided by Zelle. A (active) I (inactive) U (unknown) NOTE: U (unknown) is not a status supported by Zelle. However, when the Zelle Match Recipient call returns a value of false for match-successful, the status of a recipient is defaulted to U (unknown). The token attribute is the token of a Zelle recipient. NOTE: This field is used when invoking the Zelle MatchRecipient web service. The value returned in the Zelle MatchRecipient response is the value stored in the FTM database. The tokengroup attribute is used to group recipients by their tokens. 53 String Yes Yes 20 Yes Integer Yes Yes N/A Yes String Yes Yes 255 No String Yes Yes 64 No String No No 255 No String Yes Yes 1 No String Yes Yes 255 Yes String Yes Yes 64 No tokentype The tokentype attribute is the String Yes Yes 1 Yes

54 type of token associated with the payment profile of a Zelle recipient. E ( ) M (mobile) This is a read-only attribute that represents a value provided by Zelle. WEB SERVICES CREATE (POST) This service returns the location (URL) of the newly-created CXCRecipient with an HTTP status of 201 (CREATED) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCRecipient.Create web service is used to find and add the payment profile information of a recipient based on a token. First, the CXCRecipient.Create web service invokes the Zelle Match Recipient token web service, passing the token (and last name and/or first name if provided) to determine if the token exists. If a matching active token is found, the Zelle Match Recipient token web service returns the payment profile associated with the token and then calls the Client Service to refresh the fraud detection data provided from the user interface. Next, a call is made to the fraud application to perform fraud detection. If no fraud is detected, the associated payment profile is then stored in the FTM database as a recipient of the participant. The CXCRecipient.Create web service returns a response to the user interface to indicate that the recipient was successfully added. FTM then calls the Client Service to notify the participant of successful recipient addition. REQUEST { } auditsource : details, currentrecipientfirstname : Jane, currentrecipientlastname : Doe, frauddata : [ See CXCFraudDetectionData JSON ], partnerid : partner123, partnertype : 1, token : token@my .com, tokentype : E RESPONSE 54

55 { } Location : urltonewtoken 55

56 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCRecipient.Create web service. MAIN FLOW: ADD NEW RECIPIENT 56

57 ALTERNATE FLOW: ADD UNKNOWN RECIPIENT 57

58 ALTERNATE FLOW: RECIPIENT ALREADY EXISTS 58

59 ALTERNATE FLOW: CONNECTION NOT ALLOWED 59

60 ALTERNATE FLOW: FRAUD DETECTED 60

61 ALTERNATE FLOW: POSSIBLE FRAUD DETECTED FRAUD DETECTED 61

62 ALTERNATE FLOW: POSSIBLE FRAUD DETECTED NO FRAUD DETECTED 62

63 READ (GET) DESCRIPTION The CXCRecipient.Read web service retrieves a Zelle recipient from the FTM database. This service returns the CXCRecipients requested with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. QUERY This service allows filtering, sorting, and paging. To read a single CXCRecipient, use the entire key. However, if reading more than one CXCRecipient, use the query feature without specifying a key. Refer to the Fields table above to identify which fields can be used for filtering and sorting. Below are examples of how to use each feature individually, as well as in combination with each other. FILTER The example below shows how to filter results where partnerid is equal to id123 and partnertype is equal to 1. SORT The example below shows how to sort results by organizationid in ascending (+) order. PAGING The example below shows how to page results by specifying the range (inclusive). FILTER, SORT, AND PAGING The example below shows how to combine all of the above queries. The results are a list of no more than 10 CXCRecipients ordered by organizationid, where the partnerid is equal to id123 and partnertype is equal to 1. _sort=+organizationid&_range=0-9 REQUEST This service does not accept any JSON input. RESPONSE [ { acceptancemode : A, auditsource : details, canreceiveexpeditedpayment : Y, 63

64 channeltype : mobile, firstname : John, fraudcheckreason : reason, fraudcheckstatus : Y, fraudcheckversion : version123, frauddata : [ See CXCFraudDetectionData JSON ], hostname : hostinfo, ignorenamematch : N lastname : Doe, onsaccountnumber : onsacct123, onsaccounttype : accttype123, onsencryptionkey : encrypt123, onsencryptionversion : 1, onsroutingnumber : route123, organizationid : org123, partnerid : partner123, partnertype : 1, paymentprofileid : profile123, recipientid : recipient123, requestid : abc123, status : A, token : token@my .com, tokengroup : grp1, tokentype : E } ] UPDATE (PUT) This service returns the number of CXCRecipients updated with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. DESCRIPTION The CXCRecipient.Update web service is used to retrieve the current, up-to-date information of a recipient from Zelle. First, the CXCRecipient.Update web service checks whether the ignorenamematching flag was passed. If the flag was not passed, it is defaulted to Y and the web service then invokes the Zelle Match Recipient web service, passing the token to retrieve all current data of that token. If a matching active token is found, the Zelle Match Recipient web service returns the payment profile associated with the token. Next, the web service overwrites all read-only attributes in the database using the attribute values retrieved from 64

65 Zelle. Optionally, the web service updates the tokengroup, recipientfirstname, and recipientlastname attributes if values were passed as parameters. The CXCRecipient.Update web service returns a response to the user interface to indicate the number of rows affected by the update. Note: In order to update the currentrecipientfirstname and currentrecipientlastname attributes, the value for currentrecipientfirstname must be passed using the newrecipientfirstname attribute and the value for currentrecipientlastname must be passed using the newrecipientlastname attribute. Note: When ignorenamematching is N, the firstname and lastname values are retrieved from the database to be sent as part of the request for Zelle Match Recipient. If new values are passed as parameters using the firstname and lastname attributes, these values are used as part of the request for Zelle Match Recipient. REQUEST { } auditsource : details, tokengroup : 1, newrecipientfirstname : John, newrecipientlastname : Doe RESPONSE { rowsaffected : 1 } 65

66 SEQUENCE DIAGRAMS Below are the sequence diagrams that show the flow of data and operations performed for the CXCRecipient.Update web service. MAIN FLOW: UPDATE RECIPIENT WITH IGNORE NAME MATCHING Y 66

67 ALTERNATE FLOW: UPDATE RECIPIENT WITH IGNORE NAME MATCHING N 67

68 ALTERNATE FLOW: NAME MATCHING FAILS DELETE (DELETE) DESCRIPTION The CXCRecipient.Delete web service deletes a Zelle recipient from the FTM database. The CXCRecipient.Delete web service finds the associated CXCRecipients in the database and marks their isdeleted attribute to Y. If the operation is successful, the CXCRecipient.Delete web service returns a success response to the user interface. This service returns the number of CXCRecipients deleted with an HTTP status of 200 (OK) if executed successfully, or one of the HTTP 4xx error codes if an error occurs. REQUEST This service does not accept any JSON input. RESPONSE { 68

69 } rowsaffected : 1 ERROR CODES POSSIBLE ERROR CODES Error Code Description General failure while adding a new recipient No participant matching the supplied partnerid and partnertype exists The participant is inactive Failed to add recipient due to duplicate recipient detection Failure while calling Zelle Match Recipient with reason "invalid-token" Failure while calling Zelle Match Recipient with reason "connection-notallowed" <name> is a read-only attribute <name> is part of the key and cannot be updated No recipient matching the supplied partnerid, PartnerType, token, currentrecipientfirstname and currentrecipientlastname exists firstname or lastname attribute is required when ignorenamematching is N General failure while adding a new recipient during CXCMultiRecipient General failure while deleting a recipient during CXCMultiRecipient General failure while updating a recipient during CXCMultiRecipient <name> is not allowed when performing a create operation Failed to update recipient due to duplicate recipient detection <token> is an invalid mobile number 69

70 CXCPAYMENT A CXCPayment entity represents a Zelle payment made to a CXCRecipient. The base URL for this service is ATTRIBUTES KEY partnerid : partnertype : paymentid FIELDS accountbankcode accountnumber accounttype Name Description Type Filter Sort Len Req The accountbankcode is the bank code (for example, routing transit number) associated with the payment profile of a Zelle participant. NOTE: This field is required if participanttoken or participantpaymentprofileid and participantorganizationid are not specified. NOTE: Fields accountnumber and accounttype must be specified in conjunction with this field. The accountnumber attribute is the account number associated with the payment profile of a Zelle participant. NOTE: This field is required if participanttoken or participantpaymentprofileid and participantorganizationid are not specified. NOTE: Fields accountbankcode and accounttype must be specified in conjunction with this field. The accounttype attribute is the account type associated with the payment profile of a Zelle participant. C (checking) S (savings) NOTE: This field is required if participanttoken or participantpaymentprofileid and participantorganizationid are not 70 String Yes Yes 20 Conditional; See Description String Yes Yes 35 Conditional; See Description String Yes Yes 1 Conditional; See Description

71 achreturncode amount auditsource channeltype checkforduplicates declinememo enforcematchsuccessful expedited specified. NOTE: Fields accountbankcode and accountnumber must be specified in conjunction with this field. The achreturncode attribute is the return code of the ACH for this payment. The amount attribute is the dollar amount to be used for the payment. The auditsource attribute is the name of the logged in user or the system component invoking the web service. NOTE: Any value can be specified by the calling application. The channeltype attribute is the channel (for example, mobile, web portal, etc.) from which the request originated. NOTE: Any value can be specified by the calling application The checkforduplicates attribute is a flag which determines whether or not to perform duplicate payment checking. The default value is Y (yes). Y (yes) N (no) The declinememo attribute is the memo for the decline reason. The enforcematchsuccessful attribute requires that the matchsuccessful element in a Zelle MatchRecipient response have a value of true in order for a payment to be sent. To ignore the match-successful element, set the enforcematchsuccessful attribute to N (no). The default value is Y (yes). The expedited attribute is the flag indicating if the payment is expedited. Default value is N (no). Y (yes) N (no) String No No 3 No Decimal Yes Yes N/A Yes String No No 128 Yes String No No 16 No String No No 1 No String No No 200 No String No No 1 No String Yes No 1 No expirationtime The expirationtime attribute is the Timestamp No No N/A No 71