# API Reference Overview

Complete reference for all Prism API services, request/response types, and error handling.

## Overview

Prism provides a unified gRPC API for payment processing across 100+ payment processors. The API is organized into services that handle different aspects of the payment lifecycle.

## Services

| Service                                                                                                             | Description            | Key Operations                                               |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------ |
| [Payment Service](/integrations/prism/api-reference/payment-service.md)                                             | Core payment lifecycle | Authorize, Capture, Void, Refund, CreateOrder                |
| [Refund Service](/integrations/prism/api-reference/refund-service.md)                                               | Refund operations      | Get refund status                                            |
| [Recurring Payment Service](/integrations/prism/api-reference/recurring-payment-service.md)                         | Stored payment methods | Charge, Revoke mandate                                       |
| [Dispute Service](/integrations/prism/api-reference/dispute-service.md)                                             | Chargeback handling    | Accept, Defend, SubmitEvidence                               |
| [Event Service](/integrations/prism/api-reference/event-service.md)                                                 | Webhook processing     | Handle connector events                                      |
| [Customer Service](/integrations/prism/api-reference/customer-service.md)                                           | Customer management    | Create customer                                              |
| [Payment Method Service](/integrations/prism/api-reference/payment-method-service.md)                               | Payment method storage | Tokenize                                                     |
| [Payment Method Authentication Service](/integrations/prism/api-reference/payment-method-authentication-service.md) | 3DS authentication     | Pre-authenticate, Authenticate, Post-authenticate            |
| [Merchant Authentication Service](/integrations/prism/api-reference/merchant-authentication-service.md)             | Session management     | CreateAccessToken, CreateSessionToken, CreateSdkSessionToken |

## Error Object

All API errors return a structured `ErrorInfo` object with detailed information about what went wrong.

### ErrorInfo Fields

| Field               | Type                    | Description                                                      |
| ------------------- | ----------------------- | ---------------------------------------------------------------- |
| `unified_details`   | `UnifiedErrorDetails`   | Machine-readable unified error code and user-facing message      |
| `issuer_details`    | `IssuerErrorDetails`    | Card issuer-specific error information (scheme, network details) |
| `connector_details` | `ConnectorErrorDetails` | Connector-specific error code and message from the PSP           |

### UnifiedErrorDetails Fields

| Field                   | Type     | Description                                              |
| ----------------------- | -------- | -------------------------------------------------------- |
| `code`                  | `string` | Machine-readable error code (e.g., `INSUFFICIENT_FUNDS`) |
| `message`               | `string` | Human-readable error message                             |
| `description`           | `string` | Detailed explanation of the error                        |
| `user_guidance_message` | `string` | User-facing message with guidance on next steps          |

### IssuerErrorDetails Fields

| Field             | Type                  | Description                                                |
| ----------------- | --------------------- | ---------------------------------------------------------- |
| `code`            | `string`              | Card scheme code (e.g., `VISA`, `MASTERCARD`)              |
| `message`         | `string`              | Human-readable message from the issuer                     |
| `network_details` | `NetworkErrorDetails` | Network-specific error details (advice code, decline code) |

### NetworkErrorDetails Fields

| Field           | Type     | Description                         |
| --------------- | -------- | ----------------------------------- |
| `advice_code`   | `string` | Network advice code for retry logic |
| `decline_code`  | `string` | Card scheme decline code            |
| `error_message` | `string` | Network-specific error details      |

### ConnectorErrorDetails Fields

| Field     | Type     | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `code`    | `string` | Connector-specific error code (e.g., Stripe's `card_declined`) |
| `message` | `string` | Human-readable message from the connector                      |
| `reason`  | `string` | Detailed explanation of why the error occurred                 |

### Error Response Example

```json
{
  "error": {
    "unified_details": {
      "code": "INSUFFICIENT_FUNDS",
      "message": "Your card has insufficient funds.",
      "description": "The payment was declined because the card does not have sufficient available credit or balance to complete the transaction.",
      "user_guidance_message": "Please try a different payment method or contact your bank."
    },
    "connector_details": {
      "code": "card_declined",
      "message": "Your card was declined.",
      "reason": "insufficient_funds"
    },
    "issuer_details": {
      "code": "VISA",
      "message": "Decline",
      "network_details": {
        "advice_code": "01",
        "decline_code": "51",
        "error_message": "Insufficient funds"
      }
    }
  }
}
```

## Domain Schema

See [Domain Schema](/integrations/prism/api-reference/domain-schema.md) for complete documentation of all data types, enums, and structures used across the API.

## Proto Files

The API is defined in Protocol Buffer files located at:

* `backend/grpc-api-types/proto/payment.proto` - Core payment types and errors
* `backend/grpc-api-types/proto/sdk_config.proto` - SDK and network error types
* `backend/grpc-api-types/proto/services.proto` - Service definitions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hyperswitch.io/integrations/prism/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.