Download - Guide for Wisely Pay by ADP Card APIs
Guide for Wisely Pay by ADP Card APIs
ADP Copyright Information
ADP, the ADP logo, Always Designing for People, and Wisely Pay by ADP are trademarks of ADP, LLC.
All other trademarks are the property of their respective owners.
Copyright © 2019 ADP, LLC. ADP Proprietary and Confidential - All Rights Reserved. These materialsmay not be reproduced in any format without the express written permission of ADP, LLC.
ADP provides this publication “as is” without warranty of any kind, either expressed or implied, including,but not limited to, the implied warranties of merchantability or fitness for a particular purpose. ADP is notresponsible for any technical inaccuracies or typographical errors which may be contained in thispublication. Changes are periodically made to the information herein, and such changes will beincorporated in new editions of this publication. ADP may make improvements and/or changes in theproduct and/or the programs described in this publication.
Publication Date: 9/10/2019 10:34 AM
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
ContentsOverview .................................................................................................................................................. 1Before You Begin ..................................................................................................................................... 2Enroll Your Employees for Wisely Pay by ADP Cards .............................................................................. 3
Obtaining Organization Location .......................................................................................................... 3Application Scope ............................................................................................................................. 3Output ............................................................................................................................................... 4Full Schema and Client URL (cURL) Samples .................................................................................. 4
Obtaining Funding Accounts................................................................................................................. 5Application Scope ............................................................................................................................. 5Sensitive Information Masking .......................................................................................................... 5API Proxy Caches the Responds ...................................................................................................... 5Output ............................................................................................................................................... 6Full Schema And cURL Samples ...................................................................................................... 6
Validating the Pay Card Account .......................................................................................................... 6Application Scope ............................................................................................................................. 7Option 1: Validating by Using the Account Number ........................................................................... 7Option 2: Validate by Using Proxy ID ................................................................................................ 9Possible Values for Card Status...................................................................................................... 11Full Schema and cURL Samples .................................................................................................... 11
Submitting Wisely Pay by ADP Card Enrollment ................................................................................ 11Response ....................................................................................................................................... 11Application Scope ........................................................................................................................... 12Enroll an Instant Issue Card Option 1 - Using Proxy ID ................................................................... 12Enroll an Instant Issue Card Option 2 - Using Account Number ...................................................... 14Enroll a Mail Ordered Card ............................................................................................................. 16Full Schema and cURL Samples: ................................................................................................... 18
Funding Wisely Pay by ADP Cards .................................................................................................... 19Application Scope ........................................................................................................................... 19Option 1: Instant Funding by Using the Employee Account Number ............................................... 19Option 2: Instant Funding with Employee ID ................................................................................... 20Full Schema And cURL Samples .................................................................................................... 21
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Reversing Funds from Wisely Pay by ADP Cards .............................................................................. 22Application Scope ........................................................................................................................... 22Option 1: Reverse Fund by Using Employee Account Number ....................................................... 23Option 2: Reverse fund with Employee ID ....................................................................................... 23Full Schema And cURL Samples: ................................................................................................... 24
Searching for Cardholders .................................................................................................................. 25Search for Cardholders by Request Body ....................................................................................... 25$filter ............................................................................................................................................... 25$order ............................................................................................................................................. 26$skip and $top ................................................................................................................................ 26Full Schema and cURL Samples .................................................................................................... 30
Appendix: Field Names and Descriptions ............................................................................................... 30
Overview 1
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
OverviewThe Wisely Pay by ADP card Application Programming Interfaces (APIs) includes a library of APIs for theWisely Pay by ADP card. This guide helps you create your first Wisely Pay by ADP card managementapplication in your environment.
The Wisely Pay card APIs allow you to build your own application to do the following:
· Enroll employees for Wisely Pay by ADP cards by practitioners.· Issue instant funding to employees’ Wisely Pay by ADP cards.
Before You Begin 2
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Before You BeginBefore you begin working with Wisely Pay by ADP card APIs, do the following:
· Familiarize yourself with the Hypertext Transfer Protocol (HTTP), RESTful (RepresentationalState Transfer) web services, JavaScript Object Notation (JSON), and Open Authorization(OAuth). You will also need an SSL Certification along with an OAuth2 Client ID and ClientSecret. See Overview Of The End-user Authorization Process for more information.
· Connect to the ADP API Gateway. The pre-build libraries that ADP Marketplace offers allow youto focus on your application functionality rather than interfacing with ADP. The code examplesand tutorial are available in various programming languages and can be accessed here. You mayalso find ADP user information module sample code useful: https://github.com/adplabs/adp-userinfo-node.
· Register with Marketplace. You will need to obtain a Client ID and Client secret. The Wisely Paytest cards are set up in our staging environment. Both the production environment and stagingenvironment need their own Client ID and Client Secret. If you don’t have this information, contactyour client representative and you should receive one set of Client ID and Client Secret for eachenvironment.
o Production Uniform Resource Locator (URL) begins with https://api.adp.com.o Staging URL begins with https://iat-api.adp.com.
· Access ADP APIs. You will need to generate a Certificate Signing Request (CSR). See Generatea Signing Request and Certificate Signing Request for more information. Send the generatedCSR to your client representative as instructed in one of the steps.
· Obtain test proxy IDs for instant issue cards from your client representative. You may need themto test instant issue card enrollment in ADPs staging environment before enrolling to theproduction environment. The enrollment conducted in the staging environment is to simulate theenrollment in the production environment and the actual enrollment will not take place.
Enroll Your Employees for Wisely Pay by ADP Cards 3
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Enroll Your Employees for Wisely Pay by ADPCardsBy using ADP APIs, you can build your own application to enroll your employees in the Wisely Pay byADP card for your employees. Create your first Wisely Pay by ADP card enrollment application todaycompleting these steps, which are documented in more detail in the following sections:
1. Obtain organization locations.2. Obtain funding accounts.3. Validate pay card account.4. Submit Wisely Pay by ADP card enrollment.5. Fund Wisely Pay by ADP cards.6. Reverse fund from Wisely Pay by ADP cards.7. Search for cardholders.
Note:Steps One through Six are optional. They are provided to increase the accuracy of thedata that you will use in enrollment. You can skip these steps if you already have thepayload data required.
Obtaining Organization Location
As part of the Wisely Pay by ADP card setup, your implementation specialist will set up single or multiplelocations for your company. Enrollment submission requires the Location ID for each employee. Alocation ID is a unique identifier that identifies the location, such as a branch, through which the WiselyPay by ADP card was issued.
The Pay Card Organization-Locations API returns all the Wisely Pay locations and the details of eachlocation that you have setup for the Wisely Pay by ADP card.
The API returns a collection of Wisely Pay by ADP card locations.
Application ScopeThe canonical uniform resource identifier (URI) corresponding to the API needs to be added in theConsumer Application Registry (CAR) for the subscription following which a user can access this APIand make successful API calls.
The following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/core/v1/paycard/organization-locations
Enroll Your Employees for Wisely Pay by ADP Cards 4
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
OutputSchema Location Field Name
Name
locations > namecode > codeValue Location ID
locations > namecode > longName Location Name
Address
locations > addresses > lineOne Address Line One
locations > addresses > cityName City
locations > addresses > countrySubdivisionLevel1 > codeValue State
locations > addresses > postalCode Zip
Full Schema and Client URL (cURL) SamplesSee Paycard Organization Locations for more information.
Back to Top of Section
Enroll Your Employees for Wisely Pay by ADP Cards 5
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Obtaining Funding AccountsAn instant funding account is an escrow-style account set up in the system, by ADP, that enables fundsto be instantly loaded to your employees’ cards whenever needed. This account does not replace yourregular payroll process of setting up account information, like a traditional direct deposit employee. Thisseparate account is ideal for between pay cycle needs like missed hours, expense reimbursements, andso on.
The Pay Card Funding Account API is required when enrolling a Wisely Pay by ADP card for anemployee. It returns the list of funding accounts for a given location.
Note: The location ID is a unique identifier that identifies the location.
Application ScopeThe following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/payroll/v1/paycard/funding-accounts?$filter=locationID eq ‘location ID'
Sensitive Information MaskingTo establish compliance with data security best practices, ADPs Pay Card Funding Account API willonly return a masked account number unless you specify that you want to see the values un-maskedin your HTTP request. To see these values un-masked, simply add the following header to your HTTPrequest:
Accept: application/json;masked=false
API Proxy Caches the RespondsThe API Proxy caches the successful response of the API for 30 minutes. It may prevent you from seeingthe unmasked value if you changed the HTTP request with the value in the previous section to beunmasked and sent the request right away. This is because if the same request comes in from the sameclient within this cache expiration time, API Proxy gives the response from its cache database instead ofsending the request to be a backend Statement of Request (SOR).
At any time, if you want to bypass the API Proxy cache and receive fresh data from backend systems,you can include if-none-match:none in the request header.
Enroll Your Employees for Wisely Pay by ADP Cards 6
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
OutputSchema Location Field Name
fundingAccounts > accountID > idValue Account Alias ID
fundingAccounts > location > nameCode > codeValue Location ID
fundingAccounts > financialAccount > accountNumber Funding Account Number
fundingAccounts > financialAccount > accountName Funding Account Name
fundingAccounts > accountCardAliasID > idValue Card Alias ID
fundingAccounts > defaultAccount Default Account
Full Schema And cURL SamplesSee Paycard Funding Accounts for more information.
Back to Top of Section
Validating the Pay Card Account
Important: This validation is for instant issued card only. If you are enrolling a mail-orderedcard, you may skip this step.
The Pay Card Funding Account API validates Proxy ID or Account Number of a Wisely Pay by ADP cardinstant issue card and returns location, card status, and Routing number (American Banking Association– ABA) and Account Number (Demand Deposit Account – DDA) of the card.
Enroll Your Employees for Wisely Pay by ADP Cards 7
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Application ScopeThe following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/ events/payroll/v1/paycard-account.validate
Option 1: Validating by Using the Account Number
Input
Schema Location: events > data > transform > cardDepositAccount > financialAccount > accountNumber
Field Name: Account Number
Required (Y/N): Y
Output
Schema Location Field Name
events > data > output > location > nameCode > codeValue Location ID
events > data > output > location > nameCode > shortName Location Name
events > data > output > cardDepositAccount > financialParty > routingTransitID >idValue
Routing TransitID(ABA)
events > data > output > cardDepositAccount > financialAccount > accountNumberAccount Number
(DDA)
events > data > output > cardDepositAccount > accountID > idValue Proxy ID
events > data > output > cardDepositAccount > accountStatusCode > codeValue Card Status
Enroll Your Employees for Wisely Pay by ADP Cards 8
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Enroll Your Employees for Wisely Pay by ADP Cards 9
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Option 2: Validate by Using Proxy IDAll 19 digits of the Proxy ID, including the 0s are required as the input.
Input
Schema Location: events > data > transform > cardDepositAccount > accountID > idValue
Field Name: Proxy ID
Required (Y/N): Y
Output
Schema Location Field Name
events > data > output > location > nameCode > codeValue Location ID
events > data > output > location > nameCode > shortName Location Name
events > data > output > cardDepositAccount > financialParty > routingTransitID >idValue Routing TransitID (ABA)
events > data > output > cardDepositAccount > financialAccount > accountNumber Account Number (DDA)
events > data > output > cardDepositAccount > accountID > idValue Proxy ID
events > data > output > cardDepositAccount > accountStatusCode > codeValue Card Status
Enroll Your Employees for Wisely Pay by ADP Cards 10
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Enroll Your Employees for Wisely Pay by ADP Cards 11
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Possible Values for Card StatusThe following are the possible values forevents[].data.output.cardDepositAccount.accountStatusCode.codeValue:
· Card Issued· Pending Card Issuance· Active· Closed· Lost Card· Stolen Card· Expired Card· restricted· locked· idle· retired· ofac· limited· canceled· disabled· deceased
Full Schema and cURL SamplesSee Paycard Enrollment v2 and go to /events/payroll/v1/paycard-account.
Back to Top of Section
Submitting Wisely Pay by ADP Card EnrollmentThis section guides you in finishing the enrollment for both instant issue cards and mail ordered cards.For instant issue cards, you can either enroll an employee by using the Proxy ID or account number. Theenrollment status will be returned after the submission is completed.
ResponseFrom the previous version of this guide, the step to verify enrollment status is no longer necessary.Enrollment is now a single step process.
· Routing Transit ID and Account Number will additionally be returned.· Proxy ID will only be returned if enrollment was done through Proxy ID.· Order Confirmation Number will no longer be returned.
Reference the following Output section for an updated schema.
Enroll Your Employees for Wisely Pay by ADP Cards 12
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Application ScopeThe following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/ events/payroll/v2/paycard.enroll
Enroll an Instant Issue Card Option 1 - Using Proxy ID
Input
Schema Location Field NameRequired
(Y/N)
events > data > eventContext > workerID > idValue Employee ID N
events > data > transform > enrollment > enrollmentTypeCode >codeValue Enrollment Type Y
events > data > transform > enrollment > cardDepositAccount >accountID > idValue Proxy ID Y
events > data > transform > enrollment > cardDepositAccount >accountID > schemeCode > codeValue ID Type Y
events > data > transform > enrollment > person > legalName >givenName First Name Y
events > data > transform > enrollment > person > legalName >middleName Middle Name N
events > data > transform > enrollment > person > legalName >familyName1 Last Name Y
events > data > transform > enrollment > person > birthDate Birth Date Y
events > data > transform > enrollment > person > governmentIDs >idValue Government ID Y
events > data > transform > enrollment > person > governmentIDs >nameCode > codeValue
Government IDType Y
events > data > transform > enrollment > person > legalAddress >lineOne Address Line One Y
events > data > transform > enrollment > person > legalAddress >cityName City Y
events > data > transform > enrollment > person > legalAddress >countrySubdivisionLevel1 > codeValue State Y
Enroll Your Employees for Wisely Pay by ADP Cards 13
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > enrollment > person > legalAddress >postalCode Zip Code Y
events > data > transform > enrollment > person > legalAddress >countryCode Country Code N
events > data > transform > enrollment > person > communication >mobiles > formattedNumber Mobile Number
Mobile or LandLine:
Y
events > data > transform > enrollment > person > communication >landlines > formattedNumber Land Line Number
Mobile or LandLine:
Y
events > data > transform > enrollment > person > communication >landlines > nameCode > codeValue Land Line Type Y
events > data > transform > enrollment > person > communication >emails > emailUri Email N
events > data > transform > enrollment > standardizedAddresses >address > lineOne
StandardizedAddresses Line
OneY
events > data > transform > enrollment > standardizedAddresses >address > cityName
StandardizedAddresses City Y
events > data > transform > enrollment > standardizedAddresses >address > countrySubdivisionLevel1 > codeValue
StandardizedAddresses State Y
events > data > transform > enrollment > standardizedAddresses >address > postalCode
StandardizedAddresses Zip
CodeY
events > data > transform > enrollment > standardizedAddresses >address > countryCode Country Code N
events > data > transform > enrollment > fundingAccount > location >nameCode > codeValue Location ID Y
events > data > transform > enrollment > processingInstructions >processingCode > codeValue Ship to Code Y
· If enrolling using Proxy ID, then the value for the ID Type field should always be PROXY.· If Location ID does not match with the card’s location, then we will ignore the specification and
the card’s location will not be updated.
Enroll Your Employees for Wisely Pay by ADP Cards 14
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Output
Schema Location Field Name
events > data > output > enrollment > enrollmentStatus > codeValue Enrollment Status
events > data > output > enrollment > cardDepositAccount >financialParty > routingTransitID > idValue Routing TransitID (ABA)
events > data > output > enrollment > cardDepositAccount >financialAccount > accountNumber Account Number (DDA)
events > data > output > enrollment > cardDepositAccount > accountID> idValue Proxy ID
Enroll an Instant Issue Card Option 2 - Using Account Number
Input
Schema Location Field NameRequired
(Y/N)
events > data > eventContext > workerID > idValue Employee ID N
events > data > transform > enrollment > enrollmentTypeCode >codeValue Enrollment Type Y
events > data > transform > enrollment > cardDepositAccount >accountID > idValue Account Number Y
events > data > transform > enrollment > cardDepositAccount >accountID > schemeCode > codeValue ID Type Y
events > data > transform > enrollment > person > legalName >givenName First Name Y
events > data > transform > enrollment > person > legalName >middleName Middle Name N
events > data > transform > enrollment > person > legalName >familyName1 Last Name Y
events > data > transform > enrollment > person > birthDate Birth Date Y
events > data > transform > enrollment > person > governmentIDs >idValue Government ID Y
events > data > transform > enrollment > person > governmentIDs >nameCode > codeValue
Government IDType Y
Enroll Your Employees for Wisely Pay by ADP Cards 15
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > enrollment > person > legalAddress >lineOne
Address LineOne Y
events > data > transform > enrollment > person > legalAddress >cityName City Y
events > data > transform > enrollment > person > legalAddress >countrySubdivisionLevel1 > codeValue State Y
events > data > transform > enrollment > person > legalAddress >postalCode Zip Code Y
events > data > transform > enrollment > person > legalAddress >countryCode Country Code N
events > data > transform > enrollment > person > communication >mobiles > formattedNumber
Mobile NumberMobile or
Land Line:
Y
events > data > transform > enrollment > person > communication >landlines > formattedNumber
Land LineNumber
Mobile orLand Line:
Y
events > data > transform > enrollment > person > communication >landlines > nameCode > codeValue Land Line Type Y
events > data > transform > enrollment > person > communication >emails > emailUri Email N
events > data > transform > enrollment > standardizedAddresses >address > lineOne
StandardizedAddresses Line
OneY
events > data > transform > enrollment > standardizedAddresses >address > cityName
StandardizedAddresses City Y
events > data > transform > enrollment > standardizedAddresses >address > countrySubdivisionLevel1 > codeValue
StandardizedAddresses State Y
events > data > transform > enrollment > standardizedAddresses >address > postalCode
StandardizedAddresses Zip
CodeY
events > data > transform > enrollment > standardizedAddresses >address > countryCode Country Code N
Enroll Your Employees for Wisely Pay by ADP Cards 16
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > enrollment > fundingAccount > location >nameCode > codeValue Location ID Y
events > data > transform > enrollment > processingInstructions >processingCode > codeValue Ship to Code Y
If enrolling using Account Number, then the value for the ID Type field should always be ACCOUNTNUMBER.
Output
Schema Location Field Name
events > data > output > enrollment > enrollmentStatus > codeValue Enrollment Status
events > data > output > enrollment > cardDepositAccount >financialParty > routingTransitID > idValue Routing TransitID (ABA)
events > data > output > enrollment > cardDepositAccount >financialAccount > accountNumber Account Number (DDA)
Enroll a Mail Ordered Card
Input
Schema Location Field NameRequired
(Y/N)
events > data > eventContext > workerID > idValue Employee ID N
events > data > transform > enrollment > enrollmentTypeCode >codeValue Enrollment Type
Y
events > data > transform > enrollment > person > legalName >givenName First Name
Y
events > data > transform > enrollment > person > legalName >middleName Middle Name
N
events > data > transform > enrollment > person > legalName >familyName1 Last Name
Y
events > data > transform > enrollment > person > birthDate Birth Date Y
events > data > transform > enrollment > person > governmentIDs >idValue Government ID Y
Enroll Your Employees for Wisely Pay by ADP Cards 17
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > enrollment > person > governmentIDs >nameCode > codeValue
Government IDType Y
events > data > transform > enrollment > person > legalAddress >lineOne
Address LineOne Y
events > data > transform > enrollment > person > legalAddress >cityName City Y
events > data > transform > enrollment > person > legalAddress >countrySubdivisionLevel1 > codeValue State Y
events > data > transform > enrollment > person > legalAddress >postalCode Zip Code Y
events > data > transform > enrollment > person > legalAddress >countryCode Country Code N
events > data > transform > enrollment > person > communication >mobiles > formattedNumber
Mobile NumberMobile or
Land Line:
Y
events > data > transform > enrollment > person > communication >landlines > formattedNumber
Land LineNumber
Mobile orLand Line:
Y
events > data > transform > enrollment > person > communication >landlines > nameCode > codeValue Land Line Type Y
events > data > transform > enrollment > person > communication >emails > emailUri Email N
events > data > transform > enrollment > standardizedAddresses >address > lineOne
StandardizedAddresses Line
OneY
events > data > transform > enrollment > standardizedAddresses >address > cityName
StandardizedAddresses City Y
events > data > transform > enrollment > standardizedAddresses >address > countrySubdivisionLevel1 > codeValue
StandardizedAddresses State Y
events > data > transform > enrollment > standardizedAddresses >address > postalCode
StandardizedAddresses Zip
CodeY
Enroll Your Employees for Wisely Pay by ADP Cards 18
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > enrollment > standardizedAddresses >address > countryCode Country Code N
events > data > transform > enrollment > fundingAccount > location >nameCode > codeValue Location ID Y
events > data > transform > enrollment > processingInstructions >processingCode > codeValue Ship to Code Y
Output
Schema Location Field Name
events > data > output > enrollment > enrollmentStatus > codeValue Enrollment Status
events > data > output > enrollment > cardDepositAccount >financialParty > routingTransitID > idValue Routing TransitID (ABA)
events > data > output > enrollment > cardDepositAccount >financialAccount > accountNumber Account Number (DDA)
Full Schema and cURL Samples:See Paycard Enrollment v2 and go to the /events/payroll/v2/paycard section.
Note: The ADP API library may not be updated with V2 specifications.
Back to Top of Section
Enroll Your Employees for Wisely Pay by ADP Cards 19
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Funding Wisely Pay by ADP CardsThe Fund Wisely Pay Cards API initiates an immediate fund transfer with the employee Account Numberor Employee ID and returns the Transaction Reference Number.
Note:
The Funding Account Number specification is only required if Company has multiple(non-WisleyNow) funding accounts. If Company has a single (non-WisleyNow) fundingaccount and the Funding Account Number is:
· Not specified, the API will proceed with that funding account.· Specified, the API will validate, before proceeding, that the specified account
number belongs to that funding account.The API will validate that the card, by the Employee Account Number, is in a locationassociated with the funding account.
Application ScopeThe following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/events/payroll/v1/paycard-funding.initiate
Option 1: Instant Funding by Using the Employee Account Number
Input
Schema Location Field NameRequired
(Y/N)
events > data > transform > transfer > transferTypeCode > codeValueTransfer Type
Code Y
events > data > transform > transfer > fundingAccount >financialAccount > accountNumber
Funding AccountNumber
Y, IfCompanyhas morethan onefundingaccount
events > data > transform > transfer > cardDepositAccount >financialAccount > accountNumber
EmployeeAccount Number Y
events > data > transform > transfer > transferAmount > amountValue Transfer Amount Y
Enroll Your Employees for Wisely Pay by ADP Cards 20
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Output
Schema Location: events > data > output > transfer > itemID
Field Name: Transaction reference number
Option 2: Instant Funding with Employee ID
Input
Schema Location Field NameRequired
(Y/N)
events > data > transform > transfer > transferTypeCode > codeValueTransfer Type
Code Y
events > data > transform > transfer > fundingAccount >financialAccount > accountNumber
Funding AccountNumber
Y, ifCompanyhas morethan onefundingaccount
Enroll Your Employees for Wisely Pay by ADP Cards 21
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > transfer > fundingAccount > location >nameCode > codeValue Location ID N
events > data > eventContext > workerID > idValue Employee ID Y
events > data > transform > transfer > transferAmount > amountValue Transfer Amount Y
Output
Schema Location: events > data > output > transfer > itemID
Field Name: Transaction reference number
Full Schema And cURL SamplesSee Paycard Funding Accounts v1 and go to the /events/payroll/v1/paycard-funding section.
Back to Top of Section
Enroll Your Employees for Wisely Pay by ADP Cards 22
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Reversing Funds from Wisely Pay by ADP CardsThe API provides the capability to reverse a funded amount from a cardholder’s card to the company’sfunding account, instantly. The API will also validate if the funding has been processed successfullybefore the reversal can be performed. The following business rules are in place:
· Reversal can only be performed within 5 calendar days after the funding has been made by theAPI.
· Full amount of reversal will be performed. No partial amount is allowed.· Reversal requires cardholder’s account to have a sufficient balance. The reversal will not be
performed if the amount is less than the requested amount.
To ensure the integrity of the reversal, the following information is required in the reversal request andwill be validated against our records:
· Transaction Reference Number refers to the transaction reference number that was returned bythe paycard-funding.initiate API after a funding request was processed successfully.
· Transfer Type Code – Use IMMEDIATE.· Funding Account Number – The company funding account has been setup for Wisely funding. If
you have more than one funding account, it needs to be the same account where the instantfunding was initiated.
Note:
The Funding Account Number specification is only required if Company has multiple(non-WisleyNow) funding accounts. If Company has a single (non-WisleyNow) fundingaccount and the Funding Account Number is:
· Not specified, the API will proceed with that funding account.· Specified, the API will validate, before proceeding, that the specified account
number belongs to that funding account.The API will validate that the card, by the Employee Account Number, is in a locationassociated with the funding account.
Application ScopeThe following canonical needs to be added to your application scope to complete this step:
https://api.adp.com/events/payroll/v1/paycard-funding.reverse
Enroll Your Employees for Wisely Pay by ADP Cards 23
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Option 1: Reverse Fund by Using Employee Account Number
Input
Schema Location Field NameRequired
(Y/N)
events > data > eventContext > transfer > transactionID
TransactionReferenceNumber
Y
events > data > transform > transferReversal > transferTypeCode >codeValue
Transfer TypeCode Y
events > data > transform > transferReversal > fundingAccount >financialAccount > accountNumber
Funding AccountNumber
Y, if Companyhas more than
one fundingaccount
events > data > transform > transferReversal > cardDepositAccount >financialAccount > accountNumber
EmployeeAccount Number Y
events > data > transform > transferReversal > transferAmount >amountValue Transfer Amount Y
Output
Schema Location: events > data > output > transfer > itemID
Field Name: Transaction reference number
Option 2: Reverse fund with Employee ID
Input
Schema Location Field NameRequired
(Y/N)
events > data > eventContext > transfer > transactionID
TransactionReferenceNumber
Y
events > data > transform > transferReversal > transferTypeCode >codeValue
Transfer TypeCode Y
Enroll Your Employees for Wisely Pay by ADP Cards 24
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field NameRequired
(Y/N)
events > data > transform > transferReversal > fundingAccount >financialAccount > accountNumber
FundingAccount Number
Required ifCompany hasmore than one
fundingaccount
events > data > eventContext > workerID > idValue Employee ID Required
events > data > transform > transferReversal > transferAmount >amountValue Transfer Amount Required
Output
Schema Location: events > data > output > transfer > itemID
Field Name: Transaction reference number
Full Schema And cURL Samples:See Paycard Funding Accounts v1 and go to the /events/payroll/v1/paycard-funding section.
Back to Top of Section
Enroll Your Employees for Wisely Pay by ADP Cards 25
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Searching for CardholdersThe Search for Cardholders API gives demographic information of cardholders based on search criteria.
Search for Cardholders by Request Body· queryParameter in the Request Body, acts as a placeholder for the entire Query String and is
typically appended to the end of a URL (scheme:hier-part). Seehttps://tools.ietf.org/html/rfc3986#section-3.
· Query String is case sensitive and non-safe characters (such as ASCII Control, Non-ASCII,Reserved, and Unsafe characters) must be URL Encoded. Additionally, any filter for a value witha literal apostrophe (‘) must be escaped with an additional apostrophe.
· $filter, $orderby, $top, and $skip query parameters are supported and adhere to the ODatastandard. See the OData Guide for more information regarding syntax.
$filterField Name Example
Associate OID cardholders/associateOID eq ‘some aoid’
First Name cardholders/personName/givenName eq ‘some first name’
Last Name cardholders/personName/familyName1 eq ‘some last name’
Employee Idcardholders/workerID/schemeCode/codeValue eq ‘EMPLOYEE’ andcardholders/workerID/idValue eq ‘some employee id’
SSNcardholders/governmentID/nameCode/codeValue eq ‘SSN’ andcardholders/governmentID/idValue eq ‘some ssn’
Account Number
cardholders/cardholderAccount/accountID/schemeCode/codeValue eq‘ACCOUNT NUMBER’ andcardholders/cardholderAccount/accountID/idValue eq ‘some accountnumber’
Account Numbercardholders/cardholderAccount/accountNumber eq ‘some accountnumber’
Enroll Your Employees for Wisely Pay by ADP Cards 26
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
$orderField Name Example
Location Name location asc|desc
Employee(LastName,FirstName) employee asc|desc
If unspecified, sort direction defaults to ascending
$skip and $topEquivalent to SQL offset and limit, respectively
Input
Schema Location: events > data > transform > queryParameter
Field Name: Query String
Required (Y/N): N
Examples
This is decoded:
{ "events": [ { "data": { "transform": { "queryParameter": "$orderby=employeedesc&$top=5&$skip=1&$filter=cardholders/personName/givenName eq ’Ellick’" } } } ]}
Enroll Your Employees for Wisely Pay by ADP Cards 27
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
This is encoded (as it should be):
{ "events": [ { "data": { "transform": { "queryParameter": "$orderby=employeedesc&$top=5&$skip=1&$filter=cardholders%2FpersonName%2FgivenName%20eq%20%27Ellick%27" } } } ]}
Output
Schema Location Field Name
cardholders > associateOID Associate OID
cardholders > workerID > idValue Employee ID
cardholders > cardholderAccount > accountID > idValue
OR
cardholders > cardholderAccount > accountNumber Account Number
cardholders > cardholderAccount > accountBalanceAmount >amountValue Balance
cardholders > personName > givenName First Name
cardholders > personName > middleName Middle Name
cardholders > personName > familyName1 Last Name
cardholders > birthDate Birth Date
cardholders > governmentID > idValue Government ID (masked)
cardholders > profileDetails >address > lineOne Address Line One
cardholders > profileDetails >address > lineTwo Address Line Two
cardholders > profileDetails >address > cityName City
cardholders > profileDetails >address > countrySubdivisionLevel1 >codeValue State
cardholders > profileDetails >address > postalCode Zip Code
Enroll Your Employees for Wisely Pay by ADP Cards 28
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Schema Location Field Name
cardholders > profileDetails >address > countryCode Country Code
cardholders > communication > mobiles > formattedNumber Phone Number
cardholders > communication > communication > emails > emailUri Email
cardholders > locationNameCode > codeValue Location ID
cardholders > locationNameCode > shortName Location Name
cardholders > programCode > shortName Card Program
cardholders > cards > cardStatusCode > codeValue Card Status
cardholders > cards > cardAliasID Card Alias
cardholders > cards > cardNumber Card Number (masked)
Enroll Your Employees for Wisely Pay by ADP Cards 29
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Appendix: Field Names and Descriptions 30
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Full Schema and cURL SamplesSee Cardholders v1 and go to the /events/payroll/v1/paycard/cardholder.read section.
Back to Top of Section
Appendix: Field Names and DescriptionsField Name Description
Location ID Specifies an assigned ID that identifies thelocation, such as a branch, through which thePrepaid card was issued. The Issuer must obtainvalid values from ADP.
Employee ID Specifies the employ identification. It is caseinsensitive and a maximum of 25 characters.
givenName Specifies the employee’s first name.
middleName Indicates the employee’s middle name.
familyName1 Specifies the employee’s last name.
birthDate Indicates the employee’s date of birth.
emailUri Specifies the employee’s email address.
lineOne Indicates the first line of the street address.
lineTwo Indicates the second line of the street address.
cityName Specifies the city where the employee resides.
countrySubdivisionLevel1 /state
Indicates the U.S Post Office state code for thestate where the cardholder resides.
postalCode Indicates the zip code.
countryCode Specifies the cardholder’s country code.
GovernmentId Indicates the employee’s Social Security Number(SSN).
GovernmentIdType Specifies the kind of Government ID used toidentify the employee.
Appendix: Field Names and Descriptions 31
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, LLC.Copyright © 2019 ADP, LLC.
Field Name Description
cardAliasId Indicates a unique ID representing theemployee’s card.
accountNumber Specifies the card account number.
proxyId Specifies a unique sequential value assigned toevery card. Typically found on the outside of theinstant issue card envelope.
The Proxy ID will no longer be provided for newlyissued Wisely Pay by ADP cards.