Card PIN Control

API: WS_PinControl

This web service enables you to set, retrieve, unblock and change the PIN associated with the card.

It also allows you to unblock the CVC2Closed The Card Verification Value (CVV) on a credit card or debit card is a 3 digit number on VISA, MasterCard and Discover branded credit and debit cards. Cardholder's are typically required to enter the CVV during any online or cardholder not present transactions. CVV numbers are also known as CSC numbers (Card Security Code), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process that makes them harder to guess. of a card or mobile device token.

PIN field usage

The table below displays the conditions under which each of the PIN fields must be present in the request and response for each <function>. Y = the field must be present. Blank = the field must be left empty.

 

currentPIN

newPIN

confirmPIN

Function

Request

Response

Request

Response

Request

Response

00 – Set PIN

N

N

Y

N

Y

N

01 – Get PIN

N

Y

N

N

N

N

02 – Change PIN

Y

Y

Y

Y

Y

N

03 – Generate and Get PIN

N

Y

N

N

N

N

04 – Unblock PIN

N

Y

N

N

N

N

05 – Send PIN Mailer

N

Y

N

N

N

N

06 – Forward PIN request to external API

N

N

N

N

N

N

07 – Unblock CVC2

N

N

N

N

N

N

08 – Unblock PIN and CVC2

N

N

N

N

N

N

Record Description

Tag

Type

Minimum Length

Maximum Length

Description

Request

Response

<WSID>

N

1

19

Web service ID. Must be unique for every web service request sent. For details, see the FAQs.Tip: You could use a number based on the current date and time, as long as it is unique (e.g., 20201217145006).

Mandatory

Mandatory

<IssCode>

AN

1

4

Thredd Issuer (Program Manager) Code. Assigned by Thredd.

Mandatory

Mandatory

<AuthType>

AN

1

1

Parameter to specify how the card is authenticated. See Authentication Methods.

Mandatory

Omit

<DOB>

YYYY-MM-DD

10

10

Date of Birth. Mandatory if value of <AuthType> is ‘2’ or ‘6’.

Conditional

Omit

<CVV>

AN

3

3

Card Verification ValueClosed The Card Verification Value (CVV) on a credit card or debit card is a 3 digit number on VISA, MasterCard and Discover branded credit and debit cards. Cardholder's are typically required to enter the CVV during any online or cardholder not present transactions. CVV numbers are also known as CSC numbers (Card Security Code), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process that makes them harder to guess., the 3-digit code printed on the back of the card. Mandatory if the value of <AuthType> is ‘3’.

Conditional

Omit

<AccCode>

AN

0

6

Access code or passcode. If provided, must be 6 digits, leading zeroes are acceptable. Leave empty if not required. Mandatory if the value of <AuthType> is ‘4’.

Conditional

Omit

<lastName>

AN

1

20

Cardholder's last name for authenticating the cardholder if the value of <AuthType> is ‘6’.

Optional

Omit

<locDate>

YYYY-MM-DD

10

10

The local current date in year-month-date format.

Mandatory

Mandatory

<locTime>

HHMMSS

6

6

The local current time, in hour-minute-second format.

Mandatory

Mandatory

<PAN>

AN

14

19

Card Number. Required in request if <AuthType> is ‘1’, ‘2’, ‘3’,‘4’ or ‘6’  and <PublicToken> not present.

Conditional

Omit

<PublicToken>

AN

1

9

The card’s public token. Mandatory in request if <PAN> is not present. Mandatory in the response.

Conditional

Mandatory

<ClientCode>

AN

1

64

User ID of the customer using the service. Only applicable to systems using member logins. Returned in the response if present in the request.

Note: Legacy field. Not used.

Conditional

Conditional

<Func>

AN

1

2

PIN function requested:

00 = Set PIN

01 = Get PIN

02 = Change PIN

03 = Generate and Get PIN

04 =Unblock PIN

05 = Send PIN mailer

06= Forward PIN request to external API. See Forwarding a PIN request to a External API.

