26
UPside Prepaid Cards Web Services APIs specifications April 2010 Embedding prepaid card enrollment and card account management in your own consumerfacing systems

Visa Prepaid Cards Web Services API

Embed Size (px)

DESCRIPTION

Application Programmer's Interface allowing businesses to embed Visa prepaid card enrollment and basic card account access into their own websites, or connected to their Interactive Voice Response servers

Citation preview

Page 1: Visa Prepaid Cards Web Services API

 

 

UPside Prepaid Cards Web Services APIs specifications  April 2010 

 

Embedding prepaid card enrollment and card account management in your own consumer‐facing systems 

 

Page 2: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 2 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

 

1. Scope ................................................................................................................................... 3

2. Pre-requisites ....................................................................................................................... 5

Limitations ..................................................................................................................................... 5

Technical pre-requisites ................................................................................................................ 5

Operational pre-requisites ............................................................................................................. 5

Legal pre-requisites....................................................................................................................... 6

3. Plastyc Role.......................................................................................................................... 7

Prior to making the APIs available to a Partner............................................................................. 7

In support of the EnrollCardholder method ................................................................................... 7

In support of other methods .......................................................................................................... 8

4. Web Service Set Up ............................................................................................................. 8

General Set Up.............................................................................................................................. 8

Security Set-Up ............................................................................................................................. 8

5. Methods Overview................................................................................................................ 9

4. EnrollCardholder method.................................................................................................... 10

5. GetCardholders method ..................................................................................................... 13

6. GetCardholderInfo method................................................................................................. 14

7. GetCardholderTx method................................................................................................... 18

8. TransferMoney method ...................................................................................................... 20

9. SuspendCard method......................................................................................................... 21

10. Web Service Sample Windows Application (.exe).............................................................. 21

11. Appendix A - UPside Card Web Service Response Codes................................................ 25

12. Account Set Up................................................................................................................... 26

 

Page 3: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 3 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

1. Scope This Specification document is intended for 3rd party web communities, marketplaces and merchants (hereinafter called “Web Properties”) which want any combination of the following capabilities: 

- Host a prepaid cardholder enrollment process on their own system with their own Graphical User Interface (GUI) and parse and post to Plastyc the required parameters for enrolling consumers into an UPside Visa Prepaid Card 

- Obtain from Plastyc a list of all users who enrolled into an UPside Card through the Web Property (whether by using the enrollment API of by simple link‐based referral to a Plastyc‐run enrollment website) 

- Retrieve cardholder information and card account information such as balance and latest transactions for a particular cardholder enrolled through the Web Property, and display such information in its own system through its own GUI 

- Let users perform certain card account functions like sending money to another user or suspending a card in case of loss of theft, from its own system, through its own GUI 

 

Companies interested only in referring potential cardholders to Plastyc by handing visitors from their own website over to one of Plastyc‐operated websites, without capturing the required cardholder information themselves, or without attempting to display any card account information in their own sites do not need to use this specification.  If you are in this case, please contact us at [email protected] or 646‐485‐5267 to seek a referral agreement with Plastyc, through which you will receive a “sponsorship code” allowing you to simply embed traceable hyperlinks into your website. 

Page 4: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 4 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

The following diagram illustrates how the Web Services APIs are intended to be used: 

 

 

Partner’s 

Web 

Property 

Plastyc Enrollment Server 

First Name 

Last Name 

Address 1 

Address 2 

ZIP Code 

City 

Date of Birth 

SSN 

Gender 

Enrollment Form Partner’s website and Graphical User 

Interface 

SOAP/XML 

over https

Card Enrollment API

Processing Platform

User  Card 

Email

(Shipped by post)

EnrollCardHolder Method

Other Methods 

Partner’s 

Web 

Property 

Name on card:         Joe SMITH 

Card Number:  XXXXXXXX1234 

Type                 Details                                         Date                    Amount load              DDA                                              3/15/10              +$750.00 expense       Starbucks                                     3/14/10                   ‐$3.97 expense       iTune store                                  3/09/10                   ‐$9.99 

Send money to:  Amount:

Submit 

Partner’s website and Graphical User Interface 

Plastyc Cardholder Management Server 

Other  APIs 

User (Authenticated)

Card Accounts Database 

SOAP/XML 

over https

Card Account Management 

Window 

Processing Platform

Page 5: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 5 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

2. Pre­requisites 

