Communications API for Sycurio Integrations
Overview
The CASI API enables seamless integration between the CCG (Convenient Checkout Gateway) platform and Sycurio for secure telephonic payment processing. This API facilitates the secure exchange of payment data captured via DTMF (Dual-Tone Multi-Frequency) technology, ensuring PCI-compliant handling of sensitive information.
Key Features
- Secure Data Transmission: Ensures all payment data is securely transmitted between the telephony system and Sycurio.
- PCI Compliance: Maintains compliance with PCI DSS requirements for telephonic payment processing.
- Real-Time Integration: Supports real-time communication for immediate payment authorization and confirmation.
- Flexible Integration: Designed to work with various telephony infrastructures, including WWE10 and Omni telephony systems.
API Endpoints
Insert API
Insert the call into the Sycurio System.
GET https://api-stg.uhg.com/api/infra/sipsessionmanagers/1.0.1/casi/insert?msid=[YOUR_MS_ID_HERE] HTTP/1.1
Host: api-stg.uhg.com
X-Upstream-Env: dev
Authorization: Bearer [YOUR_TOKEN_HERE]
Responses
Success (200 OK):
{
"sycurioURL": "stg-elr-semaproxy.uhc.com/",
"sycurioCR": "7C8705E71756481890717"
}
Failure (HTTP 500):
{
"detail": "Failed to retrieve context data"
}
Failure (HTTP 504 Gateway Timeout):
{
"detail": "Gateway Timeout. The upstream service did not respond in time."
}
Failure (e.g., 400/401/404):
{
"error": "Invalid MSID or session not found."
}
Inspect API
Confirm the call is present in Sycurio before loading the payment fragment.
GET https://api-stg.uhg.com/api/infra/sipsessionmanagers/1.0.1/casi/inspect?msid=[YOUR_MS_ID_HERE] HTTP/1.1
Host: api-stg.uhg.com
X-Upstream-Env: dev
Authorization: Bearer [YOUR_TOKEN_HERE]
Responses
Success (200 OK):
CONFIRMED
Failure (HTTP 500):
{
"detail": "Failed to retrieve context data"
}
Failure (HTTP 504 Gateway Timeout):
{
"detail": "Gateway Timeout. The upstream service did not respond in time."
}
Failure (e.g., 400/401/404):
{
"error": "Location is empty in context"
}
Remove API
After the payment flow, remove the call from Sycurio.
GET https://api-stg.uhg.com/api/infra/sipsessionmanagers/1.0.1/casi/remove?msid=[YOUR_MS_ID_HERE] HTTP/1.1
Host: api-stg.uhg.com
X-Upstream-Env: dev
Authorization: Bearer [YOUR_TOKEN_HERE]
Responses
Success (200 OK):
{
"message": "Semafone endpoint removed successfully and SemafoneCr updated to '0'."
}
Failure (HTTP 500):
{
"detail": "Failed to retrieve context data"
}
Failure (HTTP 504 Gateway Timeout):
{
"detail": "Gateway Timeout. The upstream service did not respond in time."
}
Failure (e.g., 400/401/404):
{
"error": "Location is empty in context"
}
Expected Inspect Responses and Retriability
| Response State / Message | HTTP Status | Response Type | Retriable | Comment |
|---|---|---|---|---|
| EARLY | Internal | N/A | N/A | Internal to Session Manager and not exposed to CCG. This is before the first call is established. |
| CONFIRMED | 200 | string | No | Sycurio fragment can be loaded; Security and media ports are negotiated and media now flows through Sycurio; At this point you can load the payment fragment and enter Secure mode. |
| CONNECTED | 200 | string | No | Stable state when the SIP call is active with an endpoint. |
| RINGING | 500 | JSON | Yes | Transitional state while placing Sycurio upstream; During RINGING, the agent and customer can continue to talk while media is being moved; CASI may return HTTP 500 with { "detail": "Failed to make Semafone inspect URL call" }; treat as transient and retry until a stable state (e.g., CONFIRMED) or a terminal state is reached. |
| TRANSFERRING | 500 | JSON | Yes | Transitional state during an API/REFER transfer; CASI may return HTTP 500 with { "detail": "Failed to make Semafone inspect URL call" }; treat as transient and retry until a stable state (e.g., CONFIRMED) or a terminal state is reached. |
| DISCONNECTED | 400 | string | No | Call ended normally by either party. Stop polling. |
| ABANDONED | 400 | string | No | Caller hung up during a transfer. Stop polling. |
| DECLINED | 400 | string | No | Blind transfer was rejected; no further call treatment. Stop polling. |
| HTTP 504 Gateway Timeout | 504 | JSON | Yes | Temporary network or service issue. Retry is recommended. |
| QUEUED | Internal | N/A | N/A | Session Manager has detected an overload event on a downstream device and has queued the call to protect the system. This state only occurs before call arrival to an agent. A call can only transition from EARLY to QUEUED. No other state may transition to QUEUED. |
{ "detail": "Failed to retrieve context data" } | 500 | JSON | No | CASI has no records for the user id. Investigate Agent Desktop integration with Enterprise Desktop Team. |
{ "detail": "Failed to make Semafone inspect URL call" } | 500 | JSON | Yes | During, RINGING & TRANSFERRING CASI return HTTP 500 with this message; But after a successful REMOVE call, when INSPECT is called then also CASI returns HTTP 500 with same message. This is a bug. CONNECTED should be returned. Treat as needing to perform an insert. |
{ "detail": "Location is empty in context" } | 400 | JSON | No | Call is connected but no insert was attempted. Inspect should only be called after insert. |
note
In telephony (SIP protocol), REFER is a SIP method used to instruct the recipient to initiate a call transfer to another party. When a call is being transferred using REFER, the current call participant is told to connect to a new destination, effectively moving the call to another endpoint. This is commonly used for call transfers in VoIP systems.
Continuous Polling
CCG uses a continuous polling mechanism to monitor the status of telephonic payment sessions in real time. This approach ensures that CCG can promptly detect changes in session state and respond accordingly, providing a seamless experience for both agents and customers.
- Polling Interval: CCG sends periodic requests (polls) to the CASI Inspect API to check the current status of the session. The interval between polls is currently 1 Second.
- Session State Monitoring: Each poll retrieves the latest session state (e.g., CONFIRMED, DISCONNECTED). CCG uses this information to determine the next action, such as loading the payment fragment or ending the session.
- Stop Conditions:
- Polling stops when a non-retriable error occurs.
- Stop polling if there’s no change for 10 minutes (idleTimeoutMillis: 600000) to avoid keeping an inactive session open.
- Hard stop for polling at 30 minutes (forceTimeoutMillis: 1800000) — even if activity continues—to protect system resources.
- Error Handling: If a retriable error occurs during polling (as defined in the Expected Inspect Responses and Retriability table), CCG applies its retry strategy before resuming normal polling.
- Efficiency: The polling mechanism is designed to minimize unnecessary network traffic and system resource usage while ensuring timely updates.
CCG Integration Behavior and Guidance
- CCG issues INSERT and INSPECT in quick succession and does not consume phone event streams.
- If INSPECT returns RINGING, retry until you receive CONFIRMED.
- Any INSPECT that hits a transitional state that is not CONFIRMED returns HTTP 500 with details. Treat this as transient and retry.
- Any INSPECT after the call has ended returns HTTP 400 with a reason of DISCONNECTED, ABANDONED, or DECLINED.
- After a successful INSERT, the state moves from RINGING to CONFIRMED once media negotiation completes. Load the payment fragment only after CONFIRMED.
- Once a call reaches CONFIRMED, it stays there until you call REMOVE or the call ends.
- When you call REMOVE, Session Manager removes Sycurio from the path and the state returns to CONNECTED. The REMOVE response is HTTP 500 by design for legacy compatibility.
- If the call ends, the state moves to a final status and API responses return HTTP 400.