CyberSource OAuth Payment API Integration Guide ​

This documentation provides a complete guide for integrating with CyberSource payment processing through TTC's Payment Gateway OAuth service.

Overview ​

The CyberSource OAuth Payment API Integration Guide allows merchants to:

• Obtain secure access tokens for CyberSource API authentication
• Process payments using mutual TLS (mTLS) authentication
• Handle payment authorization and capture operations

The integration follows a two-step process:

1. Get Access Token: Request an OAuth access token from TTC's Payment Gateway
2. Submit Payment: Use the token together with the mTLS certificates (provided to you separately by TTC Payments) to process payments with CyberSource

Step 1: Request Access Token ​

Overview ​

This endpoint retrieves a CyberSource OAuth access token for secure communication with CyberSource APIs. The mTLS certificates required for CyberSource API calls are provided separately by TTC Payments through a secure channel and are not part of this response.

Endpoints ​

Test Environment

POST https://paymentgateway.uat.travcorpservices.com/cybersource/token/{integratorName}

Production Environment

POST https://paymentgateway.travcorpservices.com/cybersource/token/{integratorName}

Path Parameters ​

Important Notes about integratorName:

• This value is case-sensitive and must match exactly what was configured during onboarding
• Each integrator has their own isolated OAuth configuration and refresh tokens
• Contact TTC Payments if you're unsure of your assigned integrator name
• Examples: costco

Authentication ​

• Required Header: x-api-key - Your API key provided by TTC Payments

Request ​

Headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY

Body:

{
  "merchantId": "ttc_ttusas_m"
}

Response ​

Success Response (200):

{
  "message": "Access token retrieved successfully",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899,
  "merchant_id": "ttc_ttusas_m"
}

Response Fields:

• access_token: Bearer token for CyberSource API authentication
• token_type: Always "Bearer"
• expires_in: Token validity period in seconds
• merchant_id: Merchant identifier associated with the token

Error Handling ​

Notes ​

• Access tokens are valid for approximately 15 minutes (899 seconds)
• If CyberSource rotates the refresh token, it's automatically updated in our system
• The mTLS certificates are required for all CyberSource API calls and are provided separately by TTC Payments through a secure channel

Step 2: Submit Payment to CyberSource ​

Overview ​

Once you have obtained the access token (Step 1) and have the mTLS certificates provided by TTC Payments, you can submit payments directly to CyberSource using their Payments API.

Endpoints ​

TEST Environment

POST https://api-matest.cybersource.com/pts/v2/payments

Production Environment

POST https://api-ma.cybersource.com/pts/v2/payments

Authentication ​

This endpoint requires mutual TLS (mTLS) authentication using the certificates provided separately by TTC Payments through a secure channel.

Request ​

Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Body Example:

{
  "clientReferenceInformation": {
    "code": "TTUSAS_123456", // Your unique transaction reference example: TTUSAS_123456
    "partner": {
      "solutionId": "ttctestpartner" // production solutionId TBC
    }
  },
  "processingInformation": {
    "capture": true,
    "actionList": [
      "TOKEN_CREATE"
    ]
  },
  "paymentInformation": {
    "card": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "102.21",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1 Market St",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@cybs.com",
      "phoneNumber": "4158880000"
    }
  }
}

Required Request Fields:

• clientReferenceInformation.code: Your unique transaction reference
• processingInformation.capture: Set to true to automatically capture (settle) the payment immediately after authorisation in a single request. Set to false to authorise only, which reserves the funds without settling — a separate capture request must then be made
• processingInformation.actionList: List of additional actions to perform. Use TOKEN_CREATE to instruct CyberSource to tokenise the card during the payment transaction, returning a network token in the response
• paymentInformation.card: Card details for payment
• orderInformation.amountDetails: Transaction amount and currency
• orderInformation.billTo: Billing information

Response ​

Success Response (201):

{
    "_links": {
        "authReversal": {
            "method": "POST",
            "href": "/pts/v2/payments/7515647504736821004807/reversals"
        },
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/7515647504736821004807"
        },
        "capture": {
            "method": "POST",
            "href": "/pts/v2/payments/7515647504736821004807/captures"
        }
    },
    "clientReferenceInformation": {
        "code": "TTUSAS_123456"
    },
    "id": "7515647504736821004807",
    "orderInformation": {
        "amountDetails": {
            "authorizedAmount": "102.21",
            "currency": "USD"
        }
    },
    "paymentAccountInformation": {
        "card": {
            "type": "001"
        }
    },
    "paymentInformation": {
        "tokenizedCard": {
            "type": "001"
        },
        "card": {
            "type": "001"
        }
    },
    "pointOfSaleInformation": {
        "terminalId": "12345678"
    },
    "processorInformation": {
        "merchantNumber": "12345678",
        "approvalCode": "102",
        "cardReferenceData": "12345678901234567890123456789012345678901234567890123456",
        "networkTransactionId": "123456789012345",
        "transactionId": "123456789012345",
        "responseCode": "0",
        "avs": {
            "code": "U",
            "codeRaw": "00"
        }
    },
    "status": "AUTHORIZED",
    "submitTimeUtc": "2025-07-03T17:45:50Z"
}

