API Documentation

Authentication

All API requests must be authenticated using API Key and API Secret headers.

Headers:

Header Name Description
X-API-KEY Your API Key
X-API-SECRET Your API Secret

These credentials are unique to each merchant and must be included in every API request. Requests without valid credentials will receive a 401 Unauthorized response. You can get credentials from Settings page in our dashboard.

Example:

curl -X POST https://api.example.com/api/payment \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: your_api_key_here" \
     -H "X-API-SECRET: your_api_secret_here" \
     -d '{"orderId": "ORD-12345", ...}'

Ensure that your API Key and API Secret are kept secure and not shared publicly.

Payment

Endpoint: POST /api/payment

Description: Process a payment transaction

Request Body:

{
  "orderId": "string",
  "amount": "number",
  "currency": "string",
  "cardHolderName": "string",
  "pan": "string",
  "expiryMonth": "string",
  "expiryYear": "string",
  "cvv": "string",
  "requestIp": "string",
  "requestPort": "number",
  "customerId": "string"
}

Field Descriptions:

Field Description Example
orderId Client's tracking number for the order ORD-12345
amount Transaction amount 100.50
currency Currency code TRY
cardHolderName Name of the card holder John Doe
pan Primary Account Number (card number) 5421190122090656
expiryMonth Card expiry month (2 digits) 04
expiryYear Card expiry year (2 digits) 28
cvv Card Verification Value 916
requestIp IP address of the client making the request 192.168.1.1
requestPort Port number of the client making the request 8080
customerId Optional unique identifier for the customer CUST-12345

Response:

Returns an ApiPaymentResponse object with payment details.

{
  "paymentId": "UUID",
  "orderId": "string",
  "amount": "number",
  "installmentCount": "number",
  "currency": "string",
  "merchantCommission": "number",
  "status": "string",
  "paymentDate": "date",
  "cardHolderName": "string",
  "pan": "string",
  "domInt": "string",
  "cardScheme": "string",
  "cardType": "string",
  "loyaltyCode": "string",
  "externalTransactionId": "string",
  "authCode": "string",
  "resultCode": "string",
  "resultMessage": "string",
  "customerId": "string"
}

Response Field Descriptions:

Field Description Example
paymentId Unique identifier for the payment 123e4567-e89b-12d3-a456-426614174000
orderId Client's tracking number for the order ORD-12345
amount Transaction amount 100.50
installmentCount Number of installments 3
currency Currency code TRY
merchantCommission Commission charged to the merchant 2.50
status Payment status (SUCCESS, FAILED, ENROLLED) SUCCESS
paymentDate Date and time of the payment 2023-05-01T14:30:00Z
cardHolderName Name of the card holder John Doe
pan Masked Primary Account Number 411111******1111
domInt Domestic or International transaction DOM
cardScheme Card scheme (e.g., VISA, MASTERCARD) VISA
cardType Type of card (e.g., CREDIT, DEBIT) CREDIT
loyaltyCode Loyalty program code (if applicable) GOLD123
externalTransactionId Transaction ID from the payment provider EXT123456789
authCode Authorization code from the payment provider AUTH987654
resultCode Result code from the payment provider SUCCESS
resultMessage Result message from the payment provider Successful
customerId Unique identifier for the customer (if provided) CUST-12345

Pre-Authorization

Endpoint: POST /api/pre-authorization

Description: Process a pre-authorization transaction

Request Body:

{
  "orderId": "string",
  "amount": "number",
  "currency": "string",
  "cardHolderName": "string",
  "pan": "string",
  "expiryMonth": "string",
  "expiryYear": "string",
  "cvv": "string",
  "requestIp": "string",
  "requestPort": "number",
  "customerId": "string"
}

Field Descriptions:

Field Description Example
orderId Client's tracking number for the order ORD-12345
amount Transaction amount 100.50
currency Currency code TRY
cardHolderName Name of the card holder John Doe
pan Primary Account Number (card number) 5421190122090656
expiryMonth Card expiry month (2 digits) 04
expiryYear Card expiry year (2 digits) 28
cvv Card Verification Value 916
requestIp IP address of the client making the request 192.168.1.1
requestPort Port number of the client making the request 8080
customerId Optional unique identifier for the customer CUST-12345

Response:

