Edge Pay Integration Guide

Overview

Edge Payment is Kaptio’s hosted payment collection service. It provides a fully branded, PCI-compliant payment page that handles:

• Payment UI — branded page with booking summary, deposit/full payment selection, and payment form
• Payment Processing — Braintree integration (card, PayPal, and optionally Apple Pay / Google Pay where enabled)
• Multi-Currency — guest-selectable display currency with FX conversion
• Insurance — optional travel insurance selection (provider-configurable)
• Webhooks — transaction result notifications to your backend
• Redirect — configurable success/failure/cancel redirect URLs back to your application

What Edge Pay Handles

Edge Pay owns the payment experience from the moment the guest lands on the payment page until the transaction is complete. It:

1. Fetches booking data (pricing, payment schedule, passenger info)
2. Renders a branded payment page with the correct amounts
3. Collects payment via a PCI-compliant hosted form
4. Sends a webhook with the transaction result
5. Redirects the guest back to your application

What the Integrator Handles

Your application is responsible for:

1. Providing booking data via your API (e-commerce) or Salesforce (agent portal)
2. Constructing the redirect URL to Edge Pay with the correct parameters
3. Receiving and processing the webhook callback
4. Displaying success/failure pages after the redirect

---

Two Integration Flows

Edge Pay supports two distinct integration flows, determined by the scenario URL parameter. Choose the flow that matches your application architecture.

E-Commerce Flow (scenario=ecommerce)

For guest-facing checkout applications (web storefronts, booking engines). Booking data is fetched from an E-Commerce API.

How it works:

1. Guest completes booking on your e-commerce site
2. Your site redirects to Edge Pay with bookingId (UUID) and channel (UUID)
3. Edge Pay calls your E-Commerce API to fetch booking details and pricing
4. Guest completes payment on the branded Edge Pay page
5. Edge Pay sends a webhook to your backend with the transaction result
6. Edge Pay redirects the guest back to your site

Required parameters:

Parameter	Type	Description
tenantId	string	Tenant identifier (provided by Kaptio)
scenario	string	Must be ecommerce
bookingId	UUID	Booking identifier from your E-Commerce API
channel	UUID	Channel token for API authentication
currency	string	Pre-selects the display currency (ISO 4217, e.g. CAD, USD). The guest can change the currency on the payment page — this sets the initial default. Pass the currency the guest has been viewing on your site to avoid a price-change feel at handoff.

Optional parameters:

Parameter	Type	Description
brand	string	Brand identifier for multi-brand tenants

Example URL:

https://payment.edge.production.kaptioapis.com/pay/new
  ?tenantId=your-tenant
  &scenario=ecommerce
  &bookingId=550e8400-e29b-41d4-a716-446655440000
  &channel=a1b2c3d4-e5f6-7890-abcd-ef1234567890
  &currency=CAD
  &brand=your-brand

Agent Portal / Salesforce Flow (scenario=payment_link or call_center)

For agent-facing applications where booking data lives in Salesforce. The agent sends a payment link to the customer, or processes payment on behalf of the customer in a call center.

How it works:

1. Agent creates a booking in Salesforce (Kaptio Travel Itinerary__c)
2. Agent or system generates a payment link with the Salesforce itineraryId
3. Customer (or agent) opens the Edge Pay page
4. Edge Pay fetches booking data directly from Salesforce
5. Payment is processed and written back to Salesforce as a Transaction__c

Required parameters:

Parameter	Type	Description
tenantId	string	Tenant identifier (provided by Kaptio)
scenario	string	payment_link or call_center
itineraryId	string	Salesforce Itinerary__c record ID (15 or 18 char)

Optional parameters:

Parameter	Type	Description
sfEnvironment	string	Salesforce environment name
paymentRequestId	string	Pre-selected payment items (call center only)
currency	string	Pre-selects the display currency (ISO 4217). Guest can change it on the payment page.
brand	string	Brand identifier for multi-brand tenants

Example URL:

https://payment.edge.production.kaptioapis.com/pay/new
  ?tenantId=your-tenant
  &scenario=payment_link
  &itineraryId=a0xVc000000AbCdEFG
  &sfEnvironment=production
  &currency=USD

Flow Comparison

Aspect	E-Commerce	Agent Portal / Salesforce
Scenario	ecommerce	payment_link or call_center
Booking ID	UUID (bookingId)	Salesforce ID (itineraryId)
Data Source	E-Commerce API	Salesforce
Auth	channel token (UUID)	Salesforce OAuth (managed by Edge)
Webhook	Yes (to your backend)	No (written directly to Salesforce)
Use Case	Guest checkout	Agent payment links, call center

---

URL Parameters Reference

Complete reference for all /pay/new query parameters.

