Skip to content
/
Payment
Last updated

Payment Operations

Payment endpoints handle the complete payment processing workflow for car rental orders. The system supports multiple payment methods including credit card payments with 3D Secure authentication and credit limit payments for approved agencies.

Get Installment Information

Retrieve available installment options for credit card payments based on the card's BIN number and order amount. This endpoint helps customers understand payment options before completing their purchase.

Endpoint

POST /payment/installment-info

Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body

FieldTypeRequiredDescription
orderIDstringYesOrder ID for which to calculate installments
binNumberstringYesFirst 6 digits of the credit card number

Example Request

curl -X POST https://api.pro.yolcu360.com/api/v1/payment/installment-info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "orderID": "order_123456789",
    "binNumber": "543210"
  }'

Response

Success Response (200 OK):

{
  "bankCode": 12,
  "bankName": "Example Bank",
  "binNumber": "543210",
  "cardAssociation": "MasterCard",
  "cardFamily": "World",
  "cardType": "credit",
  "shouldForceTo3D": true,
  "supportedCurrencies": [
    "TRY",
    "USD",
    "EUR"
  ],
  "installmentPrices": [
    {
      "number": 1,
      "price": {
        "amount": 54500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 54500,
        "currency": "TRY"
      }
    },
    {
      "number": 3,
      "price": {
        "amount": 18500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 55500,
        "currency": "TRY"
      }
    },
    {
      "number": 6,
      "price": {
        "amount": 9500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 57000,
        "currency": "TRY"
      }
    },
    {
      "number": 12,
      "price": {
        "amount": 5000,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 60000,
        "currency": "TRY"
      }
    }
  ]
}

Response Fields

FieldTypeDescription
bankCodeintegerBank identifier code
bankNamestringBank name
binNumberstringBIN number used for the query
cardAssociationstringCard network (Visa, MasterCard, etc.)
cardFamilystringCard family (Classic, Gold, Platinum, etc.)
cardTypestringCard type (credit, debit)
shouldForceTo3DbooleanWhether 3D Secure is mandatory for this card
supportedCurrenciesarrayCurrencies supported by the card
installmentPricesarrayAvailable installment options
installmentPrices[].numberintegerNumber of installments
installmentPrices[].priceobjectMonthly payment amount
installmentPrices[].totalPriceobjectTotal amount with interest

Process Payment

Process payment for an order using either credit card or credit limit. This endpoint handles both 2D and 3D Secure credit card payments, as well as credit limit payments for approved agencies.

Endpoint

POST /payment/pay

Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

Request Body

FieldTypeRequiredDescription
orderIDstringYesOrder ID to process payment for
paymentTypestringYesPayment method: creditCard or limit
payWithCardobjectConditionalCredit card details (required if paymentType is creditCard)

Credit Card Payment (payWithCard)

FieldTypeRequiredDescription
cardNumberstringYesCredit card number (PCI compliant handling)
expireMonthstringYesCard expiration month (01-12)
expireYearstringYesCard expiration year (YYYY)
cardHolderNamestringYesName as it appears on the card
cvcstringYes3-digit security code
installmentintegerYesNumber of installments (1 for single payment)
isWith3DSecurebooleanYesWhether to use 3D Secure authentication
callbackUrlstringYesURL for 3D Secure completion callback

Example Requests

Credit Card Payment

curl -X POST https://api.pro.yolcu360.com/api/v1/payment/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "orderID": "order_123456789",
    "paymentType": "creditCard",
    "payWithCard": {
      "cardNumber": "4242424242424242",
      "expireMonth": "12",
      "expireYear": "2025",
      "cardHolderName": "John Doe",
      "cvc": "123",
      "installment": 3,
      "isWith3DSecure": true,
      "callbackUrl": "https://yoursite.com/payment/callback"
    }
  }'

Credit Limit Payment

curl -X POST https://api.pro.yolcu360.com/api/v1/payment/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "orderID": "order_123456789",
    "paymentType": "limit"
  }'

Response

2D Payment Success (200 OK)

{
  "status": "success",
  "is3dsSecure": false,
  "threeDSHtmlContent": null
}

3D Secure Required (200 OK)

{
  "status": "redirect_required",
  "is3dsSecure": true,
  "threeDSHtmlContent": "<!DOCTYPE html><html><head><title>3D Secure</title></head><body><form id='threeDSForm' action='https://3ds.bank.com/auth' method='POST'>...</form><script>document.getElementById('threeDSForm').submit();</script></body></html>"
}

Credit Limit Payment Success (200 OK)

{
  "status": "success",
  "is3dsSecure": false,
  "threeDSHtmlContent": null
}

Response Fields

FieldTypeDescription
statusstringPayment status (success, redirect_required, failed)
is3dsSecurebooleanWhether the payment requires 3D Secure authentication
threeDSHtmlContentstringHTML content for 3D Secure redirect (if required)

3D Secure Callback

Handle 3D Secure authentication callback after the customer completes authentication with their bank. This endpoint is called automatically by the payment processor.

Endpoint

POST /payment/3ds-callback/{orderID}

Path Parameters

ParameterTypeRequiredDescription
orderIDstringYesOrder ID for the payment being processed

Request Body (Form Data)

FieldTypeRequiredDescription
languagestringYesLanguage code for response
paymentIdstringYesPayment transaction ID
transactionIdstringYesBank transaction ID

Example Request

curl -X POST https://api.pro.yolcu360.com/api/v1/payment/3ds-callback/order_123456789 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'language=en&paymentId=payment_123456&transactionId=txn_789012'

Response

Success Response (200 OK):

Returns HTML content that redirects the user back to your application with the payment result.

<!DOCTYPE html>
<html>
<head>
    <title>Payment Complete</title>
