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 and mTLS certificates to process payments with CyberSource

Step 1: Request Access Token ​

Overview ​

This endpoint retrieves a CyberSource OAuth access token along with the required mTLS certificates for secure communication with CyberSource APIs.

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,
  "mTls_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...\n-----END PRIVATE KEY-----",
  "mTls_cert": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKoK/OvD78JEMA0GCSqGSIb3DQEBBQUA...\n-----END CERTIFICATE-----"
}

Response Fields:

• access_token: Bearer token for CyberSource API authentication
• token_type: Always "Bearer"
• expires_in: Token validity period in seconds
• mTls_key: Private key for mutual TLS authentication
• mTls_cert: Certificate for mutual TLS authentication

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

Step 2: Submit Payment to CyberSource ​

Overview ​

Once you have obtained the access token and mTLS certificates, 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 obtained from Step 1.

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 from the token response:

1. Extract the certificates from the token response
2. Configure your HTTP client to use client certificate authentication
3. Use the certificates for all CyberSource API calls

Example using curl:

# Save certificates to files
echo "$mTls_cert" > client.crt
echo "$mTls_key" > 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 and certificates from Step 1.

# Save certificates to files
echo "$mTls_cert" > client.crt
echo "$mTls_key" > 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

# Clean up certificates
rm client.crt client.key

import requests
import tempfile
import os

# Save certificates to temporary files
with tempfile.NamedTemporaryFile(mode='w', suffix='.crt', delete=False) as cert_file:
    cert_file.write(mTls_cert)
    cert_path = cert_file.name

with tempfile.NamedTemporaryFile(mode='w', suffix='.key', delete=False) as key_file:
    key_file.write(mTls_key)
    key_path = key_file.name

try:
    # 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()
    
finally:
    # Clean up certificate files
    os.unlink(cert_path)
    os.unlink(key_path)

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

// Write certificates to temporary files
const certPath = '/tmp/client.crt';
const keyPath = '/tmp/client.key';

fs.writeFileSync(certPath, mTlsCert);
fs.writeFileSync(keyPath, mTlsKey);

try {
    // 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;
    
} finally {
    // Clean up certificate files
    fs.unlinkSync(certPath);
    fs.unlinkSync(keyPath);
}

// 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();

// Convert PEM to X509Certificate2 (requires additional code)
// var clientCert = ConvertPemToCertificate(mTlsCert, mTlsKey);
// 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
// Save certificates to temporary files
$certFile = tempnam(sys_get_temp_dir(), 'client_cert_');
$keyFile = tempnam(sys_get_temp_dir(), 'client_key_');

file_put_contents($certFile, $mTlsCert);
file_put_contents($keyFile, $mTlsKey);

$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);

// Clean up certificate files
unlink($certFile);
unlink($keyFile);
?>

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 mTLS certificates securely and temporarily
   • Clean up certificate files after use
   • 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 mTLS certificates securely and temporarily
• 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 ​