Limitations The current version of this specification covers only enrollment of adult users (above the age of 18) with a valid US mailing address and a valid Social Security Number. 

Technical pre­requisites The partner company wishing to use the Web Service APIs must be able to establish https sessions with both its own visitors’ browsers and Plastyc’s production servers, from a fixed and known IP address. 

The Web Property must maintain a valid SSL certificate at all times. 

Other method‐specific technical pre‐requisites are listed below: 

Method  Pre‐requisite 

EnrollCardholder 

Verification mechanism like a graphic challenge (CAPTCHA) must have been successful to ensure that only human beings and not programs or robots are attempting to perform an enrollment. 

Data validation mechanism to ensure that data entered by users is not spurious or does not contain blatant errors. Validation must include at least: no empty mandatory field, correct syntax of email address, of phone number and of SSN. 

GetCardholders   

GetCardholderInfo  User must have been authenticated by Web Property to ensure that the CardholderID parameter is only passed in actual presence of the cardholder 

GetCardholderTx  User must have been authenticated by Web Property to ensure that the CardholderID parameter is only passed in actual presence of the cardholder 

TransferMoney Sending User must have been authenticated by Web Property to ensure that the Sending CardholderID parameter is only passed in actual presence of the cardholder 

SuspendCard  User must have been authenticated by Web Property to ensure that the CardholderID parameter is only passed in actual presence of the cardholder 

 

 

Operational pre­requisites The Partner company operating the Web Property must be prepared to collect the following minimum information from consumers it wishes to enroll into an UPside Visa Prepaid Card: 

- first and last name 

Page 6: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 6 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

- email address and phone number - shipping address (which will become the billing address of the card) - gender, birth date and Social Security Number 

 

The Partner company must be prepared to either select (and impose to its customers) a specific card graphic choice, or implement a graphical user interface for the customer to choose one among the several card graphic choices available from Plastyc. 

If the Partner company chooses to not use the EnrollCardholder method, but uses any of the other methods, it must map its own users name space to the CardholderIDs used by the APIs. For example, if the Web Property operated by the Partner Company uses its own set of usernames to identify its users, then it will need to also capture the users email address or phone number or real names in order to be able to map each of the username values to each CardholderID. This mapping process is outside the scope of this document. 

The Partner company must train its staff who will have access to the user and account data, on security and privacy protection requirements, and in particular ensure that all involved employees are aware of the requirement that no personally identifiable financial data shall be communicated to any third party under any circumstances. Plastyc cannot provide any such training services or legal advice. 

 

Legal pre­requisites The Web APIs described in this document can be used in production mode only after a legally binding agreement has been signed between the Partner and Plastyc, including clauses covering the following items: 

- Partner to pay Plastyc a one‐time support, testing and set‐up fee of $5,000. 

- Partner to indemnify and hold Plastyc and its affiliates harmless in case of loss or theft of cardholder data, or resulting from misuse of such data by its staff or inappropriate transmission of such data to 3rd parties; 

- Partner to never ask users for their cardholder number other than if Partner operates an e‐ecommerce site for which card numbers are needed to make purchases, unrelated to the use of the APIs; 

- Partner to not store any cardholder data unless absolutely necessary for customer support purposes or as may be required by law; 

- Partner to have a Privacy Policy in full force and effect at all times, and to operate and maintain adequate training of its staff with respect to such Privacy Policy. 

Page 7: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 7 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

3. Plastyc Role 

Prior to making the APIs available to a Partner Plastyc will answer reasonable questions about the APIs and their intended use by phone and via email. 

Plastyc will open test accounts for letting the Partner evaluate and test the APIs by exercising them in a non‐production environment with fictitious cardholders and data. Plastyc will provide reasonable technical support by phone and email during Partner’s evaluation and testing of the APIs. 

Plastyc will provide its standard form of partnership agreement suitable for using the APIs in a production environment, and will negotiate in good faith the final terms of such Agreement with the Partner. 

Plastyc reserves the right to discontinue the dialog with a Partner if, in Plastyc’s own judgement, deploying the APIs with the Partner is not in Plastyc’s best commercial or strategic interests. 

 

In support of the EnrollCardholder method Upon receiving from the Partner company the minimal information required about the prospective cardholder to process a card enrollment, Plastyc will: 

