Pin Management

Pin Management

Overview

Our PIN Management services provide a secure platform for you to manage and distribute PINs to your customers. With our platform, you can easily generate, distribute and revoke PINs as needed, and track their usage.

Our PIN Management services also include added security features, such as encryption and multi-factor authentication, to ensure that your customers PINs are protected from fraud. Our platform also ensures that your PINs are compliant with all local and international regulations and industry standards, such as PCI DSS, which ensures that your transactions are processed in a secure and compliant manner.

In addition, our PIN Management services provide you with detailed reporting and analytics, which allows you to track and analyze your customers PIN usage, and make data-driven decisions. You can also set up alerts and notifications, which will inform you of any changes to your customers PINs usage or activity.

Version

Card Set Pin

Status:

Production

Version:

V2

Category:

Pin Management

Card Set PIN

Overview

This API is used to set a PIN on a card. This is typically done for newly created cards or replaced ones, and is necessary for making Point of Sales (POS) purchases. The API can also be used in the event that the cardholder forgets their PIN, but it is important to note that strong verification of the cardholder's identity should be performed before enabling this feature (e.g. through the use of biometrics, security questions, or one-time passwords).

The PIN provided through this API will be the one required for all POS purchases made with the card. To ensure the secure exchange of sensitive information, the API uses cryptography to protect the PIN. Two modes of encryption are supported: symmetric encryption and asymmetric encryption.

Symmetric encryption relies on a key exchange ceremony and requires the use of a Hardware Security Module (HSM) or a signed waiver from the bank for key handling. Asymmetric encryption, on the other hand, relies on dynamic key exchange.

For more information on encryption, refer to the 'Get Encryption Certificate' API.

Security

The API uses asymmetric encryption to secure the exchange of sensitive PIN information.

PCI-DSS compliance:

The PIN exchange strategy has been certified by the Payment Card Industry Data Security Standard (PCI-DSS), ensuring compliance with industry standards.

Secure storage of card information

The API uses software encryption and PIN block algorithms, eliminating the need for an HSM.

How It Works

This API allows for the secure configuration of a PIN on a card for Point of Sales (POS) purchases. In order to ensure the security of the PIN, the API requires the use of another API, known as the 'Get Encryption Certificate' API, to prepare the PIN before it is transported.

To use this API, the following steps must be followed:

Retrieve the encryption certificate by calling the 'Get Encryption Certificate' API. This will provide a X509 certificate containing a public key specific to your institution. Obtain the raw PIN from the cardholder through your own channels. It is important to note that this process should not be logged or stored in any way.

If you do not have access to the Card PAN, use the Card Lookup API to retrieve it. The Card PAN is required to form the Pinblock using the ISO 9564 Pinblock format Algorithm.

Form the Pinblock and encrypt it using the certificate obtained in step 1. It's important to note that the Pinblock must be in a Hexstring format before encryption. Use the encrypted Pinblock in this API to configure the PIN on the card.

This API uses a combination of software encryption (RSA 4096) and the PIN Block algorithm to ensure the secure exchange of sensitive information. Furthermore, it does not require the use of Hardware Security Modules (HSM) and can be integrated within your own applications. Additionally, the API is PCI-DSS certified, meaning that it has been certified as compliant with the Payment Card Industry Data Security Standard, and thus you don't have to worry about the security of this API.

Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

https://api-sandbox.network.global

Card Set Pin

Download

Status:

Production

Version:

V2

Category:

Pin Management
/SB/CardServices/Transaction/V2/CardSetPin
curl --location --request POST '#{PARAM_URL}' --header 'Authorization: Bearer {{ access_token }}' {custom_headers} --data-raw '#{JSON_PAYLOAD}'
curl --location --request GET 'https://api-sandbox.network.global/v1/tokenkc/generate' \--data-raw '#{JSON_PAYLOAD}'
curl --location --request POST 'https://api-sandbox.network.global/v1/tokenkc/generate' \--data-raw '#{JSON_PAYLOAD}'

Node Child Node Type Length Description
Authorization* requiredBearer xxxx* requiredstringAuthorization Header (Bearer Token)
Content-Type* requiredapplication/json* requiredstringContent Type

