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>/api/v2/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"
        }
    }
}

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>/api/v2/payments/{transactionID}/card/purchase

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

Request Headers

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

Key Annotations

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

Important:

• This request typically uses:
  • Authorization: Digest <transactionSignature>
  • Content-Type: application/json
  • Accept: application/json

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 / InProcessing
  • Completion occurs after user authentication

3. 3D Secure (3DS) Considerations

Behavior

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

Typical Indicators

• paymentStatus = "Pending" or "InProcessing"
• Additional steps required:
  • Redirection (Form Integration)
  • 3DS challenge

Important

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

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>/api/v2/payments/{transactionID}/capture

Important

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

5. Tokenization (Optional)

Token Generation (Zero-Amount AUTH)

{
    "transaction": {
        "paymentType": "AUTH",
        "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

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
  • Reduced PCI scope (when used correctly)

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