X-Source

Introduction

The x-source header identifies the originating system or surface of a request. Merchants may operate multiple surfaces (such as web, mobile app, etc.) within the same organization, and the x-source header helps distinguish between them. This header is optional but valuable for tracking and analytics.

Example:
For the Optum Rx merchant, requests may come from different surfaces like the Optum Rx website, mobile app, or partner portals. By setting the x-source header (e.g., x-source: optumrx-web or x-source: optumrx-mobile), each request can be traced back to its specific origin within the same merchant.

Implementation

• Implementation by Header

x-source is a string header that can be included in API requests. It is optional header.

Example of 'x-source` on header directly on API request

curl --location --request POST 'https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'X-Upstream-Env: ...' \
--header 'X-Merchant-Id: ...' \
--header 'Authorization: Bearer ....' \
--header 'X-source: testsource' \
--data-raw '{
"reason": "...",
"merchantTransactionId": "...",
"paymentId":"...",
"amount":...
}'

In this example:

• X-source:: contains x-source value in the header

• Implementation by Session storage and propagation by sidecar

When a session is created with the x-source header, its value is saved in the checkout-session table by the auth-service. Later, when a user or agent creates a payment method or payment in the widget, the call is intercepted by the sidecar, which retrieves the x-source value from the auth-service and includes it in the request. For implementation details, see config/templates/envoyfilter.yaml in customer-service or payment-service.

Example of 'x-source` on header of session creation

curl --location --request POST 'https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'X-Upstream-Env: test' \
--header 'X-Merchant-Id: ....' \
--header 'Cookie: ....' \
--header 'X-source: testxsource' \
--header 'Authorization: Bearer ....' \
--data-raw '{
    "customer": {
        "hsid": "...."
    },
  .....
   '

In this example:

• X-source:: contains x-source value in the header on session creation request. It will be saved in the checkout-session table by the auth-service and later propagated by the sidecar.

Validation

1. x-source header is optional.
2. Maximum size of newly added header x-source is 50 characters. Error message for this check is x-source header should be less than 50 characters.

Related DataBase

The x-source value is persisted in the following database tables:

Operation	Table	Column	Data Type	Nullable
SESSION	CHECKOUT_SESSION	SOURCE	VARCHAR2(50)	YES
SETUP PAYMENT METHOD	SETUP_PAYMENT_METHOD	SOURCE	VARCHAR2(50)	YES
PAYMENT	CC_PAYMENT	SOURCE	VARCHAR2(50)	YES
REFUND	CC_REFUND	SOURCE	VARCHAR2(50)	YES

Implemented services

Operation	HTTP Method	API Endpoint
Create Session	POST	/sessions
Update Payment Method	PATCH	/payment-methods/{payment-method-id}
Delete Payment Method	DELETE	/payment-methods/{payment-method-id}
Create Setup Intent	POST	/setup-payment-methods
Create Payment	POST	/payments
Update Payment	PATCH	/payments/{paymentId}/capture
Cancel Payment	PATCH	/payments/{paymentId}/cancel
Create Refund	POST	/refunds
Create Payment though IVR	POST	/token/payments

Related Webhooks

x-source will be added in the bellow webhooks of merchant-services

1. Payment method related webhooks

• PAYMENT_METHOD_UPDATED
• PAYMENT_METHOD_CREATED
• PAYMENT_METHOD_DELETED
• PAYMENT_METHOD_REPLACED

Quick Reference

Payment method Webhook Reference

2. Payment related webhooks

• PAYMENT_SUCCEEDED
• PAYMENT_FAILED
• PAYMENT_AUTHORIZED
• PAYMENT_CANCELED
• PAYMENT_ACCEPTED

Quick Reference

Payment Webhook Reference

3. Refund related webhooks

• REFUND_SUCCESS
• REFUND_PENDING
• REFUND_FAILED

Quick Reference

Refund Webhook Reference