Shopping Loan Application Management

Loan Application

Creates a loan application on behalf of the customer. Before calling this service, the Pre-Credit Assessment service must be called.

Endpoint: /loans/v1/facilitate/application/{preApprovedReferenceId} Method: POST Content-Type: application/json

Parameters

Parameter	Type	Description
preApprovedReferenceId	string (path)	The referenceId value returned from the Pre-Credit Assessment service

Request Parameters

{
  "nationalIdentityNumber": "12345678901",
  "gsmNumber": "5551234567",
  "orderId": "ORDER-12345",
  "orderDate": "2025-12-24T10:30:00",
  "totalTerm": 6,
  "timeToLive": 1735041000,
  "callbackUrl": "https://yourdomain.com/callback",
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Product Name",
        "categoryCode": "Category Code",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00,
        "sellerExternalId": "SELLER-001",
        "commissionRate": 1.00,
        "withholdingTax": 0.10,
        "marketplaceCost": 2.00
      }
    ]
  }
}

Parameter	Type	Description	Required
nationalIdentityNumber	string	Customer’s national ID number	Required
gsmNumber	string	Customer’s phone number (5XXXXXXXXX format)	Required
orderId	string	Order number (must be unique)	Required
orderDate	string	Order date (ISO 8601: YYYY-MM-DDTHH:mm:ss)	Required
totalTerm	integer	Selected number of terms	Required
timeToLive	integer	Application validity period (Unix timestamp)	Required
callbackUrl	string	URL where PaynKolay will send the application result	Required
cart	object	Cart information (same format as Pre-Approval Query)	Required
cart.items[].sellerExternalId	string	Seller ID	Optional
cart.items[].commissionRate	number	Commission rate (%)	Optional*
cart.items[].commissionAmount	number	Commission amount (TL)	Optional*
cart.items[].withholdingTax	number	Withholding tax	Optional
cart.items[].marketplaceCost	number	Marketplace cost	Optional

Note: Only one of commissionRate and commissionAmount fields should be filled.

Response Example

{
  "success": true,
  "referenceId": "81acf2ef-448c-43f3-978e-52757b4c621b",
  "referenceCode": "REF123456",
  "bankApproved": true,
  "bankResponseCode": "0",
  "bankResponseMessage": "Transaction Successful",
  "bankRedirectionUrl": "https://dpuat.aktifbank.com.tr/WebCreditApi/WebCredit?ecommerceref=3bb0f009-d15c-4eee-b2a1-cbc3cd959381",
  "paymentPlan": {
    "lendingAmount": 20100,
    "interestRate": 4.19,
    "term": 6,
    "totalPaymentAmount": 24101.05,
    "annualEffectiveInterestRate": 88.9781,
    "monthlyPayments": [
      {
        "term": 1,
        "amount": 4016.84,
        "dueDate": "2026-01-24T10:30:00"
      },
      {
        "term": 2,
        "amount": 4016.84,
        "dueDate": "2026-02-24T10:30:00"
      }
    ]
  }
}

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the operation was successful
referenceId	string	PaynKolay reference ID (used for application querying)
referenceCode	string	PaynKolay reference code
bankApproved	boolean	Indicates whether it was approved by the bank
bankResponseCode	string	Bank response code
bankResponseMessage	string	Bank response message
bankRedirectionUrl	string	Bank’s redirection URL. The customer must be redirected to this URL.
paymentPlan	object	Payment plan information
paymentPlan.lendingAmount	number	Loan amount (TL)
paymentPlan.interestRate	number	Interest rate (%)
paymentPlan.term	integer	Number of terms (months)
paymentPlan.totalPaymentAmount	number	Total payment amount (TL)
paymentPlan.annualEffectiveInterestRate	number	Annual effective interest rate (%)
paymentPlan.monthlyPayments	array[object]	Monthly payment details
paymentPlan.monthlyPayments[].term	integer	Installment number
paymentPlan.monthlyPayments[].amount	number	Monthly payment amount (TL)
paymentPlan.monthlyPayments[].dueDate	string	Payment date (ISO 8601)

