1. Overview
CC.Bridge.Server is an ASP.NET ASMX Web Service that
provides a SOAP-based bridge between client applications and the Synergy credit
card processing back-end. It exposes database-authenticated methods for
retrieving transaction history, managing customer payment tokens, reading audit
logs, and writing transaction records to the Synergy database.
The service is deployed as CCBridge.asmx under IIS and
communicates exclusively over SOAP 1.1. All endpoints require a valid session
key supplied in a SOAP header; raw database credentials are never transmitted
through the API after the initial login handshake.
2. Technology Stack
|
Component
|
Detail
|
|
Framework
|
ASP.NET Web Services (ASMX) — .NET Framework
|
|
Protocol
|
SOAP 1.1 over HTTP/HTTPS
|
|
Service File
|
CCBridge.asmx
/ CCBridge.asmx.cs
|
|
Namespace
|
CC.Bridge.Net
|
|
SOAP Namespace
|
http://ccbridge.org/
|
|
Supported Databases
|
Oracle (ODP.NET Managed) and Microsoft SQL Server
|
|
Authentication
|
Session key via SOAP header (AuthenticationKey)
|
|
Logging
|
log4net (SRIMacroServer.log)
|
|
Configuration
|
Web.config +
Connection.config + Credentials/*.xml
|
3. Authentication
The service uses a two-phase authentication model:
3.1 Session Key Flow
• The client first obtains a session key from the Synergy
host application (or the SRI Macro Server).
• This key is a 16-byte random token generated using
RandomNumberGenerator (FIPS-compliant).
• The key is stored server-side in the Credential Cache
as an XML file at the path specified by CredentialCacheLocation in Web.config.
• Every subsequent API call must include the key in the
AuthenticationKeyHeader SOAP header.
3.2 Credential Cache
The server resolves the session key to an ActiveCredentials
record containing:
|
Field
|
Type
|
Description
|
|
Key
|
string
|
The session token
|
|
DbType
|
string
|
"Oracle" or "SqlServer"
|
|
Server
|
string
|
Database server host name or DSN
|
|
Database
|
string
|
Database / schema name
|
|
User
|
string
|
DB username (stored upper-cased)
|
|
Password
|
string
|
Encrypted database password
|
|
Expiration
|
DateTime
|
UTC expiry timestamp (default +120 min, rolling)
|
3.3 Key Expiry Rules
• Standard keys expire 120 minutes after last use
(rolling window).
• A background purge removes keys older than PurgeEvery
minutes (default 1440 min / 24 hr).
• Keys listed in the NeverExpires section of
Connection.config bypass expiry entirely.
• If a key is missing or expired the service throws:
"Invalid or Expired Credentials Key: <key>"
4. Configuration Files
4.1 Web.config — Key App Settings
|
Setting
|
Purpose
|
|
CredentialCacheLocation
|
File-system path where session-key XML files are stored
|
|
MacroServerDLLPath
|
Path used to resolve Connection.config when ApplicationPath is
null
|
4.2 Connection.config
An XML file co-located with the service that controls
database routing and key lifetime. Key sections:
<ConnectionConfig>
<ConnectionLifetime
ExpiresAfter="120" PurgeEvery="1440">
<NeverExpires>
<Key
Key="PERMANENT-KEY-VALUE" Comments="Service account" />
</NeverExpires>
</ConnectionLifetime>
<DatabaseConnections
DefaultType="SqlServer" DefaultServer="DBSERVER01"
AllowConnection="true">
<Database
alias="MYDB" db="MYDB" Type="SqlServer"
Server="SQLHOST" />
<Database
db="ORACLE_SCHEMA" Type="Oracle" Server="ORA_TNS"
/>
</DatabaseConnections>
</ConnectionConfig>
5. Web Methods Reference
All methods reside in the CCBridge class (CCBridge.asmx).
Every method requires the AuthenticationKeyHeader SOAP header unless otherwise
noted.
5.1 GetTransactions
|
Attribute
|
Value
|
|
Method Name
|
GetTransactions
|
|
Return Type
|
List<SRI_CC_TRANSACTIONS>
|
|
Parameter 1
|
string
OrderId
|
|
Parameter 2
|
bool
IsSettlement
|
|
Auth Header
|
AuthenticationKeyHeader required
|
Description:
Retrieves all credit card transaction records for a given
order. Pass IsSettlement = true to filter for settlement transactions only, or
false to return authorisation records.
Sample SOAP Request:
<soap:Header>
<ccb:AuthenticationKey>
<ccb:Key>AA-BB-CC-DD-EE-FF-00-11-22-33-44-55-66-77-88-99</ccb:Key>
</ccb:AuthenticationKey>
</soap:Header>
<soap:Body>
<ccb:GetTransactions>
<ccb:OrderId>ORD-2024-00123</ccb:OrderId>
<ccb:IsSettlement>false</ccb:IsSettlement>
</ccb:GetTransactions>
</soap:Body>
</soap:Envelope>
5.2 GetCustomerTokens
|
Attribute
|
Value
|
|
Method Name
|
GetCustomerTokens
|
|
Return Type
|
List<SRI_CUSTOMER_TOKENS>
|
|
Parameter 1
|
string
CustomerId
|
|
Auth Header
|
AuthenticationKeyHeader required
|
Description:
Returns all stored payment tokens (tokenised card
references) on file for the specified customer. Used to present saved payment
methods at checkout without exposing raw card numbers.
Sample SOAP Request:
<soap:Body>
<ccb:GetCustomerTokens>
<ccb:CustomerId>CUST-001234</ccb:CustomerId>
</ccb:GetCustomerTokens>
</soap:Body>
5.3 GetAuditLog
|
Attribute
|
Value
|
|
Method Name
|
GetAuditLog
|
|
Return Type
|
List<SRI_CREDIT_CARD_AUDIT>
|
|
Parameter 1
|
string
DocId
|
|
Auth Header
|
AuthenticationKeyHeader required
|
Description:
Retrieves the full credit card audit trail for a document
(invoice, sales order, etc.) identified by DocId. Returns a chronological list
of all processor interactions recorded against that document.
Sample SOAP Request:
<soap:Body>
<ccb:GetAuditLog>
<ccb:DocId>INV-2024-00456</ccb:DocId>
</ccb:GetAuditLog>
</soap:Body>
5.4 SetCustomerToken
|
Attribute
|
Value
|
|
Method Name
|
SetCustomerToken
|
|
Return Type
|
void
|
|
Parameter 1
|
CreditCardResponse
Transaction
|
|
Auth Header
|
AuthenticationKeyHeader required
|
Description:
Persists a tokenised customer payment method to the Synergy
database from a completed CreditCardResponse record. Called after a successful
authorisation to store the gateway-issued token for future charges.
CreditCardResponse Key Fields:
|
Field
|
Type
|
Description
|
|
CustomerId
|
string
|
Synergy customer identifier
|
|
Token
|
string
|
Gateway-issued payment token
|
|
CardType
|
string
|
e.g. Visa, MasterCard
|
|
Last4
|
string
|
Last four digits of card number
|
|
ExpiryDate
|
string
|
Card expiry in MM/YY format
|
5.5 SetCreditCardTrans
|
Attribute
|
Value
|
|
Method Name
|
SetCreditCardTrans
|
|
Return Type
|
void
|
|
Parameter 1
|
CreditCardTransaction
Transaction
|
|
Auth Header
|
AuthenticationKeyHeader required
|
Description:
Writes a completed credit card transaction record to the
SRI_CC_TRANSACTIONS table. Called at the completion of an authorization,
capture, void, or refund to maintain a full transaction ledger in Synergy.
If this is a deposit/charge transaction the call will generate a record into the visual erp system in the following manner:
1. Validate
that the customer order exists using CustomerOrderId field
2. If
CaptureAmt > 0
a. Create
a Visual ERP Receivable data record
b. If
Omit Bank Transactions (see SRI_CC_BANK_ACCOUNT record) stop processing
c. Create
a Bank Deposit record in Visual ERP
d. Create
a Cash Receipt record in Visual ERP
CreditCardTransaction Fields:
|
Field
|
Type
|
Default
|
Description
|
|
SiteId
|
string
|
""
|
Site / location identifier
|
|
Gateway
|
string
|
""
|
Payment gateway name (e.g. Authorize.Net, Braintree)
|
|
CustomerOrderId
|
string
|
""
|
Visual ERP Customer Id or Document Id
|
|
TransactionId
|
string
|
""
|
Gateway transaction reference number
|
|
ApprovalCode
|
string
|
""
|
Processor approval / authorisation code
|
|
BankID
|
string
|
""
|
Bank identifier returned by processor
|
|
MaskedCardNumber
|
string
|
""
|
Masked PAN for display (e.g. ****4242)
|
|
Token
|
Guid
|
Guid.Empty
|
Internal unique reference (GUID). Not the gateway TransactionId.
|
|
CreateDate
|
DateTime
|
DateTime.UtcNow
|
UTC timestamp the record was created
|
|
Status
|
string
|
""
|
Current transaction status
|
|
AuthAmount
|
decimal
|
0
|
Authorised amount in dollars and cents (e.g. 10.00)
|
|
CaptureAmount
|
decimal
|
0
|
Captured / settled amount in dollars and cents
|
|
TransactionType
|
string
|
""
|
"AUTH", "CAPTURE", "REFUND", or
"VOID"
|
|
PaymentCode
|
string
|
""
|
Payment method code returned by processor
|
|
CardProfileId
|
string
|
""
|
Credit card token in the vendor / gateway system
|
|
CustomerProfileId
|
string
|
""
|
Customer profile token in the vendor / gateway system
|
|
PaymentProfileId
|
string
|
""
|
Transaction token used for refunds and voids to reference the
original transaction
|
|
JsonResponse
|
string
|
""
|
Raw JSON response from the credit card provider
|
|
UserId
|
string
|
""
|
Visual ERP User Id of the user who created the record (audit
trail)
|
6. SOAP Headers Reference
Three SOAP header classes are defined in CCBridge.asmx.cs.
Only AuthenticationKey is required by the public web methods; the Header class
is used internally for SQL pass-through.
|
Header Class
|
Field(s)
|
Description
|
|
AuthenticationKey
|
Key
(string)
|
Session token. Required on all public web methods.
|
|
Credentials
|
Database,
UserID, Password
|
Legacy header — not currently used by active web methods.
|
|
Header
|
Key,
Sql, UseOleDB, CommandType, Parameters[]
|
Internal SQL pass-through header used by NewCommand property.
|
7. Error Handling
All errors are surfaced as SOAP faults. The following table
lists the most common exceptions:
|
Error
Message
|
Cause /
Resolution
|
|
Missing
AuthenticationKeyHeader
|
The SOAP header was omitted. Add AuthenticationKey header to
every request.
|
|
Invalid
or Expired Credentials Key: <key>
|
Key not found in cache or has passed expiration. Obtain a new
session key from the host application.
|
|
Retrieve
Credentials Error
|
File I/O error reading the credential cache. Check
CredentialCacheLocation path and permissions.
|
|
HTTP
500 Internal Server Error
|
Unhandled exception — check SRIMacroServer.log for full stack
trace.
|
8. Testing the Endpoints
8.1 Prerequisites
•
IIS hosting CCBridge.asmx is running and reachable.
•
A valid session key has been provisioned in
CredentialCacheLocation (as a <key>.xml file).
•
The target database (Oracle or SQL Server) is
accessible from the IIS server.
8.2 Using the Built-in ASMX Test
Page
Navigate to the service URL in a browser to access the
auto-generated WSDL and method test forms:
http://<server>/CCBridge.asmx
// WSDL
http://<server>/CCBridge.asmx?WSDL
Note: The test forms on the ASMX page only support simple
type parameters. Methods requiring a SOAP header (AuthenticationKey) cannot be
tested from the browser form — use SoapUI or a code client instead.
8.3 Testing with SoapUI
1.
Launch
SoapUI and create a New SOAP Project.
2.
Set
the Initial WSDL to: http://<server>/CCBridge.asmx?WSDL
3.
SoapUI
will auto-generate request templates for all five web methods.
4.
In
the generated request XML, replace the placeholder in
<AuthenticationKey><Key> with your session key.
5.
Fill
in the method-specific parameters and click the green Run button.
6.
Inspect
the Response panel — a successful call returns HTTP 200 with a SOAP envelope
containing the result.
8.4 Testing with PowerShell
PowerShell can consume the WSDL automatically:
# Create a SOAP proxy
$proxy = New-WebServiceProxy -Uri
"http://<server>/CCBridge.asmx?WSDL" `
-Namespace "CCBridge"
# Build the authentication header
$authHeader = New-Object CCBridge.AuthenticationKey
$authHeader.Key =
"AA-BB-CC-DD-EE-FF-00-11-22-33-44-55-66-77-88-99"
$proxy.AuthenticationKeyHeaderValue = $authHeader
# Call GetTransactions
$results = $proxy.GetTransactions("ORD-2024-00123",
$false)
$results | Format-Table -AutoSize
# Call GetCustomerTokens
$tokens = $proxy.GetCustomerTokens("CUST-001234")
$tokens | Format-Table -AutoSize
# Call GetAuditLog
$audit = $proxy.GetAuditLog("INV-2024-00456")
$audit | Format-Table -AutoSize
8.5 Testing with C# (.NET Client)
Add a Service Reference (or use dotnet-svcutil) pointing to
the WSDL, then:
using CCBridgeServiceReference;
// generated proxy namespace
var client = new CCBridgeSoapClient();
var authHeader = new AuthenticationKey { Key =
"AA-BB-CC-DD-..." };
// GetTransactions
var txns = client.GetTransactions(authHeader,
"ORD-2024-00123", false);
// GetCustomerTokens
var tokens = client.GetCustomerTokens(authHeader,
"CUST-001234");
// GetAuditLog
var audit = client.GetAuditLog(authHeader,
"INV-2024-00456");
// SetCustomerToken (write operation)
var ccResp = new CreditCardResponse {
CustomerId =
"CUST-001234",
Token = "tok_gateway_abc123",
CardType = "Visa",
Last4 = "4242",
ExpiryDate =
"12/26"
};
client.SetCustomerToken(authHeader, ccResp);
// SetCreditCardTrans (write operation)
var ccTrans = new CreditCardTransaction {
OrderId = "ORD-2024-00123",
TransactionId = "txn_gateway_xyz789",
Amount = 150.00m,
TransactionType =
"Auth",
ResponseCode = "00",
IsSettlement = false
};
client.SetCreditCardTrans(authHeader, ccTrans);
8.6 Verifying Database Connectivity
To confirm the service can reach the database with a given
key before running full tests:
# Check that the credential XML file exists
Test-Path
"C:\CCBridge\CredentialCache\AA-BB-CC-DD-EE-FF-00-11-22-33-44-55-66-77-88-99.xml"
# View the credential expiry time
[xml](Get-Content
"C:\CCBridge\CredentialCache\<key>.xml")
# Look for <EXPIRATION> element — must be in the future
9. Deployment Notes
9.1 IIS Application Pool
•
Use a dedicated Application Pool running under an
account with read/write access to CredentialCacheLocation.
•
Enable 32-bit applications if Oracle ODP.NET 32-bit
drivers are in use.
•
.NET Framework 4.x (Full CLR) is required.
9.2 Web.config Minimum Settings
<appSettings>
<add
key="CredentialCacheLocation"
value="C:\CCBridge\CredentialCache\" />
<add
key="MacroServerDLLPath"
value="C:\Synergy\Bin\MacroServer.dll" />
</appSettings>
9.3 Logging
log4net is configured via log4net.dll.config. The service
writes to SRIMacroServer.log in the application root. Increase log level to
DEBUG for detailed SOAP and database diagnostics during testing.
10. Quick Method Reference
|
Method
|
Parameters
|
Returns
|
Purpose
|
|
GetTransactions
|
OrderId,
IsSettlement
|
List<SRI_CC_TRANSACTIONS>
|
Fetch transaction history for an order
|
|
GetCustomerTokens
|
CustomerId
|
List<SRI_CUSTOMER_TOKENS>
|
Fetch stored payment tokens for a customer
|
|
GetAuditLog
|
DocId
|
List<SRI_CREDIT_CARD_AUDIT>
|
Fetch full audit trail for a document
|
|
SetCustomerToken
|
CreditCardResponse
|
void
|
Store a gateway payment token for a customer
|
|
SetCreditCardTrans
|
CreditCardTransaction
|
void
|
Write a completed transaction record to the DB
|