This document describes the custom API endpoints provided by the CyberSource Plugin for Shopware 6. These endpoints allow authorized users to retrieve CyberSource transaction details, capture authorized payments, and perform refunds for orders.

Endpoint
GET /api/cybersource/order/{orderId}

Description
Retrieves CyberSource transaction details for the given Shopware Order ID.

Request Headers

Authorization: Bearer <your-access-token>  
Content-Type: application/json

Example Request

GET /api/cybersource/order/5b6a139e54e54ed7b7997c71f6f56f9e

Successful Response

{
  "cybersource_transaction_id": "CSTXN123456789",
  "payment_status": "paid",
  "amount": 100.00,
  "updated": false,
  "cybersource_status": "SETTLED"
}

Example Error Response

{
  "error": "No CyberSource transaction ID found"
}

Endpoint
POST /api/cybersource/order/{orderId}/capture/{cybersourceTransactionId}

Description
Captures a previously authorized CyberSource transaction for the specified order.

Request Headers

Authorization: Bearer <your-access-token>  
Content-Type: application/json

Example Request

POST /api/cybersource/order/5b6a139e54e54ed7b7997c71f6f56f9e/capture/CSTXN123456789

Successful Response

{
  "status": "CAPTURED",
  "transactionId": "CSTXN123456789"
}

Example Error Response

{
  "error": "Order not found"
}

Endpoint
POST /api/cybersource/order/{orderId}/refund/{cybersourceTransactionId}

Description
Processes a refund (full or partial) for a captured CyberSource payment.

Request Headers

Authorization: Bearer <your-access-token>  
Content-Type: application/json

Example Request Body

{
  "newTotalAmount": 50.00,
  "lineItems": [
    {
      "productId": "d840cfdbd1184cf98993f6761d231d94",
      "quantity": 1
    }
  ]
}

Successful Response

{
  "status": "REFUNDED",
  "transactionId": "CSTXN123456789"
}

Example Error Response

{
  "error": "Order refund amount is not valid."
}

Endpoint
GET /cybersource/capture-context

Description
Retrieves a capture context used to tokenize card data via CyberSource Microform.

Request Headers

Accept: application/json

Successful Response

{
  "captureContext": "eyJhbGciOiJIUzI1..."
}

Example Error Response

{
  "error": "Runtime error message"
}

Endpoint
POST /cybersource/authorize-payment

Description
Initiates payment authorization with CyberSource.

Request Headers

Content-Type: application/json

Example Request Body

{
  "token": "<token>",
  "subscriptionId": "<saved-card-id>",
  "saveCard": true,
  "expirationMonth": "07",
  "expirationYear": "2026",
  "orderId": "<order-id>",
  "billingAddress": { ... }
}

Successful Response

{
  "success": true,
  "action": "setup",
  "uniqid": "unique_id",
  "consumerAuthenticationInformation": { ... }
}

Example Error Response

{
  "error": "Authentication setup failed",
  "message": "Error details"
}

Endpoint
POST /cybersource/proceed-authentication

Description
Completes the 3DS authentication process and performs the payment.

Request Headers

Content-Type: application/json

Example Request Body

{
  "token": "<token>",
  "subscriptionId": "<saved-card-id>",
  "expirationMonth": "07",
  "expirationYear": "2026",
  "saveCard": true,
  "uniqid": "unique_id",
  "setupResponse": { ... },
  "callbackData": { ... },
  "billingAddress": { ... }
}

Successful Response

{
  "success": true,
  "action": "3ds",
  "authenticationTransactionId": "<id>",
  "acsUrl": "https://...",
  "stepUpUrl": "https://...",
  "pareq": "...",
  "accessToken": "...",
  "uniqid": "..."
}

Example Error Response

{
  "error": "Payer authentication failed",
  "message": "Error details"
}

Endpoint
GET /cybersource/get-saved-cards

Description
Returns a list of saved cards for the logged-in customer.

Request Headers

Accept: application/json

Successful Response

{
  "cards": [
    {
      "id": "string",
      "cardNumber": "string",
      "expirationMonth": "string",
      "expirationYear": "string",
      "type": "string",
      "billingAddress": { ... },
      "customerId": "string",
      "default": true,
      "state": "string"
    }
  ]
}

Example Error Response

{
  "cards": []
}

Endpoint
POST /account/cybersource/add-card

Description
Adds a new card to the customer’s CyberSource profile.

Request Headers

Content-Type: application/json

Example Request Body

{
  "token": "<token>",
  "expirationMonth": "MM",
  "expirationYear": "YYYY",
  "billingAddress": { ... }
}

Successful Response

{
  "success": true,
  "message": "Card successfully added"
}

Example Error Response

{
  "message": "Missing token, expirationMonth, or expirationYear"
}

Endpoint
POST /account/cybersource/delete-card

Description
Deletes a saved card from the customer’s CyberSource profile.

Request Headers

Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "instrumentId": "string",
  "customerId": "string"
}

Successful Response

{
  "success": true
}

Example Error Response

{
  "error": "Card not found"
}

Endpoint
GET /cybersource/webhook/health

Description
Simple health check endpoint to confirm that the webhook receiver is reachable by CyberSource.

Successful Response

{
  "status": "healthy"
}

Example Error Response

{
  "error": "Health check failed"
}

Endpoint
POST /cybersource/webhook

Description
Main webhook receiver for CyberSource event notifications. Verifies signature and processes the event to update order transaction states accordingly.

Example Request Body

{
  "eventType": "payments.captures.accept",
  "payloads": {
    "testPayload": {
      "transactionId": "string"
    }
  }
}

Successful Response

{
  "status": "success"
}

Example Error Response

{
  "status": "error",
  "message": "Invalid signature"
}

Admin API endpoints require a valid Admin API Bearer token. You can obtain this via the standard Shopware Admin API authentication process.