Important Notes

1. Redirection: When the application is successful, you must redirect the customer to the bank’s page using the bankRedirectionUrl value.
2. Callback: After the bank transaction is completed, PaynKolay will send a POST request to your callbackUrl address.
3. referenceId: Save this value - it will be used to query the application status.

---

Query Application

Queries the status of a specific loan application.

Endpoint: /loans/v1/facilitate/query/loan/{loanApplicationReferenceId} Method: GET

Parameters

Parameter	Type	Description
loanApplicationReferenceId	string (path)	The referenceId value returned from the Loan Application operation

Response Example

{
  "loanApplication": {
    "bankType": "AKTIFBANK",
    "bankApplicationId": "BANK-APP-12345",
    "referenceId": "81acf2ef-448c-43f3-978e-52757b4c621b",
    "referenceCode": "REF123456",
    "merchantNo": 4003,
    "orderId": "ORDER-12345",
    "nationalIdentityNumber": "12345678901",
    "gsm": "5551234567",
    "totalTerm": 6,
    "type": "SHOPPING_LOAN",
    "isApproved": true,
    "timeToLive": 1735041000,
    "bankRedirectionUrl": "https://...",
    "applicationDate": "2025-12-24T10:30:00Z",
    "orderDate": "2025-12-24T10:30:00Z",
    "status": "APPROVED",
    "merchantCallbackUrl": "https://yourdomain.com/callback",
    "cart": {
      "totalPrice": 20100,
      "shippingPrice": 100,
      "items": [
        {
          "categoryCode": "ELECTRONICS",
          "name": "Product Name",
          "quantity": 1,
          "price": 20000,
          "priceWithoutDiscounts": 20000
        }
      ]
    },
    "paymentPlan": {
      "lendingAmount": 20100,
      "interestRate": 4.19,
      "term": 6,
      "totalPaymentAmount": 24101.05,
      "totalRefundAmount": 0,
      "annualEffectiveInterestRate": 88.9781,
      "monthlyEffectiveInterestRate": 7.4148,
      "monthlyPayments": [
        {
          "term": 1,
          "amount": 4016.84,
          "dueDate": "2026-01-24T10:30:00Z",
          "details": "1st Installment"
        }
      ]
    }
  }
}

Application Statuses

Status	Description
NEW	New application created
STARTED	Application is being processed
FAILED	Application failed
APPROVED	Application approved
REJECTED	Application rejected
CANCELLED	Application cancelled
REFUNDED	Full refund made
REFUNDED_PARTIAL	Partial refund made
REFUNDED_ANOMALY	Refund anomaly
TIMEOUT	Application timed out

---

Loan Refund Operations

Enables refunding of approved and used loans.

Endpoint: /loans/v1/facilitate/refund/{loanApplicationReferenceId} Method: POST Content-Type: application/json

Parameters

Parameter	Type	Description
loanApplicationReferenceId	string (path)	The referenceId value returned from the Loan Application operation

Request Parameters

{
  "refundAmount": 1000.00,
  "sellerList": [
    {
      "trxAmount": 1000.00,
      "refundedCommissionAmount": 10.00,
      "sellerExternalId": "SELLER-001",
      "withholdingTax": 2.00
    }
  ]
}

Parameter	Type	Description	Required
refundAmount	number	Amount to be refunded (minimum 0.01 TL)	Required
sellerList	array[object]	Seller-based refund information (for marketplace)	Optional
sellerList[].trxAmount	number	Transaction amount	Optional
sellerList[].refundedCommissionAmount	number	Refunded commission amount	Optional
sellerList[].sellerExternalId	string	Seller ID	Optional
sellerList[].withholdingTax	number	Withholding tax	Optional

Response Example

{
  "bankResponseCode": "0",
  "bankResponseMessage": "Transaction Successful",
  "bankReferenceId": "BANK-REF-789",
  "referenceId": "REFUND-REF-456",
  "success": true
}

Response Parameters