- Verify the validity of the user data passed o consistency between ZIP code and City o email format is either a three‐letter top level domain except “xxx” (e.g. .com, .edu. ,org, 

.net, etc.) or the two‐letter country code top level domain “us” o SSN is properly formed and does not contain illegal strings 

- Pass the verified data to the issuance system where the customer data is verified against an identity database and against the OFAC list, in accordance to the USA Patriot Act 

 

If the process is successful, the API returns the Direct Deposit Account number corresponding to the UPside Visa Prepaid Card which will be shipped to the customer within 7 to 10 business days. 

The Direct Deposit Number is usable for ACH transfers (not for wire transfers) and is comprised of an ABA routing number and an account number. This number is immediately usable for deposits of funds into the customer card, even as the card has not been shipped or activated yet. 

If the process is unsuccessful, the API returns an error code with the reason of the failure. 

Important Note: there may be cases where an enrollment attempt is found to be suspicious at a later stage, typically within a few hours to a day of such enrollment via the API. In such cases, Plastyc will communicate directly with the prospective cardholder via email to attempt to resolve the issue. This may result in Plastyc being unable to issue a card and requiring an adjustment to any positive response provided beforehand to the Partner via the API. 

If the Partner company does not pass certain optional parameters like a cardholder username and password (which are otherwise captured when the enrollment takes place directly on one of the Plastyc websites), then the cardholders’ email address is used as the cardholders’ default username and a unique temporary password is created for the cardholder to obtain initial access to his/her online dashboard 

Page 8: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 8 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

account where he/she will be able to set their own password after the first login with the application assigned temporary password. 

 Similarly, if the Partner company does not pass the “secret question” and “answer to secret question” optional parameters via the Web Service API, then, the new cardholder will be prompted to create of choose his/her secret question / answer (used to retrieve forgotten username/password) the first time he/she accesses his/her online card account. 

In support of other methods Upon receiving the input parameters of the various methods, Plastyc : 

- verifies the data passed 

- accesses it card accounts database to retrieve the requested information 

- in the case of the TransferMoney and Suspend method, Plastyc accesses the processing platform to perform the required action 

If the process is unsuccessful, the API returns an error code with the reason of the failure. 

Important Note: all methods except EnrollCardholder and GetCardholders identify the intended cardholder via its CardholderID parameter. As outlined above, it is the responsibility of he Partner company to pass the proper CardholderID after having identified the user. 

 

4. Web Service Set Up A public SOAP/XML web service is hosted by Plastyc in order to process cardholder enrollments, cardholder and account information requests, and other methods available in the API set..   

General Set Up Plastyc provides the Web Property access to the following two environments ‐ along with an account login and password and partner ID: 

DEMO/TEST environment: This is used for development & testing purposes.  

PRODUCTION environment: Once testing is completed, the client is switched to a production URL, where the same web service schema as the test environment is utilized. 

The URL’s below are used in order to access Plastyc’s enrollment web service: 

DEMO /TEST environment: http://ws.plastyc.demo18.dataart.com/UpsideService.svc  

PRODUCTION environment: https://www.upsidecard.com:9443/UpsideService.svc 

Security Set­Up In order to comply with security requirements (sensitive data – SSN’s), the following mechanisms are used to prevent the compromising of the sensitive data exchanged between the Web Property and Plastyc: 

Page 9: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 9 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

IP filtering: PRODUCTION web service is accessible only to a permitted range of source IP addresses that need to be agreed beforehand with Plastyc. Plastyc's Demo/Test environment has no IP address validation. 

SSL encryption: PRODUCTION web service is accessible only using the HTTPS protocol. Demo/Test environment uses http only. 

In addition, Partner shall implement the following mechanism prior to calling the EnrollCardholder method: 

Prevention of robotic enrollments: a human detection mechanism like a CAPTCHA graphic challenge must be in place as part of the enrollment form that front ends the EnrollCardholder method 

5. Methods Overview The Plastyc web service declares the following six methods: 

Method  Description 

EnrollCardholder  Enroll new 18+ cardholder for UPsideLife program 

GetCardholders  Gets the list of cardholders associated with the current partner 

GetCardholderInfo  Gets detailed cardholder information 

GetCardholderTx  Gets cardholder transactions for specific time period 

TransferMoney  Transfers money between cardholders 

SuspendCard  Suspends a cardholder card account 

Each method has one input and one output parameter set of complex types, which declare all required and optional fields for the operation. 

All input parameters extend the UPsideRequest type, which declares the following properties: 

