Skip to main content

Authentication

Introduction​

YUKK APIs use a two-step authentication mechanism to ensure secure communication between your application and YUKK services. Before calling any business API, you must first obtain a B2B Access Token using asymmetric authentication. Once authorized, subsequent API requests must include the access token and a request signature generated using HMAC-SHA512.

  1. B2B Token Acquisition (Asymmetric Auth): To begin a session, your system must request an Access Token using your Client ID and a digital signature generated via SHA256withRSA with your private key and a timestamp.
  2. API Service Requests (Symmetric Auth): Once authorized, subsequent API calls (such as payments or transfers) must include:
    • Bearer Token: The accessToken retrieved in step one.
    • Request Signature: A dynamic HMAC_SHA512 signature generated for every request. This signature validates the request body, timestamp, and endpoint URL using your Client Secret.

IP Whitelist Request Procedure​

[Download Here] - To ensure only trusted servers can access APIs, partners are required to register their IP addresses.

This process includes submitting, updating, and revoking IPs to maintain the highest security level in compliance with YUKK standards.

Steps:

  • Submit the IP whitelist request to YUKK.
  • Provide required details (IP address, environment, purpose).
  • Update or revoke IPs if changes are needed.
  • YUKK verifies and approves the request.

Private & Public Key​

This mechanism is designed to obtain an access token that serves as authentication before accessing other APIs.

  • Partners generate a pair of keys: a private key and a public key.
  • The private key must be securely stored on the partner’s system.
  • The public key is submitted to YUKK (via email) for registration.

When requesting a token:

  • The partner uses the private key to generate the X-SIGNATURE.
  • YUKK then validates the X-SIGNATURE against the previously registered public key.

This process ensures that only authorized requests from trusted partners are accepted.

SNAP Signature​

Asymmetric in B2B Access Token (SHA256withRSA)​

The asymmetric signature is used specifically to request the initial B2B Access Token.
Partners sign the payload using their Private Key, and YUKK validates it using the partner's registered Public Key.

1. Asymmetric Key Generation

The below will explain about asymmetric key generation:

  • Create Private Key

Generate a standard secure 2048-bit RSA private key:

openssl genrsa -out rsa_private_key.pem 2048
  • Export Public Key

Extract the public key from the generated private key:

openssl rsa -in rsa_private_key.pem -out rsa_public_key.pem -pubout

Partner should generate the signature with rsa_private_key.pem and YUKK will use rsa_public_key.pem to validate the signature and vice versa.

2. Digital Signature Generation

The below are steps of digital signature generation:

  • Compose the string to sign:
SHA256withRSA (Private_Key, stringToSign).with formula stringToSign = client_ID + “|” + X-TIMESTAMP

  • The signature string is generated from string to sign above with applying SHA-256 with RSA-2048 encryption using pkcs8 private key, and then encode the result to base64.

  • Put the signature string into HTTP header “X-SIGNATURE“ when call API for applying B2B access token.

Example:

● stringToSign = client_ID + “|” + X-TIMESTAMP
9JYVuBkHmPSuMAJRmpN2|2022-10-06T15:08:00+07:00

