API Document Template

This template is intended to standardize API use case documentation for both consumers and engineers. Please follow the structure and provide clear, concise, and complete information for each section.

---

1. Handling (Feature Name)

Purpose: Briefly describe the feature or use case from both consumer and engineer perspectives.

For example: Handling Pre-Authorization

Example description:
When a payment is authorized, it must be captured for funds to be transferred to the merchant. Multiple captures are not supported by the CCG system; the merchant should capture the required amount in the first attempt.

---

2. API Request

Purpose: Describe how to make the API request for this use case.
Include: Required fields, optional fields, and any flags or parameters relevant to the feature.

For example: Payment request with pre-authorization

Key Points:

• Merchants can indicate partial auth via the partialAuthorization flag in /sessions or /payments APIs.
• Example fields:
  • sessionRequest.payment.partialAuthorization
  • paymentRequest.partialAuthorization

Sample /sessions request: Pre-Authorization

## /POST sessions request
curl --location --request POST 'https://api.uhg.com/api/financial/commerce/nonprodcheckout/v1/sessions' \
--header 'X-Merchant-Id: <x-merchant-id>' \
--header 'X-Upstream-Env: <x-upstream-env>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authorization-token>' \
--data-raw '{
"customer": {
    "firstName": "foo",
    "lastName": "bar",
    "email": "foo.bar@email.com",
    "ssnLastFour": "1234",
    "dateOfBirth": "1970-31-12",
    "phoneNumber": {
        "number": "9876543210",
        "countryCode": "1"
    },
    "zip5": "54321",
    "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
    "metadata": {}
},
"payment": {
    "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
    "amount": 1200,
    "authorizeCard": true,
}
}'

---

3. API Response

Purpose: Show the expected API response for this use case.
Include: Important response fields, status codes, and flags.

For example: Payment response with partial authorization

Sample /sessions response: Pre-Authorization

{
"data": {
    "sessionId": "",
    "status": "COMPLETED",
    "payment": {
        "id": "",
        "amount": 183,
        "authorizedAmount": 128,
        "capturedAmount": 0,
        "description": "",
        "merchantTransactionId": "",
        "merchantId": "",
        "paymentType": "PRE_AUTH",
        "currencyCode": "usd",
        "status": "AUTHORIZED",
        "paymentMethodId": "",
        "statementDescriptorSuffix": "",
        "partialAuthorization": true,
        "metadata": {},
        "paymentMethod": {},
        "agent": {}
    },
}
}

---

4. Error Handling

Purpose: List possible error scenarios, their status codes, and sample error responses.
Best Practice: Clearly document validation rules and business logic that may result in errors.

For example: Partial auth is applicable only for PRE_AUTH (i.e., authorizeCard=true) payments involving the 'card' payment method type.

Common Error Scenarios:

• Invalid flag combinations
• Missing required fields
• Unsupported payment types

info

Example Error Scenario:

1. Partial authorization not allowed for authorizeCard = false

Sample Request:

Partial Auth Request

{
"payment":{
  "partialAuth":true,
  "authorizeCard": false
}
}

Sample Response:

Partial Auth Failed Response

{
"title": "INVALID_REQUEST",
"status": 400,
"detail": "Partial authorization not allowed for authorizeCard = false",
"errorDetails": null
}

---

5. Additional Notes & Best Practices

• Always validate required fields before making API requests.
• Use clear and descriptive error messages.
• Include versioning information if applicable.
• Reference related documentation or API specs where helpful.

---

6. Revision History

Version	Date	Description
1.0	YYYY-MM-DD	Initial draft