Node TypeTypeLengthDescription
NISrvRequestrequest_card_set_pinheadermsg_id* requiredstring12Message ID, this field should be unique id for each Api call. This will be generated from client side. If the same message ID is used the system will decline the API call with Error Description “Duplicate Message ID”
msg_type* requiredstring12Message Type – This can have either “TRANSACTION” or “ENQUIRY” As for this API the value expected is “TRANSACTION”
msg_function* requiredstring50Static Value - REQ_CARD_SET_PIN
src_application* requiredstring10Source Application: This is a free Text and the client can populate the source system from where the API is Initiated Example: IVR, IB, MB No Validations of these are kept at Network Systems
target_application* requiredstring10The target_application can hold any value from FI side, this can be used by FI to check the target system of the API call
timestamp* requiredstring30Timestamp of the request - Format YYYY-MM-DDtHH:MM:SS.SSS+04:00
bank_id* requiredstring4Bank Id is Unique Id 4 digit code for each client and the same will be provided once the client setup is completed in our core system. For sandbox testing – Please use “NIC”
bodycard_identifier_id* requiredstring32Card Identifier Id
card_identifier_type* requiredstring20CONTRACT_NUMBER is used for clear card number or EXID which is a unique identifier for the card generated by CMS
card_sequence_numberstring2Card sequence number Example 01
card_expiry_date* requiredstring42605
encrypted_pin* requiredstring20Encrypted Pin block under ZPK Ex: 7B47D3321D4A5F63
encryption_method* requiredstring20Encryption Method to be used for the encryption of the pin

{
    "NISrvRequest": {
        "request_card_set_pin": {
            "header": {
                "msg_id": "236001",
                "msg_type": "TRANSACTION",
                "msg_function": "REQ_CARD_SET_PIN",
                "src_application": "IVR",
                "target_application": "WAY4",
                "timestamp": "2020-07-20T10:49:02.366+04:00",
                "bank_id": "NIC"
            },
            "body": {
                "card_identifier_id": "99984100148297467162",
                "card_identifier_type": "EXID",
                "card_sequence_number": "01",
                "card_expiry_date": "2704",
                "encrypted_pin": "F41AB9C3974FE7A9",
                "encryption_method": "SYMMETRIC"
            }
        }
    }
}

Node Child Node Type Length Description
Content-Typeapplication/jsonstringContent Type

Node TypeTypeLengthDescription
NISrvResponseresponse_card_set_pinheadermsg_id* requiredstring12Message ID, this field should be unique id for each Api call. This will be generated from client side. If the same message ID is used the system will decline the API call with Error Description “Duplicate Message ID”
msg_type* requiredstring12Message Type – This can have either “TRANSACTION” or “ENQUIRY” As for this API the value expected is “TRANSACTION”
msg_function* requiredstring50Static value - REP_CARD_SET_PIN
src_application* requiredstring10Source Application: This is a free Text and the client can populate the source system from where the API is Initiated Example: IVR, IB, MB No Validations of these are kept at Network Systems
target_application* requiredstring10The target_application can hold any value from FI side, this can be used by FI to check the target system of the API call
timestamp* requiredstring15Timestamp of the response - Format YYYY-MM-DDtHH:MM:SS.SSS+04:00
bank_id* requiredstring4Bank Id is Unique Id 4 digit code for each client and the same will be provided once the client setup is completed in our core system. For sandbox testing – Please use “NIC”
exception_detailsapplication_name* requiredstring20Application Name
date_time* requiredstring30Timestamp of the response Format “YYYY-MM-DD HH:MM:SS”
status* requiredstring1Status of the request (S/F)
error_code* requiredstring4EAI Internal Error Code (Check error codes section for the complete list of error codes and error code descriptions)
error_description* requiredstring100Error Description (Check error codes section for the complete list of error codes and error code descriptions)
transaction_ref_idstring20The tracking_id sent in the request will be sent back in response in this field.

{
    "NISrvResponse": {
        "response_card_set_pin": {
            "header": {
                "msg_id": "236001",
                "msg_type": "TRANSACTION",
                "msg_function": "REP_CARD_SET_PIN",
                "src_application": "IVR",
                "target_application": "WAY4",
                "timestamp": "2020-07-20T10:49:02.366+04:00",
                "bank_id": "NIC"
            },
            "exception_details": {
                "application_name": "TCC-ADP",
                "date_time": "2023-02-01T16:39:47.314+04:00",
                "status": "S",
                "error_code": "000",
                "error_description": "Success"
            }
        }
    }
}

Code Description
200Sample Description
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error
502Bad gateway
503Scheduled Maintenance
504Gateway Timeout
596Service Not Found

How It Works

Follow the steps below. For more details, read the Quick Start Guide.

1- Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

2- Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

3- Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

4- Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.

5- Process 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Amet, sed at amet cras fringilla adipiscing nunc, in pulvinar. Sagittis pellentesque leo et proin convallis justo vitae in.