â—Ź Private_Key
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA2pjFs43FkA9/s3kGNYquRqq/QyV9Iscwp1uKiI2qLUzI4FAd
BoHx2+pdVTWkOxvqpxUBzYo2joaFA7VQqyjUwSzFnYTIdRnmU/59cuf/xHDc8OsP
NL8DvXlFj0B9mX253P+LBxWCeM+q1nXKo6xmIK6JYNKSIlyGhhSwHVQMdGE+TYAI
KeVuvvrbsj8rcZxlPSch0GfNO+q/eB5qqmBnmiks3IMu020pj4830G7Y9ksX7JJs
Y3H55VUA9Hlw0MazuLudo/G3+xAxpaIZoFyuCwJDm5VCNtpLUESJIJlGeXxchJ3R
sBBOpRgdKy+1dtjlj6MKk+Q0qmh6/e8MkgJdCwIDAQABAoIBAQDCNg0gM4sdLMf2
OkYr96RSoI0BKSN+bJ5rckcof0R8rsWhlUvUZkrtadG2TMw2v9zAyUcqx+skwZsX
6lVbXBF59z8zba9zaqlaYrYuCrUQYH3LheuinzrBcic82L0+S5eAI4Hvr0qV71sG
4uxAcoDh9G+VmD/BS5cxNNwrkmrmUYLaOmaR56AsKXLbG37PeJZpnIPEl/VAuDK5
Ww/cibT1DVY2HKM3AW3zPIGlY7MlJRcV5ztu6d8iUwA61Yy8XeamUhyRzkKvi5Y8
ScvpgIQrysFHl3O3aZciJivlLPLIprdJI+HvJYOz+NTa+2IoRJhBvHva7G0zNwj5
jI+eOtWhAoGBAO9mojwmmSNCLaQ3et6I1sb+XC77Es2dVy1kX0RfuDwqZ73SlLg1
TjVVEJlcyU+wqth+G8OTYkRm0O2W1bm5CyFsJZlBMpndNjGnqtLlrjDOjM1rL6tJ
2I8um1OI3m2e3W9oEQdEk5sF7h0oPkW0C7XUj98ikVNLOEunhx+sUmhpAoGBAOnA
3WyRnfnH6DUumzWnzPzKS3T4OaJmAKv79jC/p2ppNkqcSKjPv2JM5aM8W2o6U1Ti
AaHLhu26BQ29II5PRL4rBv+lgHaLCXwgwI33jk6c1F9BKZiDey1UPkPHeVHF0Wix
ifRcB+euMsNq4086KKS7tqpt/WZhlnfPPK74ngtTAoGASD1wNzZuf3U40JTtPrmM
FgArUQHyaplP9SKUnM1FiuJA68bfmbZ8IxvIJn8ZQDLPWwSy3BFdVcawxQD+/UwZ
T7ySm+xQmJ1n/RPbOEiWh6PMWTA+8jEWaB5oQIzMkceeij+c49SNtfnUIHhEUkRC
RFwgDfUgZUINesbSv3wAYgECgYEAzBMVPTPkN63PjJ6j4rQcwpXaSsRrjNyAuaW/
yc+I2d4BCCJpTPgSnj+EPH71UEibd//YbOjDY8iDoPr88UFDQsNN2OMkxFmebkAp
28fE9dz1jDPXnM8tOuXRdlswD7QknsJhLnUqcZojt3gZ+5FK6ob3ctOT505Lj03e
LOPhFwECgYAZpLsKFxyPgzncYT4s5fB6Pa35EWc4LSKxUE7hc+Tq156bxz5fNcb3
aZ5Qqn88MCfAEJPzKjM874fTVu3DSdUwYpxFc6xgpBpbqoK7+Qj5HY/HH60R8eg1
0NWybzUZolpzusBSJ3QxTY6Isbrpyp8QwziIaHPJBaI+UMwyxOjTnw==
-----END RSA PRIVATE KEY-----

Result:

RUTGZ+FobSdHjoXKEpOA+YTFNUOX2WKQ2JNWQCA2evw5cy6tQ7eBLIbx4u9aycReXmsAKTY8op0MsIO6ZAMpW7Dg
Yuy1dLmvZg+gkNt9myYqzaGPWf/LmG8epIxkOJA3IHi7CVPzQrH/2Aq2Ez5tyPIQAmNC//sOGL6CJLOrSGL24g7Vr
FgkXDcPsOD28FESBTPURRftgY3K4bZLF5QotVq937TO6Rks/2bFnfhBljuOf3bZu1Xw0SuNZK2FTj1txduCHnnfZR
nZMTs0D4Y4bWhZI35oN6xfDZN61VZFP0ZvixTebwaB6d/nXlt9qohK8OZqmw41HvzQHydpBHZq8g==
Code Example

Below are code samples for generating both asymmetric and symmetric digital signatures across different programming languages:

Programming languageSample Code
PHPView Sample
GoView Sample
JavaView Sample
PythonView Sample
JavascriptView Sample

Symmetric in API services (HMAC_SHA512)​

The symmetric signature is used to access transaction API services and requires a valid Access Token.

Payload Structure​