Parameter	Type	Required	Scenarios	Description
tenantId	string	Always	All	Tenant identifier assigned by Kaptio
scenario	string	Always	All	ecommerce, payment_link, or call_center
bookingId	UUID	E-Commerce	ecommerce	Booking UUID from your E-Commerce API
channel	UUID	E-Commerce	ecommerce	Channel authentication token
itineraryId	string	Salesforce	payment_link, call_center	Salesforce Itinerary__c record ID
currency	string	Recommended	All	Default display currency (ISO 4217)
brand	string	Optional	All	Brand identifier for multi-brand tenants
sfEnvironment	string	Optional	payment_link, call_center	Salesforce environment name
paymentRequestId	string	Optional	call_center	Pre-selected payment items

---

Multi-Brand Support

Edge Pay supports multi-brand tenants where a single tenantId serves multiple brands, each with its own visual identity, default currency, and copy.

How It Works

1. Pass &brand=your-brand-slug as a URL parameter
2. Edge Pay resolves the brand from the tenant configuration
3. Brand-specific overrides are deep-merged onto the base tenant config
4. The payment page renders with the brand’s logo, colors, fonts, and copy

What Brands Can Override

Property	Example
Logo	Brand-specific SVG logo
Colors	Primary, secondary, accent, background, text colors
Fonts	Heading and body font families
Copy	Page title, booking header, success message
Base Currency	Default FX base currency per brand
Redirect Domains	Brand-specific redirect URLs

Brand Resolution

Brand is resolved in priority order:

1. brand URL parameter (highest priority)
2. brand_code field on the payment session
3. Default brand from tenant configuration

If no brand parameter is provided, the tenant’s default brand applies.

---

Redirect URLs

After payment completion (success, failure, or cancellation), Edge Pay redirects the guest back to your application.

Template Variables

Redirect URLs support template variables that Edge Pay replaces at runtime:

Variable	Description	Example Value
{domain}	Your application domain (configured per environment)	https://booking.example.com
{booking_id}	The booking UUID	550e8400-e29b-41d4-a716-446655440000
{confirmation}	Payment confirmation number (populated after successful payment)	KP-2026-001234

Note: {domain} and {booking_id} are replaced when the payment session is created. {confirmation} is replaced only after a successful payment — if you inspect the redirect URL before completing a payment, it will still contain the literal placeholder.

Configuration

Redirect URL templates are configured in the tenant’s Edge Payment blueprint:

scenarios:
  ecommerce:
    redirectUrls:
      success: '{domain}/booking/{booking_id}/success?ref={confirmation}'
      failure: '{domain}/booking/{booking_id}/payment-failed'
      cancel: '{domain}/booking/{booking_id}'
    domains:
      prod: 'https://booking.example.com'
      staging: 'https://staging.booking.example.com'

What You Need to Provide

For each brand and environment, provide the base domain URL. Kaptio will configure the redirect templates. The domain is the root URL of your application where the guest should be sent after payment.

---

Webhook Specification

After a payment is completed, failed, or cancelled, Edge Pay sends an HMAC-signed webhook to your backend.

Endpoint

Edge Pay sends a POST request to the webhook URL configured in the tenant blueprint.

Authentication (HMAC-SHA256)

Every webhook includes an X-Edge-Signature header:

X-Edge-Signature: sha256=<hex-digest>

Where <hex-digest> is:

HMAC-SHA256(raw_request_body, shared_secret)

Verification example (PHP):

$receivedSignature = $request->headers->get('X-Edge-Signature');
$expectedSignature = 'sha256=' . hash_hmac('sha256', $request->getContent(), $sharedSecret);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    return new JsonResponse(['error' => 'Invalid signature'], 403);
}

Verification example (Python):

import hmac, hashlib

expected = 'sha256=' + hmac.new(
    shared_secret.encode(), request.body, hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, request.headers['X-Edge-Signature']):
    return JsonResponse({'error': 'Invalid signature'}, status=403)

The shared secret is provisioned out-of-band. Different secrets are used per environment.

Headers

Header	Value	Description
Content-Type	application/json	Always JSON
X-Edge-Signature	sha256=<hex>	HMAC-SHA256 of raw body
X-Idempotency-Key	{sessionId}-{transactionId}	For idempotent processing
User-Agent	Edge-Payment/1.0	Identifies Edge

Payload: Successful Payment

{
  "event": "payment.completed",
  "bookingId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-02-11T14:30:00.000Z",

  "transaction": {
    "id": "txn_abc123",
    "status": "success",
    "amount": 250000,
    "currency": "CAD",
    "paymentMethod": "braintree_card",
    "confirmationNumber": "KP-2026-001234",
    "cardLast4": "4242",
    "cardBrand": "visa",
    "processedAt": "2026-02-11T14:29:55.000Z"
  },

  "insurance": {
    "selected": true,
    "provider": "allianz",
    "planName": "Travel Protection Plan",
    "premium": 15000,
    "currency": "CAD"
  },

  "fx": {
    "paymentCurrency": "USD",
    "bookingCurrency": "CAD",
    "rate": 1.35,
    "convertedAmount": 185185
  },

  "tc": {
    "accepted": true,
    "timestamp": "2026-02-11T14:28:00.000Z",
    "version": "1.0"
  }
}

