Authentication and Token Retrieval

User Login

To make requests to marketplace services, you first need to obtain a token via the authentication service.

This token will be used in the Authorization header in all other API requests.

Authenticate Service

Endpoint Information

TEST Environment:

POST https://apitest.paynkolay.com.tr/marketplace/v1/authenticate

PROD Environment:

POST https://api.paynkolay.com.tr/marketplace/v1/authenticate

Request Parameters

{
  "username": "nkolay_marketplace",
  "password": "nkolaypassword",
  "merchantNo": "400000904"
}

Parameter Descriptions

Parameter	Type	Required	Description
username	String	✅	Username created for you
password	String	✅	Password created for you
merchantNo	String	✅	Merchant number created for you

Security Warning

The above values are example values. Your actual username, password, and merchantNo values will be provided to you specifically by Pay N Kolay.

Never hardcode these credentials into your code; store them securely in environment variables or secure vaults.

Response Format

After a successful authentication, you will receive a response like this:

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "SUCCESS",
  "data": {
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJua29sYXlfbWFya2V0cGxhY2UiLCJleHAiOjE3NjI5NDY0NTYsImlhdCI6MTc2Mjk0NDY1Nn0.KzUrZmGymeI0Tzqss8XNJzWrCrVmPEtcbep1hXDpqxZ4ALHNk3DQoepdVWWsXs6gnhj3njWgk2klHcrBfn2OLw"
  }
}

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates whether the operation was successful
responseCode	String	Operation result code (200 = Successful)
responseMessage	String	Operation result message
data.token	String	Access token in JWT format (to be used as Bearer token)

Token Usage

You should use the token you received as a Bearer Token in the Authorization header in other API requests.

Example Usage

curl -X POST https://apitest.paynkolay.com.tr/marketplace/v1/seller/get \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "sellerExternalId": "SELLER123"
  }'

JavaScript/TypeScript Example

// Get token
const getToken = async () => {
  const response = await fetch(
    'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        username: process.env.MARKETPLACE_USERNAME,
        password: process.env.MARKETPLACE_PASSWORD,
        merchantNo: process.env.MARKETPLACE_MERCHANT_NO,
      }),
    }
  );

  const data = await response.json();
  return data.data.token;
};

// API call with token
const callAPI = async (token) => {
  const response = await fetch(
    'https://apitest.paynkolay.com.tr/marketplace/v1/seller/get',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sellerExternalId: 'SELLER123',
      }),
    }
  );

  return await response.json();
};

PHP Example

<?php
// Get token
function getToken($username, $password, $merchantNo) {
    $url = 'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate';

    $data = [
        'username' => $username,
        'password' => $password,
        'merchantNo' => $merchantNo
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $result = json_decode($response, true);
    return $result['data']['token'];
}

// API call with token
function callAPI($token, $sellerExternalId) {
    $url = 'https://apitest.paynkolay.com.tr/marketplace/v1/seller/get';

    $data = [
        'sellerExternalId' => $sellerExternalId
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Usage
$token = getToken(
    getenv('MARKETPLACE_USERNAME'),
    getenv('MARKETPLACE_PASSWORD'),
    getenv('MARKETPLACE_MERCHANT_NO')
);

$result = callAPI($token, 'SELLER123');
?>

Token Management

Token Expiration

• JWT tokens expire after a certain period
• The token’s exp (expiration) claim contains the validity period
• When the token becomes invalid, you need to obtain a new token

Best Practices

1. Cache the Token: Instead of getting a new token for every API request, use the existing token
2. Token Refresh: Obtain a new token before the current one expires
3. Error Handling: Refresh the token when you receive a 401 Unauthorized error
4. Secure Storage: Store tokens securely (memory, secure storage)

Token Refresh Example

class MarketplaceAPIClient {
  constructor(username, password, merchantNo) {
    this.credentials = { username, password, merchantNo };
    this.token = null;
    this.tokenExpiry = null;
  }

  async ensureValidToken() {
    // Get new token if none exists or if expired
    if (!this.token || Date.now() >= this.tokenExpiry) {
      await this.refreshToken();
    }
    return this.token;
  }

  async refreshToken() {
    const response = await fetch(
      'https://apitest.paynkolay.com.tr/marketplace/v1/authenticate',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(this.credentials),
      }
    );

    const data = await response.json();
    this.token = data.data.token;

    // Parse expiry time from JWT
    const payload = JSON.parse(atob(this.token.split('.')[1]));
    this.tokenExpiry = payload.exp * 1000; // convert to milliseconds
  }

  async callAPI(endpoint, body) {
    const token = await this.ensureValidToken();

    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    // If we get 401 error, refresh token and retry
    if (response.status === 401) {
      await this.refreshToken();
      return this.callAPI(endpoint, body);
    }

    return await response.json();
  }
}

Security Keys

Other important security keys used in the Marketplace API:

Key	Description	Usage
apiSecretKey	SX value - Used for payment operations	Payment, Seller, Profile services
merchantSecretKey	Used in hash calculation for payment operations	Hash calculation
apiSecretKey (cancel)	Special SX value for cancellation operations	Cancel/Refund services

Information

These keys will be provided to you specifically by Pay N Kolay, and different keys are used for different operations.

Next Steps

After obtaining the token:

1. Hash Calculation - Hash calculation for payment operations
2. Create Payment Profile - Define your first payment profile
3. Add Seller - Add your first seller to the system