07 = Unblock CVC2

08 = Unblock PIN and CVC2

Mandatory

Omit

<CurrentPin>

AN

4

12

Current PIN. Represented as a 4-12 digit PIN block. Usage depends on the value of <func>.This field is mandatory in the request for function 02. For all other functions, this field is ignored. In the response, this field is mandatory for function 01 and 03. For all other functions, this field is omitted.

Conditional

Conditional

<NewPin>

AN

4

12

New PIN. Represented as a 4-12 digit PIN block. Usage depends on the value of <func>. This field is mandatory in the request for functions 00 and 02. For all other functions, this field is ignored. In the response, this field is omitted.

Conditional

Conditional

<ConfirmPin>

AN

4

12

Confirmation of new PIN. Represented as a 4-12 digit PIN block. Usage depends on the value of <func>. This field is mandatory in the request for functions 00 and 02. For all other functions, this field is ignored. In the response, this field is omitted.

Conditional

Omit

<PINStatus>

N

1

1

Indicates whether the allowed number of card PIN tries has been exceeded. 0 = No; 1 = Yes.

Omit

Mandatory

<Sms_Required>

AN

1

1

Whether to send an SMS to the cardholder with the PIN. 0 = No; 1 = Yes. Default is ‘0’.

Optional

Omit

<FeeWaiver>

N

1

1

Indicates whether to waive any web service fee set up on the system: 0 = No, 1=Yes. Default is 0.

Optional

Omit

<ExtAPICardID>

AN

1

50

External API card ID if applicable. Follows the UUID canonical format: ‘xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’ (with x a hexadecimal char 0->f). If not used, leave blank.

Note: Legacy field. Not used.

Optional

Omit

<SysDate>

YYYY-MM-DD

10

10

The system processing date.

 

 

Omit

Mandatory

<ActionCode>

AN

3

3

The action code for the response. See Action Codes.

Omit

Mandatory

Request

Copy 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hyp="http://www.globalprocessing.ae/HyperionWeb">
   <soapenv:Header>
      <hyp:AuthSoapHeader>
         <hyp:strUserName>******</hyp:strUserName>
         <hyp:strPassword>******</hyp:strPassword>
      </hyp:AuthSoapHeader>
   </soapenv:Header>
   <soapenv:Body>
      <hyp:WS_PinControl>
         <hyp:WSID>2021123456789</hyp:WSID>
         <hyp:IssCode>PMT</hyp:IssCode>
         <hyp:AuthType>string</hyp:AuthType>
         <hyp:locDate>2021-01-01</hyp:locDate>
         <hyp:locTime>120000</hyp:locTime>
         <hyp:PAN></hyp:PAN>
         <hyp:PublicToken>123456789</hyp:PublicToken>
         <hyp:ClientCode></hyp:ClientCode>
         <hyp:Func>01</hyp:Func>
         <hyp:CurrentPin></hyp:CurrentPin>
         <hyp:NewPin></hyp:NewPin>
         <hyp:ConfirmPin></hyp:ConfirmPin>
         <hyp:Sms_Required>1</hyp:Sms_Required>
         <hyp:ExtAPICardID></hyp:ExtAPICardID>
      </hyp:WS_PinControl>
   </soapenv:Body>
</soapenv:Envelope>

Response

Copy 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <WS_PinControlResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
         <WS_PinControlResult>
            <WSID>2021123456789</WSID>
            <IssCode>PMT</IssCode>
            <PublicToken>123456789</PublicToken>
            <ClientCode/>
            <CurrentPin>1234</CurrentPin>
            <NewPin/>
            <LocDate>2021-01-01</LocDate>
            <LocTime>120000</LocTime>
            <SysDate>2021-01-01</SysDate>
            <ActionCode>000</ActionCode>
            <PINStatus>0</PINStatus>
         </WS_PinControlResult>
      </WS_PinControlResponse>
   </soap:Body>
</soap:Envelope>