Findeks is a credit scoring system used to verify customer eligibility for car rental services. This integration helps assess customer creditworthiness before completing rental reservations, reducing financial risks for both agencies and rental companies.
The Findeks integration provides a comprehensive credit verification workflow that includes:
- Credit Eligibility Check: Quick verification of customer credit status
- Phone Number Verification: Multi-step authentication using customer's registered phone numbers
- Credit Report Generation: Detailed credit assessment for qualified customers
- PIN-based Security: SMS-based verification for secure credit reporting
The complete Findeks verification process follows these steps:
1. Initial Check → /findeks/check
2. Get Phone List → /findeks/phone-list (if needed)
3. Generate Report → /findeks/report (if Unknown status)
4. Confirm PIN → /findeks/pin-confirm
5. Renew PIN → /findeks/pin-renew (if expired)
6. Final Verification → /findeks/check (recheck status)- Positive/Positive With Young Driver → Approve rental
- Negative → Reject rental
- Unknown → Continue with phone verification and report generation
All Findeks endpoints require bearer token authentication:
Authorization: Bearer YOUR_ACCESS_TOKENPerforms an initial credit eligibility check for a customer.
POST /findeks/check| Field | Type | Required | Description |
|---|---|---|---|
identityNumber | string | Yes | Customer's national identity number |
integrationCode | string | Yes | Integration tracking code from search result |
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/check \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"identityNumber": "11223344556",
"integrationCode": "integrationCode123"
}'Success Response (200 OK):
{
"status": "Positive"
}Possible Status Values:
"Positive"- Customer approved for rental"Negative"- Customer rejected for rental"Unknown"- Additional verification required"Positive With Young Driver"- Approved with young driver conditions
Error Responses:
400 Bad Request- Invalid request format or validation error401 Unauthorized- Invalid or missing access token500 Internal Server Error- Server error
Retrieves registered phone numbers for a customer to use in verification process.
POST /findeks/phone-list| Field | Type | Required | Description |
|---|---|---|---|
identityNumber | string | Yes | Customer's national identity number |
integrationCode | string | Yes | Integration tracking code from search result |
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/phone-list \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"identityNumber": "11223344556",
"integrationCode": "integrationCode123"
}'Success Response (200 OK):
{
"phoneList": [
{
"key": 711957237,
"phone": "533*****36"
},
{
"key": 711957238,
"phone": "505*****42"
}
]
}Response Fields:
key- Unique identifier for the phone number (used in report generation)phone- Masked phone number for privacy protection
Creates a detailed Findeks credit report using complete customer information.
POST /findeks/report| Field | Type | Required | Description |
|---|---|---|---|
identityNumber | string | Yes | Customer's national identity number |
birthDate | string (date) | Yes | Customer's birth date (YYYY-MM-DD) |
driverLicenseDate | string (date) | Yes | Driver license issue date (YYYY-MM-DD) |
phone | string | Yes | Customer's phone number (E.164 format) |
phoneKey | integer | Yes | Phone key from phone list response |
integrationCode | string | Yes | Integration tracking code from search result |
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/report \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"identityNumber": "45473452",
"birthDate": "1994-01-15",
"driverLicenseDate": "2012-03-20",
"phone": "+905554443322",
"phoneKey": 123,
"integrationCode": "integrationCode123"
}'Success Response (200 OK):
{
"findeksCode": 182783973
}Response Fields:
findeksCode- Generated code for the credit report (used for PIN confirmation)
Note: After successful report generation, a PIN will be sent to the customer's phone number for verification.
Confirms the PIN sent to customer's phone to authorize the credit check process.
POST /findeks/pin-confirm| Field | Type | Required | Description |
|---|---|---|---|
findeksCode | string | Yes | Findeks code from report generation |
pinCode | string | Yes | PIN code received via SMS |
integrationCode | string | Yes | Integration tracking code from search result |
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/pin-confirm \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"findeksCode": "45473452",
"pinCode": "123456",
"integrationCode": "integrationCode123"
}'Success Response (204 No Content):
No response body. A 204 status indicates successful PIN confirmation.
Error Responses:
400 Bad Request- Invalid PIN or request format401 Unauthorized- Invalid or missing access token500 Internal Server Error- Server error
Requests a new PIN when the original PIN has expired or was not received.
POST /findeks/pin-renew| Field | Type | Required | Description |
|---|---|---|---|
findeksCode | string | Yes | Findeks code from report generation |
integrationCode | string | Yes | Integration tracking code from search result |
curl -X POST https://api.pro.yolcu360.com/api/v1/findeks/pin-renew \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"findeksCode": "45473452",
"integrationCode": "integrationCode123"
}'Success Response (204 No Content):
No response body. A 204 status indicates successful PIN renewal.
Error Responses:
400 Bad Request- Invalid request format401 Unauthorized- Invalid or missing access token500 Internal Server Error- Server error
Here's a complete workflow implementation example:
async function performFindeksVerification(customerData) {
const {identityNumber, integrationCode, birthDate, driverLicenseDate, phone} = customerData;
try {
// Step 1: Initial eligibility check
const initialCheck = await checkFindeksEligibility(identityNumber, integrationCode);
if (initialCheck.status === 'Positive' || initialCheck.status === 'Positive With Young Driver') {
return {approved: true, status: initialCheck.status};
}
if (initialCheck.status === 'Negative') {
return {approved: false, status: 'Negative'};
}
// Step 2: For Unknown status, get phone list
if (initialCheck.status === 'Unknown') {
const phoneList = await getFindeksPhoneList(identityNumber, integrationCode);
// Step 3: Generate report with selected phone
const selectedPhone = phoneList.phoneList[0]; // User selects appropriate phone
const report = await generateFindeksReport({
identityNumber,
birthDate,
driverLicenseDate,
phone,
phoneKey: selectedPhone.key,
integrationCode
});
// Step 4: Get PIN from user and confirm
const pinCode = await getPinFromUser(); // Implementation depends on UI
await confirmFindeksPin(report.findeksCode, pinCode, integrationCode);
// Step 5: Recheck status after PIN confirmation
// Note: Status update may take up to 1 minute
await waitForStatusUpdate();
const finalCheck = await checkFindeksEligibility(identityNumber, integrationCode);
return {
approved: finalCheck.status.startsWith('Positive'),
status: finalCheck.status
};
}
} catch (error) {
if (error.message.includes('PIN')) {
// Handle PIN renewal if needed
await renewFindeksPin(findeksCode, integrationCode);
return performFindeksVerification(customerData); // Retry
}
throw error;
}
}
async function checkFindeksEligibility(identityNumber, integrationCode) {
const response = await fetch('/api/v1/findeks/check', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({identityNumber, integrationCode})
});
if (!response.ok) throw new Error('Findeks check failed');
return response.json();
}
async function waitForStatusUpdate() {
// Wait for status update (can take up to 1 minute)
return new Promise(resolve => setTimeout(resolve, 60000));
}| Code | Description |
|---|---|
| 1001 | Error while parsing payload |
| 1002 | Validation error |
| 1003 | Parameter error |
| 2001 | Unauthorized |
| 2002 | Forbidden |
| 5001 | Agency configuration not found |
- Handle Async Status Updates: After PIN confirmation, status updates can take up to 1 minute
- Implement Retry Logic: Handle PIN renewal scenarios gracefully
- Secure PIN Handling: Never log or store PIN codes
- Error Recovery: Implement proper error handling for each step
- User Experience: Provide clear feedback during the verification process
- Timeout Handling: Set appropriate timeouts for PIN entry
- Never store or log customer identity numbers or PIN codes
- Handle sensitive data according to GDPR and local privacy regulations
- Use HTTPS for all API communications
- Validate all input parameters before API calls
- Implement proper session management for multi-step verification
- Use secure storage for temporary verification state
- Clear sensitive data from memory after use
Unknown Status Persists
- Ensure all required customer information is accurate
- Verify phone number format (E.164)
- Check that PIN confirmation was successful
PIN Not Received
- Use the PIN renewal endpoint
- Verify phone number is correct and active
- Check for SMS delivery delays
Verification Timeout
- Implement retry logic with exponential backoff
- Check API rate limits
- Verify integration code is valid for the session
- Test with various identity numbers to understand different status responses
- Implement proper error handling for network timeouts
- Test PIN renewal scenarios
- Verify status update timing in different environments