Returns an ApiPaymentResponse object with pre-authorization details (same as Payment response).

Capture Pre-Authorization

Endpoint: POST /api/pre-authorization/{paymentId}/capture

Description: Capture a previously authorized payment

Path Parameters:

Request Body:

{
  "amount": "number",
  "currency": "string"
}

Field Descriptions:

Field Description Example
amount Amount to capture (can be less than or equal to the pre-authorized amount) 90.00
currency Currency code TRY

Response:

Returns an ApiPaymentResponse object with capture details (same as Payment response).

3D Secure Payment

Description: Process a 3D Secure payment

1. Initiate 3D Secure Enrollment

Endpoint: POST /api/3ds

Request Body:

{
  "orderId": "string",
  "amount": "number",
  "currency": "string",
  "installmentCount": "number",
  "interestPaidByCustomer": "boolean",
  "cardHolderName": "string",
  "pan": "string",
  "expiryMonth": "string",
  "expiryYear": "string",
  "cvv": "string",
  "successUrl": "string",
  "failureUrl": "string",
  "requestIp": "string",
  "requestPort": "number",
  "customerId": "string"
}

Field Descriptions:

Field Description Example
orderId Client's tracking number for the order ORD-12345
amount Transaction amount 100.50
currency Currency code TRY
installmentCount Number of installments (optional, default 1). You should check available installment options via Installment Options API before setting this value. 3
interestPaidByCustomer Whether interest is paid by customer (optional) true
cardHolderName Name of the card holder John Doe
pan Primary Account Number (card number) 5421190122090656
expiryMonth Card expiry month (2 digits) 04
expiryYear Card expiry year (2 digits) 28
cvv Card Verification Value 916
successUrl URL to redirect after successful 3D Secure authentication https://example.com/3ds/success
failureUrl URL to redirect after failed 3D Secure authentication https://example.com/3ds/failure
requestIp IP address of the client making the request 192.168.1.1
requestPort Port number of the client making the request 8080
customerId Optional unique identifier for the customer CUST-12345

Response:

{
  "paymentId": "UUID",
  "success": "boolean",
  "resultCode": "string",
  "resultMessage": "string",
  "htmlContent": "string"
}

Response Field Descriptions:

Field Description Example
paymentId Unique identifier for the payment 123e4567-e89b-12d3-a456-426614174000
success Indicates if the enrollment was successful true
resultCode Result code from the 3D Secure enrollment SUCCESS
resultMessage Result message from the 3D Secure enrollment Successful
htmlContent HTML content to be presented to the end user for 3D Secure authentication <form action="https://3ds.example.com" method="POST">...</form>

2. Present 3D Secure Authentication

Present the returned htmlContent to the end user. This typically involves rendering an iframe or redirecting the user to complete the 3D Secure authentication.

3. Handle 3D Secure Callback

After the authentication process, the payment provider will call the provided callback URLs (success or failure) with relevant parameters posted as form data.

Callback Form Data Parameters:

Field Description Example
paymentId Unique identifier for the payment 123e4567-e89b-12d3-a456-426614174000
securityKey Security key received from the 3D Secure authentication process 3DS_AUTH_KEY_123456

4. Complete 3D Secure Payment

Endpoint: POST /api/3ds/{paymentId}/complete

Path Parameters:

Request Body:

{
  "securityKey": "string"
}

Field Descriptions:

Field Description Example
securityKey Security key received from the 3D Secure authentication process 3DS_AUTH_KEY_123456

Response:

Returns an ApiPaymentResponse object with completed 3D Secure payment details (same as Payment response).

3D Secure Payment Flow:

  1. Call the Initiate 3D Secure Enrollment endpoint with the payment details and callback URLs.
  2. Present the returned htmlContent to the end user for 3D Secure authentication.
  3. Wait for the callback to be triggered after the authentication process.
  4. When the callback is received, extract the paymentId and securityKey from the form data.
  5. Call the Complete 3D Secure Payment endpoint with the extracted paymentId and securityKey.
  6. Check the response status. Consider the payment successful only if the status is "SUCCESS".

Installment Options

Endpoint: POST /api/installment-options

Description: Get available installment options for a card

Request Body:

{
  "amount": "number",
  "currency": "string",
  "pan": "string",
  "maxInstallmentCount": "number",
  "interestPaidByCustomer": "boolean"
}

Field Descriptions:

Field Description Example
amount Transaction amount 1000.00
currency Currency code TRY
pan Primary Account Number (card number) 5421190122090656
maxInstallmentCount Maximum number of installments to retrieve (optional) 12
interestPaidByCustomer Whether interest is paid by customer (optional) true

Response:

{
  "options": [
    {
      "installmentCount": 2,
      "installmentAmount": 510.00,
      "currency": "TRY",
      "interestAmount": 20.00,
      "totalAmount": 1020.00
    },
    {
      "installmentCount": 3,
      "installmentAmount": 345.00,
      "currency": "TRY",
      "interestAmount": 35.00,
      "totalAmount": 1035.00
    }
  ]
}

Response Field Descriptions:

Field Description Example
installmentCount Number of installments 3
installmentAmount Amount per installment 345.00
currency Currency code TRY
interestAmount Total interest amount 35.00
totalAmount Total amount to be paid 1035.00

Checkout

Description: Create a checkout link and process payment

1. Create Checkout Link

Endpoint: POST /api/checkout

Request Body:

{
  "orderId": "string",
  "amount": "number",
  "currency": "string",
  "description": "string",
  "callback": "string",
  "customerId": "string",
  "maxInstallmentCount": "number",
  "interestPaidByCustomer": "boolean"
}

Field Descriptions:

Field Description Example
orderId Client's tracking number for the order ORD-12345
amount Transaction amount 100.50
currency Currency code TRY
description Description of the checkout Product purchase
callback URL to be called after payment processing https://example.com/payment-callback
customerId Optional unique identifier for the customer CUST-12345
maxInstallmentCount Maximum number of installments allowed on the checkout page (optional, defaults to 1 — single payment). Installment options will be available based on the card type and merchant configuration. 6
interestPaidByCustomer Whether installment interest is paid by the customer (optional, defaults to false) true

Response:

{
  "checkoutId": "UUID",
  "redirectUrl": "string"
}

Response Field Descriptions:

Field Description Example
checkoutId Unique identifier for the checkout 123e4567-e89b-12d3-a456-426614174000
redirectUrl URL to redirect the user for payment https://api.example.com/checkout-link/123e4567-e89b-12d3-a456-426614174000

2. Redirect User

After receiving the response, redirect the user to the redirectUrl to complete the payment.

3. Callback Processing

After the payment is processed, the callback URL provided in the checkout creation request will be called with the checkoutId as form data.

4. Get Checkout Status

Endpoint: GET /api/checkout/{checkoutId}

Path Parameters:

Response:

Returns an ApiPaymentResponse object with payment details (same as Payment response).

Checkout Flow:

  1. Call the Create Checkout Link endpoint to generate a checkout link.
  2. Redirect the user to the received redirectUrl.
  3. Wait for the callback to be triggered after payment processing.
  4. When the callback is received, extract the checkoutId from the form data.
  5. Call the Get Checkout Status endpoint with the extracted checkoutId.
  6. Check the response status. Consider the payment successful only if the status is "SUCCESS".

Example Implementation:

// Create checkout link
const createCheckout = async (orderDetails) => {
  const response = await fetch('https://api.example.com/api/checkout', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'your_api_key_here',
      'X-API-SECRET': 'your_api_secret_here'
    },
    body: JSON.stringify(orderDetails)
  });
  const data = await response.json();
  return data.redirectUrl;
};

// Callback handler
app.post('/payment-callback', async (req, res) => {
  const checkoutId = req.body.checkoutId;
  const checkoutStatus = await getCheckoutStatus(checkoutId);
  
  if (checkoutStatus.status === 'SUCCESS') {
    // Process successful payment
    console.log('Payment successful');
  } else {
    // Handle failed payment
    console.log('Payment failed');
  }
  
  res.sendStatus(200);
});

// Get checkout status
const getCheckoutStatus = async (checkoutId) => {
  const response = await fetch(`https://api.example.com/api/checkout/${checkoutId}`, {
    method: 'GET',
    headers: {
      'X-API-KEY': 'your_api_key_here',
      'X-API-SECRET': 'your_api_secret_here'
    }
  });
  return await response.json();
};