Important Response Fields:

• id: CyberSource payment ID for future operations
• status: Payment status (AUTHORIZED, DECLINED, etc.)
• processorInformation.approvalCode: Authorization code
• processorInformation.responseCode: Response code (0 = approved)
• _links: Available follow-up operations (capture, reversal, etc.)

mTLS Certificate Setup ​

To use the mTLS certificates provided by TTC Payments:

1. Securely store the certificate and key files delivered to you by TTC Payments (e.g. client.crt and client.key)
2. Configure your HTTP client to use client certificate authentication
3. Use the certificates for all CyberSource API calls

Example using curl:

# Reference the certificate and key files provided by TTC Payments
# (client.crt and client.key)

# Make payment request
curl -X POST \
  --cert client.crt \
  --key client.key \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Type: application/json" \
  -d '{"clientReferenceInformation":{"code":"TC50171_3"},...}' \
  https://api-matest.cybersource.com/pts/v2/payments

Step 2.1: Code Examples by Programming Language ​

Use the following examples to submit a payment with mTLS (Step 2) once you have the access token from Step 1 and the certificates provided by TTC Payments.

# Reference the certificate and key files provided by TTC Payments
# (client.crt and client.key)

# Submit payment with mTLS
curl -X POST \
  --cert client.crt \
  --key client.key \
  -H "Authorization: Bearer $access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientReferenceInformation": {
      "code": "TTUSAS_123456",
      "partner": {
        "solutionId": "ttctestpartner"
      }
    },
    "processingInformation": {
      "capture": true,
      "actionList": [
        "TOKEN_CREATE"
      ]
    },
    "paymentInformation": {
      "card": {
        "number": "4111111111111111",
        "expirationMonth": "12",
        "expirationYear": "2031"
      }
    },
    "orderInformation": {
      "amountDetails": {
        "totalAmount": "102.21",
        "currency": "USD"
      },
      "billTo": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "1 Market St",
        "locality": "san francisco",
        "administrativeArea": "CA",
        "postalCode": "94105",
        "country": "US",
        "email": "test@cybs.com",
        "phoneNumber": "4158880000"
      }
    }
  }' \
  https://api-matest.cybersource.com/pts/v2/payments

import requests

# Paths to the certificate and key files provided by TTC Payments
cert_path = '/path/to/client.crt'
key_path = '/path/to/client.key'

if True:
    # Payment data
    payment_data = {
        "clientReferenceInformation": {
            "code": "TTUSAS_123456",
            "partner": {
                "solutionId": "ttctestpartner"
            }
        },
        "processingInformation": {
            "capture": true,
            "actionList": [
                "TOKEN_CREATE"
            ]
        },
        "paymentInformation": {
            "card": {
                "number": "4111111111111111",
                "expirationMonth": "12",
                "expirationYear": "2031"
            }
        },
        "orderInformation": {
            "amountDetails": {
                "totalAmount": "102.21",
                "currency": "USD"
            },
            "billTo": {
                "firstName": "John",
                "lastName": "Doe",
                "address1": "1 Market St",
                "locality": "san francisco",
                "administrativeArea": "CA",
                "postalCode": "94105",
                "country": "US",
                "email": "test@cybs.com",
                "phoneNumber": "4158880000"
            }
        }
    }

    # Submit payment
    response = requests.post(
        'https://api-matest.cybersource.com/pts/v2/payments',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json'
        },
        cert=(cert_path, key_path),
        json=payment_data
    )
    
    payment_result = response.json()

const https = require('https');
const fs = require('fs');
const axios = require('axios');

// Paths to the certificate and key files provided by TTC Payments
const certPath = '/path/to/client.crt';
const keyPath = '/path/to/client.key';