Name  Type  Required  Description 

Login  String  Yes  Partner's login provided by Plastyc 

Password  String  Yes  Partner's password provided by Plastyc 

PartnerID  Int32  Yes  Partner's ID provided by Plastyc 

RequestID  Guid  Yes  Unique request identifier, used to track duplicate calls 

 

All output parameters extend the UPsideResponse type, which declares the following properties: 

 

Name  Type  Description 

Page 10: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 10 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

RequestID  Guid  RequestID passed in the request 

ResponseCode  Int32  Method response code. If acompleted successfully, the ResponseCode is set to 0, otherwise it specifies the error code. 

See Appendix A for list of response codes returned by the UPside Web Service 

ResponseDescription  String  Human readable description of the response code 

 

The subsequent paragraphs provide more information about methods supported and their input/output parameters. 

4. EnrollCardholder method This method is used to process an enrollment for a single 18+ cardholder.  

The following Plastyc server side actions are carried out: 

1. Validation of  all input parameters 

2. Interact with the card processing platform, in order to create the new person in the system and assign a card to him/her 

3. Store required cardholder information into the Plastyc database 

4. Send an enrollment confirmation e‐mail to cardholder. 

Important Note: 3rd Party web communities will be responsible for the GUI required to capture the required parameters detailed below, in order to avoid failed web service calls, it is essential that the Web Property validates the data collected from their GUI before the web service call is initiated. 

Input parameters (EnrollCardholderRequest type)  

Name  Type  Used By  Required  Description 

CardholderInfo  PersonInfo  ProcessingPlatform 

Yes  Cardholder personal details 

CardholderSSN  String  ProcessingPlatform 

Yes  Cardholder Social Security Number  

(The full SSN is used for the Customer Identification Process; and the last 4 digits are used for subsequent identification of the user when accessing phone based customer support) 

CardholderUserName  String  UPside  No  Cardholder user name at www.upsidecard.com  

Page 11: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 11 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

The username may contain letters and/or digits, from 6 to 16 characters length 

If parameter is not passed, the e‐mail address will be used as username 

CardholderUserPassword  String  UPside  No  Cardholder password 

The password must contain letters and digits, from 6 to 16 characters length 

If parameter is not passed, a temporary password will be created and included into the confirmation e‐mail. 

CardholderSecretQuestion  String  UPside  No  Text of cardholder secret question 

If parameter is not passed, cardholder will be prompted at first login to create the secret question / answer 

CardholderSecretAnswer  String  UPside  No  Answer for cardholder secret question 

If parameter is not passed, cardholder will be prompted at first login to create the secret question / answer 

AccountSubprogramID  Int32  UPside, Card 

Processor 

Yes  Account subprogram ID which defines a particular card plan (i.e. card parameters and fee structure). This value to be provided by Plastyc, in line with the subprogram agreed by Plastyc & Web Property (UPsidelife is the default plan) 

CardGraphicsID  Int32  UPside,  

Card Processor 

Yes  Card graphics ID. 

Available card images and their identifiers to be provided by Plastyc for the subprogram as agreed with the Web Property. 

 

 

PersonInfo Type Definition  

Name  Type  Required  Description 

FirstName  String  Yes  Cardholder first name as will be embossed on the card and used during the Customer Identification Process 

Page 12: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 12 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

LastName  String  Yes  Cardholder last name as will be embossed on the card and used during the Customer Identification Process 

Birthdate  DateTime?  Yes  Cardholder birth date, used during the Customer Identification Process 

Gender  String  Yes  Cardholder gender (Male or Female) 

Zip  String  Yes  Zip code of the cardholder address to which the card will be shipped 

State  String  Yes  State of the cardholder address to which the card will be shipped 

City  String  Yes  City of the cardholder address to which the card will be shipped 

Address  String  Yes  Street name and house number of the cardholder address to which the card will be shipped 

Phone  String  Yes  Cardholder contact phone number (mobile or landline) 

EMail  String  Yes  Cardholder e‐mail address, used as the default username if no other username is supplied, and used for subsequent communication with the cardholder 

 

Output Parameters (EnrollCardholderResponse type)  

Name  Type  Description 

CardholderID  Int32  Cardholder identifier to be used in other operations of this service 

DDARoutingNumber  String  Cardholder Direct Deposit Account (“DDA”) routing number, designating the BIN sponsoring bank used by Plastyc to issue the cards 

