# 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

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Order ID for which to calculate installments |
| `binNumber` | string | Yes | First 6 digits of the credit card number |


### Example Request


```bash
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):**


```json
{
  "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

| Field | Type | Description |
|  --- | --- | --- |
| `bankCode` | integer | Bank identifier code |
| `bankName` | string | Bank name |
| `binNumber` | string | BIN number used for the query |
| `cardAssociation` | string | Card network (Visa, MasterCard, etc.) |
| `cardFamily` | string | Card family (Classic, Gold, Platinum, etc.) |
| `cardType` | string | Card type (credit, debit) |
| `shouldForceTo3D` | boolean | Whether 3D Secure is mandatory for this card |
| `supportedCurrencies` | array | Currencies supported by the card |
| `installmentPrices` | array | Available installment options |
| `installmentPrices[].number` | integer | Number of installments |
| `installmentPrices[].price` | object | Monthly payment amount |
| `installmentPrices[].totalPrice` | object | Total 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

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Order ID to process payment for |
| `paymentType` | string | Yes | Payment method: `creditCard` or `limit` |
| `payWithCard` | object | Conditional | Credit card details (required if paymentType is creditCard) |


#### Credit Card Payment (`payWithCard`)

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `cardNumber` | string | Yes | Credit card number (PCI compliant handling) |
| `expireMonth` | string | Yes | Card expiration month (01-12) |
| `expireYear` | string | Yes | Card expiration year (YYYY) |
| `cardHolderName` | string | Yes | Name as it appears on the card |
| `cvc` | string | Yes | 3-digit security code |
| `installment` | integer | Yes | Number of installments (1 for single payment) |
| `isWith3DSecure` | boolean | Yes | Whether to use 3D Secure authentication |
| `callbackUrl` | string | Yes | URL for 3D Secure completion callback |


### Example Requests

#### Credit Card Payment


```bash
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


```bash
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)


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

#### 3D Secure Required (200 OK)


```json
{
  "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)


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

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `status` | string | Payment status (success, redirect_required, failed) |
| `is3dsSecure` | boolean | Whether the payment requires 3D Secure authentication |
| `threeDSHtmlContent` | string | HTML 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

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Order ID for the payment being processed |


### Request Body (Form Data)

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `language` | string | Yes | Language code for response |
| `paymentId` | string | Yes | Payment transaction ID |
| `transactionId` | string | Yes | Bank transaction ID |


### Example Request


```bash
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.


```html
<!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


```mermaid
graph TD
    A[Create Order] --> B[Get Installment Info]
    B --> C[Submit Payment]
    C --> D{3D Secure Required?}
    D -->|No| E[Payment Success]
    D -->|Yes| F[Redirect to Bank]
    F --> G[Customer Authentication]
    G --> H[3D Secure Callback]
    H --> I{Authentication Success?}
    I -->|Yes| E
    I -->|No| J[Payment Failed]
    E --> K[Order Completed]
    J --> L[Retry Payment]
    L --> C
```

### Credit Limit Payment Flow


```mermaid
graph TD
    A[Create Order] --> B[Check Credit Limit]
    B --> C{Sufficient Credit?}
    C -->|Yes| D[Process Payment]
    C -->|No| E[Insufficient Credit]
    D --> F[Payment Success]
    F --> G[Update Credit Balance]
    G --> H[Order Completed]
    E --> I[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


```json
{
  "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

| Code | Description | Action |
|  --- | --- | --- |
| 2001 | Card declined | Try different card or payment method |
| 2002 | Insufficient funds | Check card balance or use different card |
| 2003 | Expired card | Update card expiration date |
| 2004 | Invalid card number | Verify card number is correct |
| 2005 | Invalid CVC | Check security code |
| 2006 | 3D Secure failed | Retry with correct authentication |
| 2007 | Credit limit exceeded | Use alternative payment method |
| 2008 | Payment timeout | Retry the payment |


## Integration Examples

### Complete Payment Flow


```javascript
// 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


```javascript
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.