API Reference

Device Usage Control API

post
https://uatmea-iss-apigw.creditpluspinelabs.com/deviceapi/apis/v1/services/helpdesk/deviceUsageControl

The Device Usage Control API enables the cardholder to toggle between the card control usages, wherein the cardholder can allow or restrict the card usage for international and domestic ATM, POS, e-commerce, contactless, MDES in-app or VTS in-app, MDES contactless or VTS contactless, and MDES token QR transactions based on the activation type provided in the input. The Credit+ Issuing system receives, validates, and processes the request. If the request is successful, the device usage is allowed or restricted on the card. The system then logs the Device Usage Control (service code: 454) service request (SR) and sends the service request details in the response message. In case of API channel, the SR is processed immediately irrespective of whether the checker/maker configuration is enabled for this SR or not. If the request fails, the system returns the corresponding error code in the response and the SR is not logged.

The following validations are performed during activation and deactivation:

• The highest priority is given to lifelong activation, followed by periodic activation, and lastly the immediate activation in hours.

• If any combination of channel activation type and origin exist, and the lifelong activation request for all channels is received, then the request is accepted. However, if all these combinations are received again in a request, then the request is declined.

• If the periodic or hourly activation for all channels is existing and the lifelong activation request is received, then the request is accepted

• Ifthe periodic activation or deactivation for all or any ofthe channelsis existing, then the activation for same or overlapping period is not allowed.

• If lifelong activation or deactivation is existing and a periodic or hourly request is initiated with the same combination of lifelong, then the new periodic and hourly request does not get processed.

• If one or more channels (not all) is configured for lifelong activation or deactivation, and the request is initiated for all channels, then the remaining channels are also activated or deactivated for lifelong. The existing channel entry in the channel transaction setting does not change.

HTTP Status and Response Status Matrix

  • HTTP Code: This is the response status code issued by a server in response to a client's request made to the server.
  • Error Code: This is the error code returned by Credit+ Issuing application in the ‘code’ field of the response message indicating if the request was processed successfully or failed.
  • Reason: This is the description of the error code returned by Credit+ Issuing application.