if (true) {
    // Create HTTPS agent with client certificates
    const agent = new https.Agent({
        cert: fs.readFileSync(certPath),
        key: fs.readFileSync(keyPath)
    });

    const paymentData = {
        clientReferenceInformation: {
            code: "TTUSAS_123456",
            partner: {
                solutionId: "ttctestpartner"
            }
        },
        processingInformation: {
            capture: true,
            actionList: [
                "TOKEN_CREATE"
            ]
        },
        paymentInformation: {
            card: {
                number: "4111111111111111",
                expirationMonth: "12",
                expirationYear: "2031"
            }
        },
        orderInformation: {
            amountDetails: {
                totalAmount: "102.21",
                currency: "USD"
            },
            billTo: {
                firstName: "John",
                lastName: "Doe",
                address1: "1 Market St",
                locality: "san francisco",
                administrativeArea: "CA",
                postalCode: "94105",
                country: "US",
                email: "test@cybs.com",
                phoneNumber: "4158880000"
            }
        }
    };

    const response = await axios.post(
        'https://api-matest.cybersource.com/pts/v2/payments',
        paymentData,
        {
            headers: {
                'Authorization': `Bearer ${accessToken}`,
                'Content-Type': 'application/json'
            },
            httpsAgent: agent
        }
    );

    const paymentResult = response.data;
}

// Using OkHttp with SSL context
import javax.net.ssl.*;
import java.security.KeyStore;

// Setup SSL context with client certificates
KeyStore keyStore = KeyStore.getInstance("PKCS12");
// Note: Convert PEM certificates to PKCS12 format first
// ... load certificates into keyStore ...

SSLContext sslContext = SSLContexts.custom()
    .loadKeyMaterial(keyStore, "password".toCharArray())
    .build();

OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(sslContext.getSocketFactory())
    .build();

String paymentJson = "{"
    + "\"clientReferenceInformation\": {"
    + "  \"code\": \"TTUSAS_123456\","
    + "  \"partner\": {"
    + "    \"solutionId\": \"ttctestpartner\""
    + "  }"
    + "},"
    + "\"processingInformation\": {"
    + "  \"capture\": true,"
    + "  \"actionList\": [\"TOKEN_CREATE\"]"
    + "},"
    + "\"paymentInformation\": {\""
    + "  \"card\": {"
    + "    \"number\": \"4111111111111111\","
    + "    \"expirationMonth\": \"12\","
    + "    \"expirationYear\": \"2031\""
    + "  }"
    + "},"
    + "\"orderInformation\": {"
    + "  \"amountDetails\": {"
    + "    \"totalAmount\": \"102.21\","
    + "    \"currency\": \"USD\""
    + "  },"
    + "  \"billTo\": {"
    + "    \"firstName\": \"John\","
    + "    \"lastName\": \"Doe\","
    + "    \"address1\": \"1 Market St\","
    + "    \"locality\": \"san francisco\","
    + "    \"administrativeArea\": \"CA\","
    + "    \"postalCode\": \"94105\","
    + "    \"country\": \"US\","
    + "    \"email\": \"test@cybs.com\","
    + "    \"phoneNumber\": \"4158880000\""
    + "  }"
    + "}"
    + "}";

Request request = new Request.Builder()
    .url("https://api-matest.cybersource.com/pts/v2/payments")
    .addHeader("Authorization", "Bearer " + accessToken)
    .addHeader("Content-Type", "application/json")
    .post(RequestBody.create(paymentJson, JSON))
    .build();

Response response = client.newCall(request).execute();

using System.Net.Http;
using System.Security.Cryptography.X509Certificates;
using System.Text;

// Setup HttpClientHandler with client certificates
var handler = new HttpClientHandler();

// Load the certificate and key files provided by TTC Payments
// var clientCert = X509Certificate2.CreateFromPemFile("client.crt", "client.key");
// handler.ClientCertificates.Add(clientCert);

var client = new HttpClient(handler);
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var paymentJson = @"{
    ""clientReferenceInformation"": {
        ""code"": ""TTUSAS_123456"",
        ""partner"": {
            ""solutionId"": ""ttctestpartner""
        }
    },
    ""processingInformation"": {
        ""capture"": true,
        ""actionList"": [""TOKEN_CREATE""]
    },
    ""paymentInformation"": {
        ""card"": {
            ""number"": ""4111111111111111"",
            ""expirationMonth"": ""12"",
            ""expirationYear"": ""2031""
        }
    },
    ""orderInformation"": {
        ""amountDetails"": {
            ""totalAmount"": ""102.21"",
            ""currency"": ""USD""
        },
        ""billTo"": {
            ""firstName"": ""John"",
            ""lastName"": ""Doe"",
            ""address1"": ""1 Market St"",
            ""locality"": ""san francisco"",
            ""administrativeArea"": ""CA"",
            ""postalCode"": ""94105"",
            ""country"": ""US"",
            ""email"": ""test@cybs.com"",
            ""phoneNumber"": ""4158880000""
        }
    }
}";

