Overview

This section provides annotated request and response examples for Credit Card payments, covering the most common operational scenarios:

• One-off payments (PURS)
• Two-step payments (AUTH → CAPTURE)
• 3D Secure (3DS) considerations
• Tokenization and subsequent usage

The objective is to provide a clear, implementation-level understanding of how Credit Card transactions are executed and interpreted, focusing strictly on payload construction and response handling.

Scope and Context

This section focuses on payload-level behavior for Credit Card transactions.

For:

• End-to-end flow sequencing → see F.1 – End-to-End Integration Examples
• Payment flow definitions → see D. Payment Methods
• Status and error semantics → see C. Meta Information, Codes and Transaction States

1. Checkout Creation (CARD Enabled)

Request

POST <ROOT_URL>/payments

{
    "merchant": {
        "terminalId": "11111",
        "channel": "web",
        "merchantTransactionId": "CARD-PURS-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-16T10:15:30.000Z",
        "description": "Card payment",
        "paymentType": "PURS",
        "paymentMethod": [
            "CARD"
        ],
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        }
    }
}

This operation uses Bearer authentication.

Key Annotations

• paymentMethod = ["CARD"]
→ Restricts the checkout to card payments only
• paymentType = "PURS"
  → Indicates immediate execution (one-off payment)
• merchantTransactionId
  → Must be unique per transaction attempt

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "transactionID": "tx123456789",
    "merchant": {
        "merchantTransactionId": "CARD-PURS-0001"
    },
    "paymentMethodList": [
        "CARD"
    ]
}

Interpretation

• statusCode = "000"
  → Confirms successful request processing only
• transactionID
  → Must be persisted for subsequent operations

2. Card Payment Execution (Server-to-Server)

Request

POST <ROOT_URL>/payments/{transactionID}/card/purchase

Request Headers

Authorization: Digest <transactionSignature>
X-IBM-Client-ID: <ClientId>
Content-Type: application/json
Accept: application/json

Request Body

{
    "cardInfo": {
        "PAN": "4111111111111111",
        "secureCode": "123",
        "validationDate": "2028-12-31T00:00:00.000Z",
        "cardholderName": "JOHN DOE"
    }
}

This operation requires Digest authentication using the transaction signature returned during the checkout step.

The Digest signature is associated with the transaction context created during the checkout initialization process.

Key Annotations

• PAN, secureCode, validationDate
  → Raw card data (only allowed in PCI-compliant environments)
• cardholderName
  → Required depending on acquirer configuration

In Server-to-Server integrations, the merchant is responsible for PCI DSS compliance requirements associated with the handling, transmission, and protection of cardholder data.

Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "tx123456789",
    "amount": {
        "value": 49.90,
        "currency": "EUR"
    }
}

Interpretation

• paymentStatus = "Success"
  → Payment completed successfully
• If 3DS is required:
  • Response may indicate Pending or another non-final state
  • Completion occurs after user authentication

This paymentStatus value must always be interpreted alongside webhook notifications and the Status endpoint when asynchronous flows (e.g., 3DS) are involved.

Depending on the acquirer, authentication model, and transaction lifecycle timing, additional validation or asynchronous confirmation steps may still occur.

3. 3D Secure (3DS) Considerations

Behavior

• Some transactions require Strong Customer Authentication (SCA)
• The flow becomes asynchronous

Typical Indicators

• paymentStatus = "Pending" or another non-final state
• Additional steps required:
  • Redirection (Form Integration)
  • 3DS challenge

Important

• Final state may be determined via:
  • Webhook
  • Status endpoint
• The initial response does not represent final state when 3DS is triggered.

The final transaction state may be determined from webhook notifications or using the Status endpoint when required.

When discrepancies exist between intermediate responses and asynchronous updates, the latest transaction state should be checked using the Status endpoint.

Additional transaction monitoring, webhook processing, and status validation guidance is available in E. Notifications and Transaction Status.

4. Two-Step Flow (AUTH → CAPTURE)

Authorization Request

{
    "merchant": {
        "terminalId": "11111",
        "channel": "web",
        "merchantTransactionId": "CARD-AUTH-0001"
    },
    "transaction": {
        "transactionTimestamp": "2026-04-16T10:15:30.000Z",
        "paymentType": "AUTH",
        "paymentMethod": [
            "CARD"
        ],
        "amount": {
            "value": 49.90,
            "currency": "EUR"
        }
    }
}

Authorization Response (Annotated)

{
    "returnStatus": {
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "transactionID": "tx123456789"
}

Key Point

• Funds are reserved but not captured

Capture Request

POST <ROOT_URL>/payments/{transactionID}/capture

This operation finalizes the financial capture of a previously authorized transaction.

Important

• Capture must occur:
  • Within allowed timeframe
  • Using the same transactionID

5. Tokenization (Optional)

Token Generation (Zero-Amount AUTH)

POST <ROOT_URL>/payments

{
    "transaction": {
        "paymentType": "AUTH",
        "paymentMethod": [
            "CARD"
        ],
        "amount": {
            "value": 0.00,
            "currency": "EUR"
        }
    }
}

Important:

• A zero-amount AUTH is used to:
  • Validate the card
  • Generate a reusable token
• No funds are reserved or captured
• The tokenization context is established during the authorization flow and may subsequently be referenced in Merchant Initiated Transaction (MIT) operations.
• Subsequent MIT operations must preserve the relationship between the original transaction context, tokenized credential, and merchant authorization framework.

Response (Token)

{
    "paymentStatus": "Success",
    "token": {
        "tokenType": "Card",
        "value": "TKN123456789"
    }
}

Usage

• Token can be used for:
  • Subsequent payments
  • Merchant Initiated Transactions (MIT)

Common Pitfalls

1. Misinterpreting returnStatus

• "000" does not mean payment success

2. Ignoring 3DS asynchronous behavior

• Assuming immediate completion

3. Using incorrect paymentType

• PURS vs AUTH mismatch

4. Not handling Pending states

• Leads to incorrect order status

5. PCI non-compliance (Server-to-Server)

• Handling raw card data without proper certification

Key Takeaways

• Credit Card flows may be:
  • Synchronous (no 3DS)
  • Asynchronous (3DS required)
• paymentStatus must always be interpreted alongside:
  • Webhooks
  • Status endpoint
• AUTH and PURS define fundamentally different processing models
• Tokenization enables:
  • Recurring payments
  • Potential reduction of PCI exposure when combined with compliant tokenization and payment credential handling practices

This section provides the reference foundation for implementing and troubleshooting Credit Card integrations in SPG.

The Inquiry Details API may return extended card-related data that is not present in the standard Status Inquiry response, including tokenization information such as masked PAN values, token identifiers, and expiry metadata.

For extended transaction data retrieval and full payload structure, refer to F.2.8 – Inquiry Details – Annotated Request and Response.