HTTP CodeError CodeReason
201HDS000Request processed successfully
403900Invalid User
404998Device(s) does not exist
500999Invalid Request Type
400997Device Number field is mandatory.
400997Device Number field should be numeric.
400997Priority Request field is invalid.
400997Request Date field is mandatory.
400997Request Date field must be in MM/dd/yyyy HH:mm:ss format.
400997Form Factor Type field is mandatory.
400997Form Factor Type field is invalid.
400997Form Factor field is mandatory.
400997Form Factor field value must have max length 24.
400997Activation Flag field is mandatory.
400997Activation Flag field is invalid.
400997Transaction Origin field is mandatory.
400997Transaction Origin field is invalid.
400997Transaction Channel field is mandatory.
400997Transaction channel field value must have length 4.
400997Atleast one transaction channel required as '1'
400997Only numeric characters 0 and 1 are allowed.
400997Activation Type field is mandatory.
400997Activation Type field is invalid.
400997Channel field is invalid.
400997Transaction country is not allowed for activation Type {}.
400997Transaction country is not allowed for non international transactions
400997Transaction country is mandatory.
400997Transaction country is invalid.
400997Country code {} is invalid.
400997Start Date is not allowed for Activation Type - 'Time in Hrs'.
400997End Date is not allowed for Activation Type - 'Time in Hrs'.
400997Time in Hrs field is mandatory.
400997Time in Hrs field should be numeric.
400997Time in Hrs field should be between 1 to 24.
400997Time in Hrs field should be between 1 to 24.
400997Start Date field is mandatory.
400997End Date field is mandatory.
400997Start Date field must be in dd/MM/yyyy format.
400997End Date field must be in dd/MM/yyyy format.
400997Time in Hrs is not allowed for Activation Type - 'Life Long Activation'.
400997End Date is not allowed for Activation Type - 'Life Long Activation'.Start Date is not allowed for Activation Type - 'Life Long Activation'.
400997Product Type field is invalid.
400997Program Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character.
400997Program Code field value must have max length 10.
400997Device Plan Code field should only contain [A-Z 0-9] and underscore and must start and end with alphanumeric character.
400997Device Plan Code field value must have max length 10.
400997Request Date should be less than or equal to institution date.
400997Start Date should be equal to or greater than institution date.
400997End Date should be greater than institution date.
400997End Date should be greater than start date.
400CNA003Record does not exists for the given details
400CNA005Multiple device numbers are active for given details
400CNA006Error while fetching device details
400927Invalid Country
400998DEVICE_ERROR
500INT101Error while retriving data from device
500INT102Error while executing International allow/disallow API
500HDEERR004Internal error occurred
400HDE100Device is not normal
400INT201country white list plan not available
400INT201Selected country is blacklisted
400HDE259Device is already deactivated for life long.
400HDE260Device is already activated for life long.
400HDE261DEVICE is already activated.
400HDE262Start Date is not allowed for Activation Type - 'Life LongDevice is already deactivated for a specific period for same transaction mode.
400HDE263Device is already activated for given date range.
400HDE264Only activated device will be deactivate.
400HDE270Device is already activated for a specific period for same transaction mode.
400HDE417Error while processing request
400BTHCM00018Error while processing request
400913Backward offset time limit violated.
400944Invalid Request - Unrecognized field.
400988Encryption type Not Supported
400913Forward offset time limit violated.
400DUCE001Exception occurred while fetching the existing details.
400DUC0003Device is already activated for lifelong
400DUC0004Device is already deactivated for lifelong
400HDE274Device is already activated for a specific period for same transaction mode and country
400HDE276Device is already deactivated for a specific period for same transaction mode and country
400DUC0007Device is already activated for lifelong
400DUC0008Device is already deactivated for lifelong
400DUC0010Device is already activated for a specific period for same transaction mode and country
400DUC0011Device is already activated for a specific period for same transaction mode
400DUC0012Device is already deactivated for a specific period for same transaction mode and country
400DUC0013Device is already deactivated for a specific period for same transaction mode
400DUC0015Device is already activated for specific hours
400DUC0016Device is already deactivated for specific hours
400DUCE111Internal error while processing the request
400DUC0017Request has been rejected, as the Device Usage Control settings are already present in the system for selected channels or Pre-digitization is not done on device for MDES/VTS channels.
400INT200Error while fetching the white and black list country code plan
400HDE232Start date should be greater than or equal to Institution Current Local Date.
400HDE1030Request has been rejected as pre-digitization is not done for the device. Please try again after pre-digitization of the device.
400HDE279Requested Details of one of the channels and origin is overlapping with existing device usage, hence rejecting the multi-channel request.
400994Invalid Encryption-Algorithm header value
400994Invalid Encryption Request Parameters
400994Cryptography error
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
required
length between 3 and 3

Indicates the data that is being sent in the formFactor attribute, identifies whether formFactor is Card Pack ID (CPI), Card Number Alias (CNA), or Card Number (CRD), not null.

Allowed:
string
required
length between 10 and 24

Indicates Card Number, Card Pack ID, or Card Number Alias depending on the formFactorType value, if formFactorType is 'CPI' then this field is Card Pack ID, if formFactorType is 'CNA' then this field is Card Number Alias, if formFactorType is 'CRD' then this field is Card Number, not null, minimum length not applicable for CNA.

string
required
length between 2 and 2

Channels through which transactions are performed, if present, it must be 31.

string
enum
required
length between 1 and 1

Indicates the activation period, valid values: P (Activation in period), H (Immediate activation for n hours), L (Lifelong activation).

Allowed:
string
enum
required
length between 1 and 1

Flag to activate or deactivate the usage of card, valid values: Y (Activate), N (Deactivate).

Allowed:
string
required
length between 7 and 7
^[0-1]{7}$

