Version: v2

Integration Document Template

This template standardizes API integration documentation for both consumers and engineers. Each section targets a specific integration need — from setup through error recovery.

When to Use This Template

Use this template when documenting an API-level feature or use case (e.g., split tender payments, pre-authorization, refunds). For business-level documentation, refer to the Business Use Case Guidelines.

Internal-Only Content

Use <Audience include="internal"> to wrap any content that should only be visible to the internal engineering team — such as architecture diagrams, processor-level details, internal status flows, or implementation notes.

<Audience include="internal">

### Internal Section Title

Content only visible to internal engineers — e.g., Stripe integration details, internal status codes, rollback flows.

</Audience>

✅ Use for: processor architecture, internal status combinations, retry/rollback flows, Stripe-specific behaviour, CCG internals.
❌ Do not use for: merchant-facing API usage, public error codes, standard integration steps.

Standard Section Headings

Every integration/API document must follow these section headings in this order. This keeps all integration docs consistent and scannable.

#	Section Heading	Purpose	Required?
—	`# [Feature Name]` (H1)	2–3 sentence intro: what it does, who benefits, when it's used	✅ Always
1	`## Integration Details`	Quick-reference summary, prerequisites, endpoints, links	✅ Always
2	`## [Feature Name] Processing Flow`	Internal architecture, sequence diagram, processing steps — wrap in `<Audience include="internal">`	✅ Always (internal)
3	`## API Request`	Use-case-specific sample requests, OpenAPI links	✅ Always
4	`## API Response`	Use-case-specific sample responses, error/failure types	✅ Always
5	`## Status Handling`	Status polling, mapping, parent/child status, internal mapping	✅ Always
6	`## Webhooks`	Webhook events, payloads, internal mapping	When webhooks exist
7	`## Error Handling`	Error code references, unique error scenarios	✅ Always
8	`## Retry Handling`	Retry logic, idempotency, rollback, internal retry flow	When retries exist
9	`## Version Comparison`	v1 vs v2 differences, migration guidance, Excel workbook	When multiple APIs
10	`## FAQ`	Common integration questions and answers	✅ Always
11	`## Integration Checklist`	Go-live checklist for integrators	✅ Always
12	`## Related Documentation`	Cross-reference links to API, business, error code docs	✅ Always

Sub-heading Standards

Within [Feature Name] Processing Flow, use these sub-headings:

Sub-heading	Purpose
`### Processing Steps`	Numbered summary of each internal stage
`### Sequence Diagram`	Mermaid diagram of system participants and message flow
`### Processor-Specifics`	Notes on processor/architecture-specific logic

Within Status Handling, use these patterns:

Sub-heading	Purpose
`### Status Mapping Table`	Parent/child status combinations, emoji labels, meanings
`### Internal Statuses`	Internal-only status mapping in `<Audience>` block

1. Overview

Purpose: Describe the feature from both consumer and engineer perspectives in 2–3 sentences.

Include:

What the feature does and when to use it
Key behaviour (e.g., all-or-nothing, idempotent, async)
Link to the related business use case document

Example:

Split Tender allows a customer to divide a single payment across two saved cards, both charged in parallel. This guide covers how to integrate — from making the request, to monitoring status, to handling errors.

2. Integration Details

Purpose: Quick-reference summary of the integration surface. Use a :::tip admonition. Cover all actionable prerequisites and links.

:::tip[Integration Details]
- **Enablement/Prerequisites:** (e.g., Merchant account must be configured. Link to merchant setup guide.)
- **API Endpoint(s):**
  - `POST v2/<endpoint>` — for direct API integration
  - `POST v2/sessions` — for widget-based flows (if applicable)
