Applying REST API

Sign Up Callback (Application Implementation)

In order to use login, the callback URL registered in the Login API Setting must be implemented as follows.

Callback for user Encrypt/Decrypt Key exchange

Authentication data and user information are provided securely as encrypted data using Encrypt/Decrypt Key provided by the application.
In order for this to work, the application user’s Encrypt/Decrypt Key is provided by performing callback communication with the URL registered in the Developer Center sign-up process

The HTTP request/response standard of the user Encrypt/Decrypt Key exchange callback is as follows

1. HTTP Request

POST /Applicaiton-Callback-URL HTTP/1.1
Host: Application-Server-Domain
Content-type: application/json;charset=utf-8

2. Parameter

3. Response

• Sample Request/Response JSON

- HTTP Request Body

{	 	
  client_id: "Application Client ID",
  used_type: "1",
  ptn_cd: "Application User Code",
  public_key: "public key (RSA)",
}

- HTTP Response Body

{
  code: "0000",
  message: "",	
  result: {
    enc_partner_key: "Application User Encrypt/Decrypt Key"
  }
}

Example of Encrypt/Decrypt Key generation

Above Application’s user Encrypt/Decrypt Key has to be returned and RSA encrypted with public key that ifree provides.

Below is an example of using SDK that provides for RSA encryption

// Create user Encrypt/Decrypt Key (Random Code)
String user_encrypt_key = CryptUtil.generateCryptKey();

// Encrypt user 'Encrypt/Decrypt Key'
String enc_partner_key = CryptUtil.encryptCryptKey(public_key, user_encrypt_key);

// RSA Encryption
KeyFactory factory = KeyFactory.getInstance("RSA");
byte[] publicKeyBytes = Base64.getDecoder().decode(publicKey);
X509EncodedKeySpec x509Spec = new X509EncodedKeySpec(publicKeyBytes);
PublicKey pk = factory.generatePublic(x509Spec);
Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
cipher.init(Cipher.ENCRYPT_MODE, pk);
byte[] encryptBytes = cipher.doFinal(plainText.getBytes());
String enc_partner_key = Base64.getEncoder().encodeToString(encryptBytes);

Callback to complete user registration

When the app user registration is completed, callback to complete user sign up is performed using callback URL registered in application.

Request/Response form for HTTP communication is as follows

1. HTTP Request

POST /Application-Callback-URL HTTP/1.1
Host: Application-Server-Domain
Content-type: application/json;charset=utf-8

2. Parameter

3. Response

• Sample Request/Response JSON

- HTTP Request Body

{	 	
  client_id: "Application Client ID",
  used_type: "2",
  ptn_cd: "Application user code",
  partner_sp: "Application User Super Passcode (Encrypted)",
  ubifill: "Application User Information (Encrypted)"
}

- HTTP Response Body

{
  code: "0000",
  message: ""
}

Example of Decrypting user Super Passcode and user information

partner_sp, ubifill information is encrypted using user Encrypt/Decrypt Key that the application provides.

Below is an example of using SDK for decrypting the above information.

// partner_sp Decryption
String decryptedPartnerSp = CryptUtil.decryptPartnerSp(user_encrypt_key, partner_sp);

// ubifill Decryption
UserInfo userInfo = CryptUtil.decryptUbifill(user_encrypt_key, ubifill);
// userInfo.getEmail();
// userInfo.getUserName();
// userInfo.getPhoneNumber();

Authentication (provided by ifree)

Access Token generation

ptn_token (created by SDK) is required to obtain Access Token for login authentication. For information on issuing ptn_token, please refer to SDK (Android, iOS, JavaScript) documentation.

Request/response format for HTTP callback communication is as follows

1. HTTP Request

POST /process/token HTTP/1.1
Host: partner-auth.ifree.world
Content-type: application/json;charset=utf-8

2. Parameter

3. Response

• Sample Request/Response JSON

- HTTP Request Body

{	 	
  client_id: "Application Client ID",
  secret_key: "Application Server Secret Key",
  ptn_token: "Application Authentication token"
}

- HTTP Response Body

{
  code: "0000",
  message: "",
  result: {
    acs_token: "Access Token",
    expire_dt: "Access Token Expiration date (yyyyMMddHH24miss format)",
    ptn_cd: "Application user code"
  }
}

Example of Access Token generation

Below is an example of using SDK to issue access token

try {
  APIClient client = new APIClient();
  client.init(clientID, secretKey);
  APIResponse<AccessTokenRes> response = client.getAccessToken(ptn_token);
  if (!"0000".equals(response.getCode())) {
    // check error message (response.getMessage())
  } else {
    AccessTokenRes result = response.getResult();
    // check access token
    result.getAccessToken();
    // check application user code
    result.getUserCode();
  }
} catch (APIResponseException e) {
  // e.getHttpStatusCode() : http status code 
} catch (IOException e) {
  // Connection Error
}

User Authentication

User authentication is performed using access token which was created doing ‘Access Token creation’. It is also able to check if ptn_sp provided by authentication request response equals partner_sp which was provided in registration process.

Request/response format for HTTP communication is as follows

1. HTTP Request

POST /process/authenticate HTTP/1.1
Host: partner-auth.ifree.world
Content-type: application/json;charset=utf-8

2. Parameter

3. Response

• Sample Request/Response JSON

- HTTP Request Body

{	 	
  client_id: "Application Client ID",
  secret_key: "Application Server Secret Key",
  acs_token: "Application Access token"
}

- HTTP Response Body

{
  code: "0000",
  message: "",
  result: {
    ptn_sp: "Application user Super Passcode (Encrypted)",
  }
}

Example for User Authentication

Below is an example of SDK that provides for user authentication

try {
  APIClient client = new APIClient();
  client.init(clientID, secretKey);
  APIResponse<AuthRes> response = client.authenticate(acs_token);
  
  if (!"0000".equals(response.getCode())) {
    // check error message (response.getMessage())
  } else {
    AuthRes result = response.getResult();
    // check Application user Super passcode
    String decryptedPartnerSp = CryptUtil.decryptPartnerSp(user_encrypt_key, result.getPartnerSP());
    // check if decryptedPartnerSp equals partner_sp that was registered in application
  }
} catch (APIResponseException e) {
  // e.getHttpStatusCode() : http status code 
} catch (IOException e) {
  // Connection Error
}

SDK Dependency Setting

Libraries for Java development are provided on the SDK download page.

After downloading the library, add maven dependency as follows.

<dependencies>
  <dependency>
    <groupId>com.rowem.ifree</groupId>
    <artifactId>ifree-sdk-rest-client-java</artifactId>
    <scope>system</scope>
    <systemPath>path-to-library</systemPath>
  </dependency>
</dependencies>