The payload is composed of several elements:

  • Path – The URL path (excluding hostname, port, and query parameters).
    Example: /snap/v1.0/dummy
  • Verb – The HTTP method in uppercase (GET, POST, PUT, PATCH, DELETE).
  • Token – The authorization token taken from the Authorization header.
    Example: Bearer R04XSUbnm1GXNmDiXx9ysWMpFWBr
  • Timestamp – The exact time the API call is made. Must follow ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ) in UTC (GMT+0).
    Example: 2021-11-02T13:14:15.678+07:00
  • Body – The request payload. Apply minify(RequestBody), then hash it using SHA-256, encode it in Hex, and lowercase the result.
    Example:
    Request body: \{"hello":"world"\}
    SHA-256 result: 93a23971a914e5eacbf0a8d25154cda309c3c1c72fbb9914d47c60f3cb681588

If the request does not include a body (e.g., a GET request), this field should remain empty.

Digital Signature Generation

The below are steps of digital signature generation:

  • Compose the string to sign:
HMAC_SHA512 (clientSecret,stringToSign) with formula stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken+":“+ Lowercase(HexEncode(SHA256(minify(RequestBody))))+ ":“ +TimeStamp

  • The signature string is generated from string to sign above with applying HMAC_SHA512 hashing using client secret key which given by YUKK, and then encode the result to base64.

  • Put the signature string into HTTP header “X-SIGNATURE“ when call YUKK API.

Example:

clientSecret
C7BR6aXzp5XjJT0UQD7FTPJtU94C5QsVpfCBElCY
stringToSign
POST:/payment-gateway/openapi/v1.0/transfer-va/create-va:eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwi
anRpIjoiNGEzMjgwODZjZmQ5NWVlYTU4MmI4NWI3MDEwMTA4ZmZhMjg2MjgyMzgxMTh
hYzNhMmE5ZjRlZmI0MmJkMzk4MjYwYzk4MTUxNjE0NTFkMmIiLCJpYXQiOjE2NjUwNDM4
MjAuMzY0MjY1LCJuYmYiOjE2NjUwNDM4MjAuMzY0MjcyLCJleHAiOjE2NjUwNDQ3MjAuM
zQxMDcyLCJzdWIiOiIxNiIsInNjb3BlcyI6W119.iZ9CShOTvz2-oPLjxM93vPLceauetLFFwYbgG4
2tnpqHON8v_1y1wKQDr_MZWZB66rMLRMmzVqo6vl1iyW77JZk10U-quFYQOz4kW5w7tvc
5zla8H2VeSKIkCgz_bVESMHZsHffms36bge7ZXhI3FEHG6Powq7HvSHo2ocr0ub_V1G0opX81
QMs1-9aGEpnqT_5DFihy4fVdgBts2tQX9hgDfWBu7ooAvdgNFu75mFd6CAlC3rI9xSvmkpuH
s2uqVVSwGaJY4gLiz4Y3M7eRK83nZ6OEKyIY80wG0-NP-G008mMmLxt8-ujsjPEGTL8t874fw
xhIJaH6ti3e8_V5_IJy_yx4DfzV8HqW8FHvyFKdzI-UFtmuGSoLJzQoMjlG7q5GXvaVgrIaXveVO
wHk4GTnKL6vVUQvXZtpI0U1duv2JdtGSC9znhuu5K1byyqamJRYntxUw-DXdXVeDSaenPn0N
cF-CGdibyAZPdPqIon7aLdCjee1eCaWtPCANGNQPc3J2R6bJuYgq2uTJyagKMhH6iw-s3E95AJ
LGaZCnH1FXf69mgQysnHC6YFhFLIvK8mMMgtbDEXRe1vDYKo0GlYjNy_8232Gbxf_PxFWnw
PG89tpmUf4Rbjx4fOt8I_OmV57EllnjsR_U4QzaR9VLFv2jefTPQp_dDSp-dxzJ5A:e1dcc500b1
4795d030f48f0667db6592a2c0f43115810d90a7e793500d549edf:2022-10-06T14:57:00+0
7:00

Result:

mzgO0XP9qRCPG+g+AzD3Ge7UkKxsnEgM3WGTZ5FKjVAipXWSdhDXIRSaONdaYlwuSx9VkX
muuHbpYTX87bKPjQ==
Code Example

Below are code samples for generating both asymmetric and symmetric digital signatures across different programming languages:

Programming languageSample Code
PHPView Sample
GoView Sample
JavaView Sample
PythonView Sample
JavascriptView Sample