DDAAccountNumber  String  Cardholder DDA account number, unique to the card to be issued 

 

Response codes: 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

Page 13: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 13 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

201  InvalidCardholderSSN  Cardholder social security number is invalid 

202  InvalidCardholderUsername  Cardholder username is invalid 

203  InvalidCardholderPassword  Cardholder password is invalid 

205  InvalidCardholderBirthdate  Cardholder birthdate is invalid 

206  InvalidCardholderEMail  Cardholder e‐mail address is invalid 

207  InvalidCardholderAddress  Cardholder street address is invalid 

208  InvalidCardholderGender  Cardholder gender is invalid 

220  InvalidAccountSubprogramID  Cardholder account subprogram ID is invalid 

231  InvalidCardGraphicsID  Cardholder card graphics ID is invalid 

300  ExistsCardholderEMail  Cardholder with specified e‐mail address already exists 

301  ExistsCardholderUsername  Cardholder with specified username already exists 

350  TransactionDeclined  Requested transaction has been declined 

400  CardProcessorError  Critical card processor error 

500  InternalError  Critical UPside error 

 

5. GetCardholders method This method returns the list of all cardholders associated with the Partner. 

Input parameters (GetCardholdersRequest type): There's no additional properties defined at GetCardholdersRequest type 

Output Parameters (GetCardholdersResponse type)  

Property Name  Type  Description 

Cardholders  CardholderInfo[]  List of cardholders associated with the Partner 

 

CardholderInfo Type Definition  

Name  Type  Description 

Page 14: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 14 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

ID  Int32  Unique cardholder identifier 

EnrollDate  DateTime  The date when cardholder has enrolled for a card 

UserName  String  Cardholder username 

PersonInfo  PersonInfo  Cardholder personal information 

 

PersonInfo Type Definition  

Name  Type  Description 

FirstName  String  Cardholder first name 

LastName  String  Cardholder last name 

Phone  String  Cardholder contact phone number (mobile or landline) 

EMail  String  Cardholder e‐mail address 

 

Response codes: 

 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

500  InternalError  Critical UPside error 

 

6. GetCardholderInfo method This method finds a cardholder by ID and returns the most recent cardholder information. 

Input parameters (GetCardholderInfoRequest type):  

Name  Type  Required  Description 

CardholderID  Int32  Yes  Cardholder ID to get information about 

Page 15: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 15 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

IncludeCardholderInfo  Bool  No  Flag indicating whether to get personal cardholder information (name, e‐mail, phone, etc.) 

IncludeAccountInfo  Bool  No  Flag indicating whether to get cardholder account information (subprogram, balance, DDA information) 

IncludeCardsInfo  Bool  No  Flag indicating whether to get information about cardholder cards (status, last four digits, graphics, etc.) 

IncludeLastCardTx  Bool  No  Flag indicating whether to get the latest transactions made by cardholder 

LastCardTxCount  Int32?  No  In case when IncludeLastCardTx is set to true, indicates how many transactions to get 

 Output Parameters (GetCardholderInfoResponse type)  

Property Name  Type  Description 

CardholderInfo  CardholderInfo  Cardholder personal information 

AccountInfo  AccountInfo  Cardholder account information 

Cards  CardInfo[]  Cardholder cards information 

LastCardTx  CardTx[]  Latest card transactions made by cardholder 

 

CardholderInfo Type Definition  

Name  Type  Description 

ID  Int32  Unique cardholder identifier 

EnrollDate  DateTime  The date when cardholder has enrolled for a card 

UserName  String  Cardholder username 

PersonInfo  PersonInfo  Cardholder personal information 

 

PersonInfo Type Definition  

Name  Type  Description 

Page 16: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 16 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

FirstName  String  Cardholder first name 

LastName  String  Cardholder last name 

Phone  String  Cardholder contact phone number (mobile or landline) 

Email  String  Cardholder e‐mail address 

 

AccountInfo Type Definition  

Name  Type  Description 

ID  Int32  Unique cardholder account identifier 

SubprogramID  Int32  Cardholder account subprogram ID 

LoyaltyBalance  Int32  Cardholder account loyalty balance 

AuthBalance  Decimal  Cardholder account authorized balance (open to buy) 

SettledBalance  Decimal  Cardholder account settled balance 

DDARoutingNumber  String  Cardholder account DDA routing number 

