Booking Flow with Payment Proxy

This document explains how to integrate the Payment Proxy into your booking workflow when using the NewSkies API.

Overview

The Payment Proxy is designed to handle payment operations separately from the main booking flow. This separation ensures PCI-DSS compliance by isolating payment processing through a dedicated, secure proxy.

Booking Flow Diagram

Visual Flow Summary

┌─────────────────────────────────────────────────────────────────┐
│  Client Application                                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌───────────────────────────────────────┐
        │  PHASE 1: Create Booking              │
        │  ────────────────────────              │
        │  • Availability Search                │
        │  • Sell Flights                       │
        │  • Add Passengers                     │
        │  • Add SSRs                           │
        │                                       │
        │  Proxy: SoapApi/DigitalApi           │
        └───────────────────────────────────────┘
                              │
                              ▼
        ┌───────────────────────────────────────┐
        │  PHASE 2: Payment Processing          │
        │  ────────────────────────              │
        │  • Add Payment                        │
        │                                       │
        │  Proxy: Payment Proxy ⚠️              │
        │  (PCI-DSS Compliant)                  │
        └───────────────────────────────────────┘
                              │
                              ▼
        ┌───────────────────────────────────────┐
        │  PHASE 3: Finalize Booking            │
        │  ────────────────────────              │
        │  • Commit Booking                     │
        │  • Follow-up Actions                  │
        │                                       │
        │  Proxy: SoapApi/DigitalApi           │
        └───────────────────────────────────────┘
                              │
                              ▼
        ┌───────────────────────────────────────┐
        │  Booking Complete                     │
        │  PNR Generated                        │
        └───────────────────────────────────────┘

Detailed Steps (Example, not a full working workflow)

Phase 1: Create Booking (Use SoapApi or DigitalApi Proxy)

1. Availability Search

   • Endpoint: GET /api/nsk/v1/availability/search
   • Search for available flights based on origin, destination, and dates

2. Sell (Select Flights)

   • Endpoint: POST /api/nsk/v1/booking/sell
   • Create a booking by selecting flights from availability results
   • This creates a booking "in state" (session-based, not yet committed)

3. Add Passengers

   • Endpoint: POST /api/nsk/v1/booking/passengers
   • Add passenger details (names, contact information, etc.)

4. Add SSRs (Special Service Requests)

   • Endpoint: POST /api/nsk/v1/booking/ssrs
   • Add ancillary services like:
     • Baggage
     • Seat selections
     • Meals
     • Other special services

Phase 2: Payment Processing (Switch to Payment Proxy)

Important: At this point, switch from the booking proxy URL to the Payment Proxy URL.

5. Add Payment

   For Digital API (REST):

   • Endpoint: POST /flight/newskies/payment/rest/api/nsk/v5/booking/payments
   • Provide payment details (credit card, voucher, etc.)
   • The proxy automatically strips /rest and routes to the secure payment backend

   For SOAP API:

   • Endpoint: POST /flight/newskies/payment/soap
   • Include SOAPAction header
   • Send SOAP envelope with payment details

   Example Request (Digital API):

   {
     "amount": 250.00,
     "currencyCode": "USD",
     "paymentFields": {
       "ACCTNO": "4111111111111111",
       "EXPDATE": "12/2025",
       "CC::AccountHolderName": "John Doe",
       "CC::VerificationCode": "123"
     }
   }

Phase 3: Finalize Booking (Switch Back to SoapApi or DigitalApi Proxy)

Important: After payment is processed, switch back to the original booking proxy URL.

6. Commit Booking

   • Endpoint: POST /api/nsk/v1/booking/commit
   • Commits the booking to the database
   • Generates PNR (Passenger Name Record)
   • Booking is no longer "in state" and becomes permanent

7. Follow-up Actions (Optional)

   • Send confirmation emails
   • Generate booking documents
   • Trigger post-booking workflows
   • Retrieve booking details for display

Key Points

Session Management

• The booking remains "in state" (session-based) throughout the process
• The same session token must be used across all three phases
• Session token is typically passed via Authorization headers (DigitalApi) or xml-requests (SoapApi)

Proxy Switching

• Phase 1 & 3: Use SoapApi or DigitalApi Proxy URL
• Phase 2: Use Payment Proxy URL (/flight/newskies/payment)
• The session token ensures continuity across proxy switches

Security & PCI-DSS Compliance

• Payment data only flows through the PCI-DSS compliant Payment Proxy
• The booking proxy never handles sensitive payment information
• This separation ensures compliance with payment card industry standards

Error Handling

• If payment fails, the booking remains "in state"
• You can retry payment or modify the booking
• Only commit the booking after successful payment
• Uncommitted bookings may expire based on session timeout

Best Practices

1. Always validate payment success before committing the booking
2. Maintain session continuity across proxy switches
3. Never log sensitive payment data (card numbers, CVV, etc.)

Troubleshooting

Common Issues

Issue: Session lost when switching proxies

• Solution: Ensure session token is properly passed in headers across all requests

Issue: 404 errors on payment endpoint

• Solution: Verify you're using the correct Payment Proxy URL and path format

Support

For technical support or questions about the payment integration flow, please contact the API Support Team.