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-sourcevalue in the header
- Persistence across session-initiated flows
If x-source is set during session creation, its value persists and is automatically included on subsequent payment-method and payment requests created later in that same session β the merchant does not need to resend it on every call.
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-sourcevalue in the header on session creation request, which is persisted for the duration of the session.
Validationβ
x-sourceheader is optional.- Maximum size of newly added header
x-sourceis 50 characters. Error message for this check isx-source header should be less than 50 characters.
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
2. Payment related webhooks
- PAYMENT_SUCCEEDED
- PAYMENT_FAILED
- PAYMENT_AUTHORIZED
- PAYMENT_CANCELED
- PAYMENT_ACCEPTED
3. Refund related webhooks
- REFUND_SUCCESS
- REFUND_PENDING
- REFUND_FAILED