DDAAccountNumber  String  Cardholder account DDA account number 

 

CardInfo Type Definition  

Name  Type  Description 

ID  Int32  Unique card identifier 

Number  String  Last four digits of the card number 

IsPrimary  Bool  Whether the card is a primary card 

CardholderName  String  Cardholder name embossed on the card 

Status  String  Card status: 

• Pending – the card has not been activated yet 

• Open – the card is active 

• Suspended – the card has been suspended 

Page 17: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 17 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

• LostStolen – the card has been marked as lost/stolen 

• Closed – the card has been closed 

• PotentialFraud – the card has been marked as potential fraud 

• Fraud – the card has been marked as fraud 

GraphicsID  Int32  Card graphics ID 

Available card images and their identifiers to be provided by Plastyc for the subprogram as agreed with the Web Property 

CreationDate  DateTime  Card issuance date 

 

CardTx Type Definition  

Name  Type  Description 

UID  Guid  Unique card transaction identifier 

CardID  Int32  Associated card identifier 

AuthDate  DateTime  Card transaction authentication date and time (EST) 

PostDate  DateTime?  Card transaction post date and time (EST) 

The value will be null if transaction has not been posted yet 

Type  String  Card transaction type 

Available types include: Deposit, Reload, Purchase, ATM, Fee, Return, Transfer, AdjustmentDebit. 

Detail  String  Contains transaction detail 

Description  String  Contains additional transaction description 

Amount  Decimal  Transaction amount in originated currency 

Currency  Int32  Originated currency code 