Indicates the transaction channels that allow or restrict card usage depending on the activationFlag value, 7-digit length, each position indicates a specific channel (1: E-Commerce, 2: ATM, 3: POS, 4: CNT Contactless, 5: MDES In-App or VTS In-App, 6: MDES Contactless or VTS Contactless, 7: MDES Token QR), numeric values (0: Ignored or not allowed, 1: Allowed), accepts only 0 and 1.

string
required
length between 2 and 2
^[0-1]{2}$

Indicates if card usage is allowed for domestic and international transactions depending on the activationFlag value, 2-digit fixed length, positions indicate transaction origin (1: International, 2: Domestic), numeric values (0: Ignored or not allowed, 1: Allowed), valid values: 00 (neither domestic nor international), 10 (only international), 01 (only domestic), 11 (both international and domestic), accepts only 0 and 1.

string
required
^\d{2}/\d{2}/\d{4}\s\d{2}:\d{2}:\d{2}$

Denotes the date and time of request, must be less than or equal to the institution date.

string
enum
required
length between 1 and 1

Product type of the device, valid values: P (Prepaid), C (Credit), D (Debit), required only when the value for cardNumberAlias is present and multiple devices are linked with the same cardNumberAlias.

Allowed:
string
length ≤ 10
^[A-Za-z0-9][A-Za-z0-9_]*[A-Za-z0-9]$

Device plan code attached with the device, [A-Z 0-9] and underscore are allowed, required only when formFactorType is CNA and multiple devices are linked with same CNA.

string
length ≤ 10
^[A-Za-z0-9][A-Za-z0-9_]*[A-Za-z0-9]$

Program attached to the device, [A-Z 0-9] and underscore are allowed, required only when formFactorType is CNA and multiple devices are linked with same CNA.

string
^\d{2}/\d{2}/\d{4}$

Use of the card is applicable on the card from this date till the date defined in endDate, applicable for activationType: P, DD/MM/YYYY format, must be greater than or equal to the institution date and requestDate, mandatory for activationType: P, must be null for activationType: H or L.

string
^\d{2}/\d{2}/\d{4}$

Use of the card is applicable from startDate till this date, applicable for activationType: P, DD/MM/YYYY format, must be greater than or equal to the institution date and requestDate, mandatory for activationType: P, must be null for activationType: H or L.

string
enum
length between 1 and 1

Denotes whether the request is to be taken on priority or not, valid values: 0 (No priority), 1 (Priority request).

Allowed:
string
^[1-9]$|^1[0-9]$|^2[0-4]$

Indicates the number of hours for which the request must be activated, value range is 1 to 24, mandatory for activationType: H, must be null for activationType: P or L.

string
length ≤ 3

Country in which international use of card is allowed, mandatory if activationType: P and transactionOrigin has first position as 1 (international), valid values: 3-digit ISO country code, ALL (indicates applicable for all countries).

string
length ≤ 4000

Any free text that requestor wants to send for logging purpose.

string
^[0-9]+$

Current UTC timestamp in milliseconds, AES key expiration criteria depends on input UTC timestamp, applicable for encrypted requests.

Headers
string
^[a-zA-Z0-9-]{1,50}$

API consumer can share Correlation-ID in HTTP header for API requests. The Correlation-ID must be unique for each request. It is recommended to generate universally unique identifier (UUID) of length 32 or 36 that is compliant with RFC 4122. The maximum supported length is 50 alphanumeric characters. For example, ac97d177-9345-4934-8343-0f91a7a02836. If the Correlation-ID is not received in the incoming request, the system generates the UUID dynamically and assigns it to the request.

string

API consumer can share Source in HTTP header for API requests. For the list of Source values, see the Pre-conditions for HTTP Header of REST API topic in the Pre-requisite for Rest API section.

string
enum
required

API consumer must use Encryption-Algorithm as AES to encrypt the API requests.

Allowed:
Response

Updated about 1 year ago

Did this page help you?
Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 1 year ago

Did this page help you?