Authentication and Token Retrieval

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 Paynkolay.

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 #

// Token alma
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;
};

// Token ile API çağrısı
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
// Token alma
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'];
}

// Token ile API çağrısı
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);
}

// Kullanım
$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 #

Cache the Token: Instead of getting a new token for every API request, use the existing token
Token Refresh: Obtain a new token before the current one expires
Error Handling: Refresh the token when you receive a 401 Unauthorized error
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() {
    // Token yoksa veya süresi dolmuşsa yeni al
    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;

    // JWT'den expiry time'ı parse et
    const payload = JSON.parse(atob(this.token.split('.')[1]));
    this.tokenExpiry = payload.exp * 1000; // milisaniyeye çevir
  }

  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),
    });

    // 401 hatası alırsak token'ı yenile ve tekrar dene
    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 (iptal)	Special SX value for cancellation operations	Cancel/Refund services

These keys will be provided to you specifically by Paynkolay, 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