</head>
<body>
<script>
    window.location.href = 'https://yoursite.com/payment/success?orderID=order_123456789&status=success';
</script>
</body>
</html>

Payment Methods

Credit Card Payments

Supported Features

  • Card Types: Visa, MasterCard, American Express
  • 3D Secure: Optional or mandatory based on card and amount
  • Installments: Multiple installment options based on card type
  • Currencies: TRY, USD, EUR (depending on card support)

3D Secure Flow

  1. Customer submits payment with 3D Secure enabled
  2. API returns HTML content for bank authentication
  3. Customer completes authentication on bank's website
  4. Bank redirects to the 3D Secure callback endpoint
  5. Payment is finalized and customer is redirected to success page

Security Features

  • PCI Compliance: All card data is handled securely
  • Tokenization: Card numbers are never stored in plain text
  • SSL/TLS: All communications are encrypted
  • Fraud Detection: Built-in fraud protection mechanisms

Credit Limit Payments

Eligibility

  • Available for agencies with approved credit limits
  • Requires active credit agreement
  • Subject to available credit balance

Processing

  • Immediate payment processing
  • No additional authentication required
  • Automatic credit limit adjustment
  • Billing occurs according to credit terms

Payment Best Practices

Credit Card Processing

  • BIN Validation: Always check installment options before payment
  • 3D Secure: Use 3D Secure for enhanced security
  • Error Handling: Implement robust error handling for payment failures
  • Timeout Management: Handle payment timeouts gracefully

Security Considerations

  • PCI Compliance: Ensure your integration meets PCI DSS requirements
  • Data Protection: Never log or store sensitive card information
  • HTTPS Only: Always use HTTPS for payment communications
  • Token Management: Securely handle payment tokens and callbacks

User Experience

  • Progress Indicators: Show clear payment progress to users
  • Error Messages: Provide helpful error messages for failed payments
  • Retry Logic: Allow users to retry failed payments
  • Confirmation: Always show payment confirmation to users

Payment Workflow

Credit Card Payment Flow

No
Yes
Yes
No
Create Order
Get Installment Info
Submit Payment
3D Secure Required?
Payment Success
Redirect to Bank
Customer Authentication
3D Secure Callback
Authentication Success?
Payment Failed
Order Completed
Retry Payment

Credit Limit Payment Flow

Yes
No
Create Order
Check Credit Limit
Sufficient Credit?
Process Payment
Insufficient Credit
Payment Success
Update Credit Balance
Order Completed
Use Alternative Payment

Error Handling

Common Error Responses

  • 400 Bad Request: Invalid payment data or missing required fields
  • 401 Unauthorized: Authentication required or token expired
  • 402 Payment Required: Insufficient credit limit or card declined
  • 404 Not Found: Order not found or payment already processed
  • 422 Unprocessable Entity: Payment validation errors
  • 500 Internal Server Error: Payment processor error

Example Error Response

{
  "code": 2001,
  "description": "Credit card declined",
  "details": {
    "field": "cardNumber",
    "message": "The card was declined by the bank",
    "bankCode": "05",
    "bankMessage": "Do not honor"
  }
}

Payment Error Codes

CodeDescriptionAction
2001Card declinedTry different card or payment method
2002Insufficient fundsCheck card balance or use different card
2003Expired cardUpdate card expiration date
2004Invalid card numberVerify card number is correct
2005Invalid CVCCheck security code
20063D Secure failedRetry with correct authentication
2007Credit limit exceededUse alternative payment method
2008Payment timeoutRetry the payment

Integration Examples

Complete Payment Flow

// Step 1: Get installment options
async function getInstallmentOptions(orderID, cardNumber) {
    const binNumber = cardNumber.substring(0, 6);

    const response = await fetch('/api/v1/payment/installment-info', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({
            orderID: orderID,
            binNumber: binNumber
        })
    });

    return await response.json();
}

// Step 2: Process payment
async function processPayment(orderID, cardDetails, installmentOption) {
    const paymentData = {
        orderID: orderID,
        paymentType: 'creditCard',
        payWithCard: {
            cardNumber: cardDetails.number,
            expireMonth: cardDetails.expireMonth,
            expireYear: cardDetails.expireYear,
            cardHolderName: cardDetails.holderName,
            cvc: cardDetails.cvc,
            installment: installmentOption.number,
            isWith3DSecure: true,
            callbackUrl: `${window.location.origin}/payment/callback`
        }
    };

    const response = await fetch('/api/v1/payment/pay', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify(paymentData)
    });

    const result = await response.json();

    if (result.is3dsSecure) {
        // Handle 3D Secure redirect
        document.body.innerHTML = result.threeDSHtmlContent;
    } else {
        // Payment completed without 3D Secure
        handlePaymentSuccess(result);
    }
}

// Step 3: Handle 3D Secure callback
function handle3DSCallback() {
    const urlParams = new URLSearchParams(window.location.search);
    const orderID = urlParams.get('orderID');
    const status = urlParams.get('status');

    if (status === 'success') {
        handlePaymentSuccess();
    } else {
        handlePaymentFailure();
    }
}

Credit Limit Payment

async function processCreditLimitPayment(orderID) {
    const response = await fetch('/api/v1/payment/pay', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({
            orderID: orderID,
            paymentType: 'limit'
        })
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Payment failed: ${error.description}`);
    }

    return await response.json();
}

Rate Limiting

Payment endpoints are subject to rate limiting:

  • Installment info: Maximum 30 requests per minute per user
  • Process payment: Maximum 10 requests per minute per user
  • 3D Secure callback: Maximum 100 requests per minute per order

Implement appropriate retry logic and monitor rate limit headers in responses.

Previous page
Next page