(see http://en.wikipedia.org/wiki/ISO_4217 for list of currency codes) 

BillingAmount  Decimal  Transaction amount in billing currency (USD) 

BillingCurrency  Int32  Billing currency code (840 ‐ USD) 

 

Page 18: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 18 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

Response codes: 

 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

200  InvalidCardholderID  Cardholder identifier is invalid 

500  InternalError  Critical UPside error 

 

7. GetCardholderTx method This method returns all cardholder transactions for a specific time period. 

Input parameters (GetCardholderTxRequest type):  

Name  Type  Required  Description 

CardholderID  Int32  Yes  Cardholder ID to get transactions for 

StartDate  DateTime?  No  Transactions start date 

EndDate  DateTime?  No  Transactions end date 

Output Parameters (GetCardholderTxResponse type)  

Property Name  Type  Description 

CardTx  CardTx[]  List of cardholders transactions 

 

CardTx Type Definition  

Name  Type  Description 

UID  Guid  Unique card transaction identifier 

Page 19: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 19 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

CardID  Int32  Associated card identifier 

AuthDate  DateTime  Card transaction authentication date and time (EST) 

PostDate  DateTime?  Card transaction post date and time (EST) 

The value will be null if transaction has not been posted yet 

Type  String  Card transaction type 

Available types include: Deposit, Reload, Purchase, ATM, Fee, Return, Transfer, AdjustmentDebit. 

Detail  String  Contains transaction detail 

Description  String  Contains additional transaction description 

Amount  Decimal  Transaction amount in originated currency 

Currency  Int32  Originated currency code 

(see http://en.wikipedia.org/wiki/ISO_4217 for list of currency codes) 

BillingAmount  Decimal  Transaction amount in billing currency (USD) 

BillingCurrency  Int32  Billing currency code (840 ‐ USD) 

 

Response codes: 

 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

200  InvalidCardholderID  Cardholder identifier is invalid 

400  CardProcessorError  Critical card processor error 

500  InternalError  Critical UPside error 

 

Page 20: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 20 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

8. TransferMoney method This operation performs money transfer between two active (open) status  cardholders. An email confirmation is sent to the sender and receiver of the funds transfer. Cardholders’ status must be verified as "open" before a request is made. 

Conditions related to this service are: 

You can share money with up to five (5) people. Total of  four (4) money transfers are allowed in a 30‐day period (up to $400 total). Total of two (2) money transfers are allowed in a 24‐hour period.  $150 is the maximum transfer amount you can send in a 24‐hour period.  Individual money transfers can be between $1 and $150.  Sender and receivers account must be in active (open) status. 

Input parameters (TransferMoneyRequest type):  

Name  Type  Required  Description 

SenderCardholderID  Int32  Yes  Cardholder ID who is sending money 

ReceiverCardholderID  Int32  Yes  Cardholder ID who is receiving money 

Amount  Decimal  Yes  Amount to transfer 

Output Parameters (TransferMoneyResponse type) There's no additional properties defined at TransferMoneyResponse type

Response codes: 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

200  InvalidCardholderID  Cardholder identifier is invalid 

250  InvalidAmount  Passed amount is not in valid range 

320  InactiveCard  Cardholder card is not currently active 

350  TransactionDeclined  Requested transaction has been declined 

400  CardProcessorError  Critical card processor error 

500  InternalError  Critical UPside error 

Page 21: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 21 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

9. SuspendCard method This method changes the status of a cardholder’s card to suspended. Action can only be performed if previous status is active (open) or pending. 

Input parameters (SuspendCardRequest type):  

Name  Type  Required  Description 

SenderCardholderID  Int32  Yes  Cardholder ID whose card must be suspended 

CardID  Int32  Yes  Card ID to be suspended 

Output Parameters (SuspendCardResponse type)  

There's no additional properties defined at SuspendCardResponse type 

Response codes: 

 

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

200  InvalidCardholderID  Cardholder identifier is invalid 

230  InvalidCardID  Cardholder card identifier is invalid 

320  InactiveCard  Cardholder card is not currently active 

400  CardProcessorError  Critical card processor error 

500  InternalError  Critical UPside error 

 

10. Web Service Sample Windows Application (.exe) A sample packaged application (.exe) is available for testing the web service methods on a Windows machine. 

Once downloaded from the Plastyc website, start the file name UpsideClientDemo.exe 

The 6 methods appear as tabs at the top of a standard application window: 

Page 22: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 22 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

 

To exercise any of the 6 methods, use the following test account credentials: 

Login: APIuser 

Password: just4test 

Partner ID: 72 

You may also receive a separate tes account with different credentials by contacting us using the information at the end of this document. 

Page 23: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 23 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

A few test cardholders have been created in this test account, which you can retrieve by using the GetCardholders method: 

 

You can add a fictitious card holder by using the Enroll Cardholder method: 

Page 24: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 24 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

The details of a given cardholder can be obtained by designating the UserID and specifying which data elements to retrieve using the GetCardholderInfo method: 

 

 

Transactions for one of the cardholders can be retrieved for a given date interval using the GetCardHolderTx method: 

 

Page 25: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 25 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

11. Appendix A ­ UPside Card Web Service Response Codes  

Value  Code  Description 

0  Success  Operation has been completed successfully 

100  MissingRequiredData  Not all required data has been specified 

101  InvalidCredentials  Called specified invalid combination of login, password and partner ID 

200  InvalidCardholderID  Cardholder identifier is invalid 

201  InvalidCardholderSSN  Cardholder social security number is invalid 

202  InvalidCardholderUsername  Cardholder username is invalid 

203  InvalidCardholderPassword  Cardholder password is invalid 

205  InvalidCardholderBirthdate  Cardholder birthdate is invalid 

206  InvalidCardholderEMail  Cardholder e‐mail address is invalid 

207  InvalidCardholderAddress  Cardholder street address is invalid 

208  InvalidCardholderGender  Cardholder gender is invalid 

220  InvalidAccountSubprogramID  Cardholder account subprogram ID is invalid 

230  InvalidCardID  Cardholder card identifier is invalid 

231  InvalidCardGraphicsID  Cardholder card graphics ID is invalid 

250  InvalidAmount  Passed amount is not in valid range 

300  ExistsCardholderEMail  Cardholder with specified e‐mail address already exists 

301  ExistsCardholderUsername  Cardholder with specified username already exists 

320  InactiveCard  Cardholder card is not currently active 

350  TransactionDeclined  Requested transaction has been declined 

400  CardProcessorError  Critical card processor error 

500  InternalError  Critical UPside error 

 

Page 26: Visa Prepaid Cards Web Services API

Plastyc Web Services API specifications  Version:     April, 2010 

 

© Plastyc, 2010  Page 26 

This document is property of Plastyc Inc. The document or any part of it may not be used without a written permission of Plastyc Inc. 

 

12. Account Set Up Setting up an account includes obtaining the following from Plastyc: 

- Partner login name 

- Partner login password 

- Partner ID (also called Promo ID) 

 

To open an API account, please contact:  

Email: [email protected]  

Phone: 646 415 9412 

 

For all commercial and contract questions, please contact: 

Email: [email protected] 

Phone: 646 485 5267