var content = new StringContent(paymentJson, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api-matest.cybersource.com/pts/v2/payments", content);

<?php
// Paths to the certificate and key files provided by TTC Payments
$certFile = '/path/to/client.crt';
$keyFile = '/path/to/client.key';

$paymentData = [
    'clientReferenceInformation' => [
        'code' => 'TTUSAS_123456',
        'partner' => [
            'solutionId' => 'ttctestpartner'
        ]
    ],
    'processingInformation' => [
        'capture' => true,
        'actionList' => ['TOKEN_CREATE']
    ],
    'paymentInformation' => [
        'card' => [
            'number' => '4111111111111111',
            'expirationMonth' => '12',
            'expirationYear' => '2031'
        ]
    ],
    'orderInformation' => [
        'amountDetails' => [
            'totalAmount' => '102.21',
            'currency' => 'USD'
        ],
        'billTo' => [
            'firstName' => 'John',
            'lastName' => 'Doe',
            'address1' => '1 Market St',
            'locality' => 'san francisco',
            'administrativeArea' => 'CA',
            'postalCode' => '94105',
            'country' => 'US',
            'email' => 'test@cybs.com',
            'phoneNumber' => '4158880000'
        ]
    ]
];

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api-matest.cybersource.com/pts/v2/payments',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($paymentData),
    CURLOPT_SSLCERT => $certFile,
    CURLOPT_SSLKEY => $keyFile,
    CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);
$paymentResult = json_decode($response, true);
curl_close($curl);
?>

Step 3: Receive CyberSource OAuth Callback ​

Overview ​

After submitting the payment in Step 2, the integrator must POST the CyberSource response payload back to TTC Payment Gateway, containing the transaction identifier and key booking details to this endpoint. TTC's Payment Gateway validates the data with CyberSource, finds the selling company configuration, and then updates the corresponding booking system.

Processing Flow ​

1. Integrator forwards CyberSource's payment response (including the transaction ID) to this callback endpoint.
2. TTC verifies the transaction with CyberSource using the supplied identifiers and amounts.
3. The validated payload is combined with selling company data and routed to the appropriate booking platform.

Endpoints ​

Test Environment

POST https://paymentgateway.uat.travcorpservices.com/cybersource/oauth/callback

Production Environment

POST https://paymentgateway.travcorpservices.com/cybersource/oauth/callback

Authentication ​

• Include the x-api-key header provided by TTC Payments; callbacks without a valid API key are rejected.
• Use the same x-api-key you received for the token endpoint in Step 1—there is a single key per integrator for both endpoints.

Request ​

Headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY

Body Parameters:

Example Payload:

{
  "merchantId": "ttc_ttusas_m",
  "transactionId": "7515647504736821004807",
  "bookingId": "C253535",
  "currency": "USD",
  "amount": "102.21"
}

Response ​

Success Response (200):

{
  "message": "ok"
}

Error Handling ​

Important Notes for Implementation ​

1. Certificate Management:

   • Store the mTLS certificates provided by TTC Payments securely
   • Restrict file permissions and access to the certificate and key files
   • Never commit certificates to version control

2. Error Handling:

   • Implement proper exception handling for network errors
   • Check HTTP status codes before processing responses
   • Handle token expiration scenarios

3. Security:

   • Store API keys in environment variables or secure key management systems
   • Use HTTPS for all communications
   • Validate SSL certificates in production

4. Testing:

   • Use TEST endpoints for development and testing
   • Test with CyberSource test card numbers
   • Verify mTLS certificate handling works correctly

Integration Best Practices ​

Security ​

• Store API keys securely - Never expose your x-api-key in client-side code
• Use HTTPS only - All communications must be over secure connections
• Certificate handling - Store the mTLS certificates provided by TTC Payments securely
• Token management - Request new tokens before expiration (every ~15 minutes)

Error Handling ​

• Implement retry logic for transient failures
• Handle token expiration gracefully by requesting new tokens
• Log errors appropriately while avoiding sensitive data in logs
• Validate responses before processing

Performance ​

• Cache tokens until near expiration to reduce API calls
• Reuse connections when possible for better performance
• Monitor response times and implement timeouts

Testing ​

• Use TEST environment for all development and testing
• Test with various card numbers provided by CyberSource
• Validate error scenarios including declined payments
• Test token expiration handling

Support ​

For technical support or questions about this integration:

• TTC Payments Team: Contact your TTC Payment Team at cardpayments@travcorpuk.com
• API Key Issues: Reach out to provision or rotate API keys
• CyberSource Documentation: Refer to CyberSource Developer Center

Changelog ​