- **Scope:** (e.g., All operations at the `merchant` scope)
- **API Version:** v2
- **UI/Widget Version:** v3 (if applicable)
- **API Spec:** [Operation Name](/api-reference-v2/#tag/Merchant/operation/operationId)
- **Webhook Spec:** [onEventName](/webhooks-v2/#tag/Payment/operation/onEventName)
- **Testing:** Use test cards or sandbox data to simulate the flow. Link to test data/scenarios if available.
- **Error Handling:** See [Error Codes](/docs/developers/convenient-checkout-api/error-codes/payment-error-codes/) for feature-specific errors and remediation steps.
:::

2.1. Internal Processing Flow

Purpose: Document the internal processing architecture, sequencing, and step-by-step flow for the engineering team. This section is always wrapped in <Audience include="internal"> — it is never visible to external consumers.

Internal-Only Section

This section must be wrapped with <Audience include="internal"> tags. Never expose processor-level details, internal status models, or rollback mechanics to external readers.

What to include:

A Mermaid sequence diagram showing system participants (Merchant, CCG Platform, Processor/Stripe, individual payment instruments) and the full message flow
Processing Steps — a numbered summary of each stage (pre-validation, parallel processing, outcome determination, action orchestration, webhook emission)
Any processor-specific behaviour (e.g., PRE-AUTH + CAPTURE two-phase flow, automatic rollback/cancel triggers)
Internal status combinations not exposed in the merchant API

**Template:**

<Audience include="internal">

### [Feature] Processing Architecture

Brief description of the internal processing model — e.g., how cards are processed in parallel, how failures are handled.

<details>
<summary>[Feature] Process</summary>

```mermaid
sequenceDiagram
  participant M as Merchant
  participant CCG as CCG Platform
  participant S as Stripe (Payment Processor)
  participant C1 as Card 1

  M->>CCG: Payment Request
  Note over CCG: Validate payment method(s)
  CCG->>S: Process Card 1
  S->>C1: Charge Card 1
  C1-->>S: Card 1 Response
  S-->>CCG: Card 1 Result

  alt Success
    CCG-->>M: PAYMENT_SUCCEEDED (COMPLETED)
  else Failure
    CCG-->>M: PAYMENT_FAILED
  end
```

</details>

**Processing Steps:**
1. **Request received** — CCG receives the payment request
2. **Pre-validation** — Payment method(s) validated before calling the processor
3. **Processing** — Card(s) charged (describe parallel vs sequential as applicable)
4. **Outcome determination** — Based on success/failure of each payment instrument
5. **Action orchestration:**
   - Success path → capture / confirm
   - Failure path → cancel/rollback as applicable
6. **Webhook** — Event emitted at the parent transaction level

</Audience>

Reference implementation: See Split Tender Payments — the Split tender Processing Architecture section shows a full parallel-processing flow with rollback.

3. API Request

Purpose: Provide use-case-specific sample requests. Do NOT duplicate field definitions or constraints — the OpenAPI spec is the source of truth.

Guidelines:

Link to the relevant OpenAPI spec operation (e.g., Create Payment)
Only show a sample curl for the specific use case this document covers
Call out any use-case-specific fields or flags that differ from the standard request
Use staging base URL: https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/
Include all required headers (Authorization, X-Merchant-Id, X-Upstream-Env, Content-Type)

API Specification

For complete field definitions, constraints, and validations, refer to the OpenAPI Spec.

Sample Request Template

curl -X POST "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/{endpoint}" \
  -H "Authorization: Bearer <token>" \
  -H "X-Merchant-Id: <merchant-id>" \
  -H "X-Upstream-Env: dev" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "<unique-id>",
    "amount": 100,
    "customer": {
      "hsid": "<customer-hsid>"
    }
  }'

4. API Response

Purpose: Show use-case-specific sample responses. Do NOT list all response fields — the OpenAPI spec covers that.

Response Structure

Trim verbose nested objects (e.g., vendor, merchant, paymentMethod) in all samples for brevity. Use // ... see API Spec for full object ... comments as placeholders. Always link to the OpenAPI Spec for the complete structure.

Always provide samples covering these states (as collapsible <details> blocks):

Success (COMPLETED) — show fields unique to this use case
Failure — Business Rule Violation (FAILED, no allocations array) — request rejected before any processor call
Failure — Processing Failure (FAILED, allocations present with error object) — processor-level failure
Failure — Rollback (FAILED, one allocation ROLLED_BACK with remediation object) — partial failure triggers automatic rollback (if applicable to the feature)

Understanding Failure Responses

Document the distinction between failure types so integrators handle them correctly:

Business Rule Violations — No paymentAllocations array in the response. Top-level detail field describes the rule violated. Happens before any processor call.
Processing Failures — paymentAllocations are present; check the error object in each failed allocation for processor-level details (errorDetails.code, errorDetails.declineCode).
Rollback — One allocation has status: "ROLLED_BACK" with a remediation.type: "CANCELLATION" object, explaining it was cancelled because another allocation failed.

Sample Response — COMPLETED

{
  "data": {
    "id": "<resource-id>",
    "status": "COMPLETED",
    "amount": 100,
    "merchantTransactionId": "<unique-id>"
  }
}

Sample Response — Business Rule Violation (FAILED, no allocations)

{
  "title": "UNPROCESSABLE_ENTITY",
  "detail": "<business rule violation message>",
  "status": 422,
  "data": {
    "id": "<resource-id>",
    "status": "FAILED",
    "merchantTransactionId": "<unique-id>"
  }
}

Sample Response — Processing Failure (FAILED with error object)

{
  "title": "PAYMENT_ERROR",
  "detail": "<processor error message>",
  "status": 422,
  "data": {
    "id": "<resource-id>",
    "status": "FAILED",
    "paymentAllocations": [
      {
        "id": "<allocation-id>",
        "status": "FAILED",
        "error": {
          "title": "PAYMENT_ERROR",
          "detail": "<error message>",
          "errorDetails": {
            "code": "<processor code>",
            "declineCode": "<decline code>"
          }
        }
      }
    ]
  }
}

Sample Response — Rollback (ROLLED_BACK + remediation)

{
  "title": "PAYMENT_ERROR",
  "detail": "<partial failure message>",
  "status": 422,
  "data": {
    "id": "<resource-id>",
    "status": "FAILED",
    "paymentAllocations": [
      {
        "id": "<allocation-id-1>",
        "status": "ROLLED_BACK",
        "remediation": {
          "type": "CANCELLATION",
          "message": "This paymentAllocation was canceled because another paymentAllocation failed."
        }
      },
      {
        "id": "<allocation-id-2>",
        "status": "FAILED",
        "error": {
          "title": "PAYMENT_ERROR",
          "detail": "<error message>"
        }
      }
    ]
  }
}

5. Status Handling

Purpose: Document how to track transaction status after submission.

Cover these areas:

Polling: Supported identifiers (resourceId, merchantTransactionId), frequency, backoff strategy, when to stop, and which identifiers are not supported for polling
Status definitions: What each status means (PENDING, COMPLETED, FAILED, ROLLED_BACK, etc.)
Parent status computation: How parent status is derived from child/allocation statuses (e.g., "all succeed → COMPLETED; any fail → FAILED")
Status mapping table: All possible parent/child status combinations
Recommended strategy: Webhooks as primary, polling as fallback

Status Mapping Table Pattern

Use emoji-prefixed status labels in the table to aid visual scanning. Always describe what each combination means:

Allocation 1	Allocation 2	Parent Status	Description
⏳ PENDING	⏳ PENDING	⏳ PENDING	Both processing
✅ COMPLETED	✅ COMPLETED	✅ COMPLETED	Transaction fully completed
⏳ PENDING	❌ FAILED	⏳ PENDING	One failed, rollback in progress
🔄 ROLLED_BACK	❌ FAILED	❌ FAILED	Rollback complete — final state
❌ FAILED	❌ FAILED	❌ FAILED	Both failed — final state

Internal Status Combinations <Audience> pattern: Add an <Audience include="internal"> block with a table of all internal database/processor statuses not exposed to merchants. Include a :::important note explaining the internal processing model (e.g., PRE-AUTH + CAPTURE two-phase flow). E.g.:

<Audience include="internal">

#### [Feature] Internal Statuses

:::important
Describe the internal processing model (e.g., PRE-AUTH + CAPTURE). Merchants only see the abstracted statuses: `PENDING`, `COMPLETED`, `FAILED`, etc.
:::

<details open>
<summary><b>All Internal Status Combinations</b></summary>

| Allocation 1 Internal | Allocation 2 Internal | Parent Status | Phase Description              |
| --------------------- | --------------------- | ------------- | ------------------------------ |
| AUTHORIZED            | AUTHORIZED            | PENDING       | Both pre-authorized            |
| CAPTURE_INITIALIZED   | AUTHORIZED            | PENDING       | Capture started on one         |
| COMPLETED             | COMPLETED             | COMPLETED     | Both captured — final          |
| CANCEL_INITIALIZED    | FAILED                | PENDING       | Rollback in progress           |
| CANCELLED             | FAILED                | FAILED        | Rollback complete — final      |
| FAILED                | FAILED                | FAILED        | Both failed — final            |

</details>

</Audience>

Reference implementation: See Split Tender Payments — the Status Handling section shows the full status mapping table and internal statuses block.

6. Webhooks

Purpose: Document webhook events emitted by the feature — when they fire, what they mean, and how to consume them reliably. Webhooks should be the primary mechanism for status updates; polling is the fallback.

What to include:

A :::info admonition linking to the webhook spec operations for each event
Event summary table: event name (linked to spec), when triggered, what it means
A :::caution for any finality caveats (e.g., FAILED event is not final while retries remain)
Internal webhook status mapping in <Audience include="internal"> — all allocation status combinations and which event each triggers

Template:

:::info[Webhook Payload Structure]
- [EVENT_SUCCEEDED](/webhooks-v2/#tag/Payment/operation/onEventSucceeded)
- [EVENT_FAILED](/webhooks-v2/#tag/Payment/operation/onEventFailed)
:::

| Event | When Triggered |
| ----- | -------------- |
| [`EVENT_SUCCEEDED`](/webhooks-v2/#tag/Payment/operation/onEventSucceeded) | All allocations completed |
| [`EVENT_FAILED`](/webhooks-v2/#tag/Payment/operation/onEventFailed) | One or more allocations failed |

:::caution
Describe finality caveats — e.g., `PAYMENT_FAILED` is **not final** if retries remain. It becomes final only after the maximum retry limit is reached or the merchant stops retrying.
:::

Internal Webhook Status Mapping <Audience> pattern:

<Audience include="internal">

### Webhook Status Mapping (Internal)

| Allocation 1 | Allocation 2 | Parent Status | Webhook Event     | Alloc 1 Status | Alloc 2 Status |
| ------------ | ------------ | ------------- | ----------------- | -------------- | -------------- |
| COMPLETED    | COMPLETED    | COMPLETED     | `EVENT_SUCCEEDED` | COMPLETED      | COMPLETED      |
| ROLLED_BACK  | FAILED       | FAILED        | `EVENT_FAILED`    | ROLLED_BACK    | FAILED         |
| FAILED       | FAILED       | FAILED        | `EVENT_FAILED`    | FAILED         | FAILED         |

</Audience>

Reference implementation: See Split Tender Payments — the Webhooks section shows the full event table, caution, best practices, and internal mapping.

7. Error Handling

Purpose: Link to the centralized error code references. Only document use-case-specific error scenarios not covered by the general error codes.

Guidelines:

Do NOT duplicate the error code reference pages
Link to the appropriate error code reference for the feature area
Only include a sample error response if the error is unique to this use case (e.g., split tender rollback behaviour, 3DS failure in agent flows)
Call out failure modes that are unique to the feature (e.g., partial failure → automatic rollback, 3DS not supported in agent sessions)

Error Code References

For contributors: When creating new error code documentation, see the API Error Code Documentation Guidelines.

8. Retry Handling (If Applicable)

Purpose: Document how retry logic works for the feature, including limits, idempotency, and what can/cannot be changed on retry.

Guidelines:

Clearly state when retries are allowed (e.g., only on FAILED status).
Specify the maximum number of retries and how attempts are tracked (e.g., by merchantTransactionId).
Explain idempotency requirements (e.g., same transaction ID for all retries).
Clarify what can be changed on retry (e.g., payment methods, amounts) and what must remain the same.
State what happens after the maximum retries are exhausted.

Example:

When to Retry

Only retry if the parent payment status is FAILED and attempts remain.

How Many Retries Are Allowed

You can retry up to 5 times per merchantTransactionId (1 initial + 4 retries).
The retry counter increments automatically for each attempt with the same merchantTransactionId.

Idempotency & Tracking

All retries must use the same merchantTransactionId for idempotency and tracking.

What Can Be Changed on Retry

Each retry is all-or-nothing — you cannot retry just the failed part; all allocations are retried together.
On each retry, you may change the payment methods and redistribute the amounts between them.
After failure, you may switch to a single-payment flow if desired.

After Max Retries

After the 5th failure, the transaction is cancelled and no further retries are allowed for that merchantTransactionId.

Internal Retry & Rollback Flow <Audience> pattern: Add an <Audience include="internal"> block with a Mermaid sequence diagram showing the full retry flow — failure → rollback → retry:

<Audience include="internal">

### Retry & Rollback Flow

<details>
<summary><b>Retry & Rollback Flow (Internal)</b></summary>

```mermaid
sequenceDiagram
  participant M as Merchant
  participant CCG as CCG Platform
  participant C1 as Card 1
  participant C2 as Card 2

  Note over M,C2: Attempt 1
  M->>CCG: Payment Request
  CCG->>C1: Process Card 1
  C1-->>CCG: ✅ SUCCESS
  CCG->>C2: Process Card 2
  C2-->>CCG: ❌ FAILED

  Note over CCG: Card 2 failed → rollback Card 1
  CCG->>C1: Cancel Card 1 Authorization
  C1-->>CCG: Cancelled
  CCG-->>M: PAYMENT_FAILED (rollback details included)

  Note over M,C2: Attempt 2 (same merchantTransactionId)
  M->>CCG: Payment Request (retry)
  Note over CCG: Attempt counter → 2
  CCG->>C1: Process Card 1
  CCG->>C2: Process Card 2
  C1-->>CCG: ✅ SUCCESS
  C2-->>CCG: ✅ SUCCESS
  CCG-->>M: PAYMENT_SUCCEEDED
```

</details>

</Audience>

Reference implementation: See Split Tender Payments — the Retry Handling section shows the full retry & rollback flow.

9. Version Comparison (If Applicable)

Purpose: Document differences between API versions when a feature exists in both v1 and v2 (or across multiple versions). This helps integrators understand what changed and how to migrate.

When to Include This Section

Only include this section when:

The feature exists in multiple API versions (e.g., v1 and v2)
There are meaningful differences in behavior, request/response structure, or capabilities
Integrators need migration guidance from an older version

Omit this section if the feature only exists in one API version.

What to Include

Choose Your Comparison Format: Depending on the complexity of changes, use one or both approaches:

Inline comparison table — For high-level behavioral differences (recommended for all version comparisons)
Downloadable Excel workbook — For comprehensive field-by-field comparisons across request, response, error, and webhook payloads (recommended when structure changes significantly)

Approach 1: Inline Comparison Table

Use a comparison table to highlight key behavioral and structural differences:

Aspect	v1	v2	Migration Notes
Endpoint	`POST /v1/payments`	`POST /v2/payments`	Update endpoint path
Request Structure	Single payment method only	Supports multiple payment methods	Can now split payments
Status Values	`SUCCESS`, `FAILURE`	`COMPLETED`, `FAILED`, `PENDING`	Update status handling logic
Retry Support	Manual retry required	Built-in retry with tracking	Use same `merchantTransactionId`
Webhook Events	Single event	Granular events per status	Update webhook handlers
Error Response	Generic error codes	Detailed error codes with `declineCode`	Enhanced error handling available

Behavior Changes: Document any breaking changes or new behaviors:

**v2 Improvements:**
- ✅ Native support for [new capability]
- ✅ Enhanced error details with processor-specific codes
- ✅ Automatic rollback on partial failures
- ✅ Idempotent retry handling

**v1 Limitations:**
- ❌ No automatic rollback — manual reversal required
- ❌ Limited error details
- ❌ No retry tracking

Migration Guidance: Provide actionable steps for migrating from v1 to v2:

### Migrating from v1 to v2

1. **Update API endpoint:** Change base path from `/v1/` to `/v2/`
2. **Update request payload:** [Specific field changes needed]
3. **Update status handling:** Map v1 statuses to v2 equivalents
4. **Update error handling:** Handle new error structure with `errorDetails` object
5. **Update webhook handlers:** Support new event types
6. **Test with staging:** Validate all flows in staging before production cutover

**Breaking Changes:**
- Field `X` renamed to `Y`
- Status `Z` split into `A` and `B`
- Error response structure changed — see [Error Codes](/docs/developers/convenient-checkout-api/error-codes/)

Deprecation Notices (If Applicable):

:::warning[v1 Deprecation]
v1 of this API will be deprecated on [DATE]. All integrations should migrate to v2 by [DEADLINE]. See the [v1 to v2 Migration Guide](/docs/developers/migration/) for detailed instructions.
:::

Version-Specific Documentation Links:

**Version-Specific Docs:**
- [v1 API Spec](/api-reference/#tag/Merchant/operation/createPayment-v1)
- [v2 API Spec](/api-reference-v2/#tag/Merchant/operation/createPayment)
- [v1 Documentation](/docs/v1/developers/payments/)
- [v2 Documentation](/docs/developers/convenient-checkout-api/payments/)

Approach 2: Downloadable Excel Workbook (For Comprehensive Comparisons)

When API structure changes significantly (new fields, restructured objects, different error formats), provide a downloadable Excel workbook with side-by-side JSON comparisons.

Workbook Structure:

Create a multi-tab workbook with these sheets:

Tab Name	Content
Request	Side-by-side comparison of request payloads
Response (Success)	Success response with all mandatory and optional fields
Response (Error)	Error responses grouped by HTTP status code (400, 401, 403, 404, 422, 500)
Webhook (Success)	All success-path webhook events
Webhook (Error)	All failure-path webhook events

Badge Convention:

Use color-coded badges to highlight field changes:

Badge	Meaning
🔴 `<REMOVED>`	Field exists in v1 but not in v2
🟢 `<ADDED>`	Field exists in v2 but not in v1
🟡 `<RENAMED>`	Field renamed between versions (optional)
No badge	Field exists in both versions

Excel Format Guidelines:

Place v1 JSON in the left column and v2 JSON in the right column
Use field type placeholders (string, int, boolean, null, array, object) instead of actual values
Highlight removed fields in red, added fields in green
Include all optional fields to show full API surface
Group error responses by HTTP status code for clarity

Documentation Template:

## V1 vs V2 API Comparison

A comprehensive field-by-field comparison workbook is available for teams migrating from v1 to v2.

> **📥 [Feature Name Payload Comparison v1 to v2](pathname:///Downloads/Feature-V1-V2-Payload_Comparison.v1.xlsx)**

The workbook contains the following tabs:

| Tab | What it covers |
|-----|---------------|
| **Request** | `POST /v1/feature` vs `POST /v2/feature` — all fields |
| **Response (Success)** | `200 OK` response with all mandatory and optional fields |
| **Response (Error)** | Error responses grouped by HTTP status: `400`, `401`, `403`, `404`, `422`, `500` |
| **Webhook (Success)** | Success event payloads (e.g., `FEATURE_SUCCESS`, `FEATURE_PARTIAL_SUCCESS`) |
| **Webhook (Error)** | Failure event payloads (e.g., `FEATURE_FAILED`) |

<details>
<summary>**How to read the workbook**</summary>

Each tab shows v1 JSON on the **left** and v2 JSON on the **right**. Field values are shown as type labels (`string`, `int`, `boolean`, `null`) — not actual values.

| Badge | Meaning |
|-------|--------|
| 🔴 `<REMOVED>` | Field exists in v1 but **not** in v2 |
| 🟢 `<ADDED>` | Field exists in v2 but **not** in v1 |
| No badge | Field exists in **both** versions |

**What to look for:**
- 🔴 **Removed fields** — Update your code to stop sending/expecting these
- 🟢 **Added fields** — New capabilities you can leverage
- **Renamed fields** — Look for matching semantics with different names
- **Type changes** — Field may exist in both but with different type (e.g., `string` → `int`)
- **Nested structure changes** — Objects may be flattened or nested differently

</details>

### Key Differences Summary

[Provide a high-level summary table here — same as the inline comparison table approach]

### Migration Guidance

[Migration steps as documented in Approach 1]

Naming Convention:

File name: {Feature}-V1-V2-Payload_Comparison.v{version}.xlsx
Example: Refund-V1-V2-Payload_Comparison.v1.xlsx
Place in: /static/Downloads/ directory
Link format: pathname:///Downloads/filename.xlsx

Reference implementation: See Split Tender Refunds — shows both inline table and downloadable Excel workbook.

10. FAQ

Purpose: Provide concise answers to common integration questions and edge cases.

Guidelines:

Address real-world scenarios, troubleshooting, and best practices.
Use Q&A format for clarity.

Example:

Q: How do I correlate webhook events with my payment records?

Use the parent paymentId or merchantTransactionId provided in both the API response and webhook payload to match events to your records.

Q: What should I do if a payment is stuck in PENDING?

Continue polling the parent transaction. If the status does not resolve after a reasonable time, check for webhook delivery issues or contact support.

Q: Can I retry only the failed card in a split tender payment?

No. All retries must include both allocations; split tender is all-or-nothing.

11. Integration Checklist

Purpose: Help integrators verify all critical steps before go-live.

Guidelines:

List all required setup, configuration, and validation steps.
Use checkboxes for easy tracking.

Example:

Merchant account is configured for the feature
API endpoints and authentication are set up
Request includes all required fields and correct structure
Error handling and remediation logic implemented
Webhook endpoint is configured and tested
Webhook handler is idempotent and logs all payloads
Retry logic follows documented rules (if applicable)
All error codes and business rule violations are handled
Integration tested with test data and simulated failures

Purpose: Provide a curated list of all related docs — use case variants, API specs, error code references, business guides, webhook configuration, and supporting guides.

Guidelines:

Only link docs directly relevant to this feature or common next steps
Always include: the direct API spec operation, the error codes page, and the business use case guide
Group by category if there are many links

Example:

Contributing Guidelines Reference

When creating documentation that accompanies this integration guide, refer to these specialized guidelines:

API Error Code Documentation Guidelines — How to create MDX error code pages and JSON data files
Business Use Case Guidelines — How to document business-level features and use cases

Standard Section Headings​

Sub-heading Standards​

1. Overview​

2. Integration Details​

2.1. Internal Processing Flow​

3. API Request​

4. API Response​

5. Status Handling​

6. Webhooks​

7. Error Handling​

8. Retry Handling (If Applicable)​

When to Retry​

How Many Retries Are Allowed​

Idempotency & Tracking​

What Can Be Changed on Retry​

After Max Retries​

9. Version Comparison (If Applicable)​

What to Include​

Approach 1: Inline Comparison Table​

Approach 2: Downloadable Excel Workbook (For Comprehensive Comparisons)​

10. FAQ​

11. Integration Checklist​

12. Related Documentation​

Contributing Guidelines Reference​

Standard Section Headings

Sub-heading Standards

1. Overview

2. Integration Details

2.1. Internal Processing Flow

3. API Request

4. API Response

5. Status Handling

6. Webhooks

7. Error Handling

8. Retry Handling (If Applicable)

When to Retry

How Many Retries Are Allowed

Idempotency & Tracking

What Can Be Changed on Retry

After Max Retries

9. Version Comparison (If Applicable)

What to Include

Approach 1: Inline Comparison Table

Approach 2: Downloadable Excel Workbook (For Comprehensive Comparisons)

10. FAQ

11. Integration Checklist

12. Related Documentation

Contributing Guidelines Reference