Payload: Failed Payment

{
  "event": "payment.failed",
  "bookingId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-02-11T14:30:00.000Z",

  "transaction": {
    "id": "txn_abc124",
    "status": "failed",
    "amount": 250000,
    "currency": "CAD",
    "paymentMethod": "braintree_card",
    "processedAt": "2026-02-11T14:29:55.000Z"
  }
}

Payload: Cancelled Payment

{
  "event": "payment.cancelled",
  "bookingId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-02-11T14:30:00.000Z",

  "transaction": {
    "id": "txn_abc125",
    "status": "cancelled",
    "amount": 250000,
    "currency": "CAD",
    "paymentMethod": "braintree_card",
    "processedAt": "2026-02-11T14:29:55.000Z"
  }
}

Field Reference

Top-Level Fields:

Field	Type	Always Present	Description
event	string	Yes	payment.completed, payment.failed, or payment.cancelled
bookingId	string (UUID)	Yes	The booking UUID passed in the original redirect
sessionId	string (UUID)	Yes	Edge session identifier
timestamp	string (ISO-8601)	Yes	When the webhook was generated

Transaction Object (always present):

Field	Type	Always Present	Description
id	string	Yes	Transaction identifier
status	string	Yes	success, failed, or cancelled
amount	integer	Yes	Amount in cents (250000 = $2,500.00)
currency	string	Yes	ISO 4217 currency code
paymentMethod	string	Yes	e.g. braintree_card, braintree_paypal
confirmationNumber	string	Success only	Kaptio Pay confirmation number
cardLast4	string	Card only	Last 4 digits of card
cardBrand	string	Card only	visa, mastercard, amex
processedAt	string (ISO-8601)	Yes	When the payment was processed

Insurance Object (optional, present when guest interacted with insurance):

Field	Type	Description
selected	boolean	Whether the guest selected insurance
provider	string	Insurance provider
planName	string	Plan name selected
premium	integer	Premium amount in cents
currency	string	Currency of the premium

FX Object (optional, present when guest paid in a different currency):

Field	Type	Description
paymentCurrency	string	Currency the guest paid in
bookingCurrency	string	Original booking currency
rate	number	Exchange rate applied
convertedAmount	integer	Amount in payment currency, in cents

T&C Object (optional, present when guest accepted terms):

Field	Type	Description
accepted	boolean	Whether T&C were accepted
timestamp	string (ISO-8601)	When acceptance occurred
version	string	T&C version identifier

Retry Policy

Attempt	Delay	Timeout
1 (inline)	Immediate	5 seconds
2 (retry)	5 seconds after failure	10 seconds
3 (retry)	30 seconds after attempt 2	10 seconds
4 (retry)	120 seconds after attempt 3	10 seconds

After all attempts are exhausted, the webhook is marked as permanently failed. The payload is stored on the Edge session and can be manually retriggered.

Expected Response

• 200 OK or 201 Created: Webhook processed successfully
• 4xx: Client error (Edge will NOT retry)
• 5xx: Server error (Edge WILL retry)

Idempotency

Each webhook includes an X-Idempotency-Key header ({sessionId}-{transactionId}). Store this key after processing and reject duplicates to prevent double-applying a payment.

---

Deposit vs Full Payment

Edge Pay supports both deposit and full payment options. How the amounts are determined depends on the integration flow.

E-Commerce Flow

Your E-Commerce API provides a payment_schedule array in the /prices/ response. Each entry has:

• name — e.g. “Deposit”, “Balance”
• amount — amount in cents
• due_date — when the payment is due

Edge Pay reads the payment schedule and presents the guest with deposit and full payment options based on the schedule entries and their due dates.

Salesforce Flow

Payment amounts are read from Salesforce PaymentSchedule__c records linked to the Itinerary__c. The deposit and balance amounts, along with due dates, are calculated from these records.

Guest Experience

On the payment page, the guest sees:

• Pay Deposit — the minimum amount due today
• Pay in Full — the total trip amount

The guest selects their preferred option. If paying a deposit, the remaining balance and due date are displayed.

---

Environment URLs

Environment	Base URL
Staging	https://payment.edge.staging.kaptioapis.com
Production	https://payment.edge.production.kaptioapis.com

All URLs follow the pattern: {base}/pay/new?{parameters}

---

Supported Currencies

Edge Pay supports the following display currencies:

CAD, USD, GBP, EUR, AUD, NZD

The currency URL parameter sets the default display currency. The guest can change the display currency on the payment page. FX conversion rates are applied at the time of payment.

The base currency (the currency the booking is priced in) is configured per tenant or per brand. FX conversion shows both the original amount and the converted amount.