Parameter	Type	Description
bankResponseCode	string	Bank response code (“0” = successful)
bankResponseMessage	string	Bank response message
bankReferenceId	string	Bank reference number
referenceId	string	PaynKolay reference number
success	boolean	Indicates whether the operation was successful

Refund Notes

• Full or partial refunds can be made
• Refund amount cannot exceed the loan amount
• After a refund operation, the application status is updated to REFUNDED or REFUNDED_PARTIAL

---

Loan Reporting

Enables reporting and listing of loans.

Endpoint: /loans/v1/facilitate/reporting Method: GET

Query Parameters

Parameter	Type	Description	Required
startDate	string	Start date (ISO 8601)	Required
endDate	string	End date (ISO 8601)	Required
referenceId	string	To filter a specific application	Optional
statuses	array[string]	Status filter (NEW, APPROVED, etc.)	Optional
pageNumber	integer	Page number	Required
pageSize	integer	Number of records per page	Required

Example Request

GET /loans/v1/facilitate/reporting?startDate=2025-12-01T00:00:00Z&endDate=2025-12-31T23:59:59Z&pageNumber=0&pageSize=20&statuses=APPROVED,REJECTED

Response Parameters

Returns a paginated list of loan applications. Each application is in the same format as Query Application.

---

Error Management

The API returns appropriate HTTP status codes and error messages for failed requests.

HTTP Status Codes

Code	Description
200 OK	Operation successful
201 Created	A new resource was created
400 Bad Request	Bad request (invalid parameters)
401 Unauthorized	Authorization error (invalid token)
403 Forbidden	Access denied
404 Not Found	Resource not found
500 Internal Server Error	Server error

Error Response Format

Error messages are typically returned in JSON format:

{
  "success": false,
  "bankResponseCode": "99",
  "bankResponseMessage": "Error message description",
  "errorCode": "VALIDATION_ERROR",
  "errorMessage": "Detailed error description"
}

Common Errors and Solutions

Error	Cause	Solution
401 Unauthorized	Token invalid or expired	Get a new token
400 Bad Request	Missing or invalid parameter	Check request parameters
bankResponseCode != “0”	Bank operation failed	Check bank error message
TIMEOUT	Operation timed out	Retry the application

---

Complete Integration Flow

Follow all the steps of the shopping loan integration in order:

1. Authentication

POST /loans/authenticate
→ Get Token

2. Bank List

POST /loans/v1/facilitate/query/banks
→ Get bank list and show to customer

3. Bank Selection and Session

Customer selects bank
POST /loans/v1/facilitate/sessions/{bankCode}
→ Get referenceId (bankSessionReferenceId)

4. Payment Simulation (Optional)

POST /loans/v1/facilitate/simulation/{bankSessionReferenceId}
→ Show installment options to customer

5. Customer Information and Pre-Approval

Get national ID and phone number from customer
POST /loans/v1/facilitate/pre-approved/{bankSessionReferenceId}
→ Get referenceId (preApprovedReferenceId)
→ Check pre-approval status

6. Loan Application

POST /loans/v1/facilitate/application/{preApprovedReferenceId}
→ Get referenceId (loanApplicationReferenceId)
→ Redirect customer to bankRedirectionUrl

7. Bank Transaction

Customer completes transaction on bank page
→ PaynKolay sends result to callbackUrl

8. Application Tracking

GET /loans/v1/facilitate/query/loan/{loanApplicationReferenceId}
→ Check application status

9. Refund (If Necessary)

POST /loans/v1/facilitate/refund/{loanApplicationReferenceId}
→ Process refund

---

Best Practices

Security

• Store tokens securely
• Use HTTPS (mandatory)
• Encrypt customer information
• Don’t hardcode API keys in source code

Performance

• Cache tokens (until they expire)
• Set appropriate timeout values
• Use retry mechanism for error situations

User Experience

• Show clear error messages
• Inform about transaction status
• Use loading indicators
• Design for mobile compatibility

Data Management

• Save referenceId values
• Regularly check application statuses
• Keep log records
• Configure callback URL properly

---

Previous Steps

• Shopping Loan Overview → - Basic concepts and introduction
• API Integration → - Authentication and preparation steps