> ## Documentation Index
> Fetch the complete documentation index at: https://juspay-78-sa-banks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Gateway Score

> Feed a transaction outcome back into the success-rate model. Call this after every transaction so the engine has accurate SR data for future routing decisions.

# Update Gateway Score

## Use case

Records the observed transaction outcome for a previously selected gateway so auth-rate analytics can learn from real payment results.

## Authentication

Protected. Send either `Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>`. In sandbox, also send `x-feature: decision-engine`.

For local development, start with:

```bash theme={null}
export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"
```

## Request

* Method and path: `POST /update-gateway-score`
* Parameters: none.
* Body: JSON body with `merchantId`, `paymentId`, `gateway` and `status`, plus optional `gatewayReferenceId`, `enforceDynamicRoutingFailure`, `txnLatency`, `errorInfo` and `isSmartRetry`.

## Example

### Update gateway score

```bash theme={null}
curl --location "$BASE_URL/update-gateway-score" \
  --header "$AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data '{
  "merchantId": "merchant_demo",
  "paymentId": "pay_sr_001",
  "gateway": "stripe",
  "status": "CHARGED",
  "gatewayReferenceId": "stripe_ref_001",
  "enforceDynamicRoutingFailure": false,
  "txnLatency": { "gatewayLatency": 120.5 }
}'
```

`status` must be a transaction status value - `CHARGED`, `AUTHORIZATION_FAILED`,
`AUTHENTICATION_FAILED`, `JUSPAY_DECLINED`, `FAILURE`, and so on. Lowercase values such as
`success` are rejected with a 400.

Payment attributes (amount, currency, payment method, auth type) are **not** part of this
payload - the engine already has them from the `/decide-gateway` call for this `paymentId`.
Any unrecognised field is silently ignored, so a misspelled key fails quietly rather than
erroring. Note in particular that latency goes in `txnLatency.gatewayLatency`, not `latency`.

## Response

```json theme={null}
{
  "message": "Gateway score updated successfully",
  "merchant_id": "merchant_demo",
  "gateway": "stripe",
  "payment_id": "pay_sr_001"
}
```

When `errorInfo` is supplied in the request and matches a gateway status map rule, the response
also carries a `gsm_info` object describing the lookup result.

## Notes

* Do not call this after `NTW_BASED_ROUTING` just to record the selected debit network; debit audit comes from `/decide-gateway` analytics.
* Call it after payment authorization completes, not before.

## Related

* [Decide Gateway](/decision-engine-api-reference/api-reference/endpoint/gateway-decision/decideGateway)
* [Analytics Gateway Scores](/decision-engine-api-reference/api-reference/endpoint/analytics/analyticsGatewayScores)
* [Update Gateway Score](/decision-engine-api-reference/api-reference/guides/feedback-scoring/update-gateway-score)


## OpenAPI

````yaml decision_engine_openapi-specs.json POST /update-gateway-score
openapi: 3.1.0
info:
  title: Decision Engine
  description: >-
    Open-source payment gateway routing service by Juspay. Selects the optimal
    payment processor for each transaction in real-time using success-rate
    scoring, rule-based routing, and elimination logic.


    ## Authentication


    This API supports two authentication methods:


    1. **JWT Bearer Token** - For dashboard/user sessions
       - Header: `Authorization: Bearer <jwt_token>`
       - Obtain via `/auth/login` endpoint

    2. **API Key** - For service-to-service/programmatic access
       - Header: `x-api-key: DE_<64_char_hex>`
       - Create via `/api-key/create` endpoint

    Protected endpoints require one of these authentication methods.
  version: 1.4.0
  contact:
    name: Juspay
    url: https://github.com/juspay/decision-engine
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://sandbox.hyperswitch.io
    description: 'Hyperswitch sandbox with x-feature: decision-engine'
security: []
tags:
  - name: Health
    description: Service liveness, readiness, and diagnostics
  - name: Auth
    description: Dashboard auth and merchant selection
  - name: API Keys
    description: Service-to-service API key management
  - name: Gateway Decision
    description: Core routing decision APIs
  - name: Score Feedback
    description: Feed transaction outcomes back to improve SR scoring
  - name: Merchant Account
    description: Merchant configuration management
  - name: Routing Rules
    description: Euclid declarative routing rules engine
  - name: Rule Configuration
    description: Service-level SR/elimination config
  - name: Config
    description: Routing key and dimension metadata
  - name: Analytics
    description: ClickHouse-backed analytics and audit reads
  - name: Compatibility
    description: Legacy compatibility routes
  - name: Connector Costs
  - name: Merchant Features
  - name: Autopilot
paths:
  /update-gateway-score:
    post:
      tags:
        - Score Feedback
      summary: Update gateway score
      description: >-
        Feed a transaction outcome back into the success-rate model. Call this
        after every transaction so the engine has accurate SR data for future
        routing decisions.


        A `CHARGED` status increases the gateway's SR; failure statuses
        (`AUTHENTICATION_FAILED`, `AUTHORIZATION_FAILED`, etc.) decrease it.
      operationId: updateGatewayScore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGatewayScoreRequest'
            example:
              merchantId: test_merchant
              gateway: stripe
              paymentId: pay_001
              status: CHARGED
              gatewayReferenceId: stripe_ref_001
              enforceDynamicRoutingFailure: false
      responses:
        '200':
          description: Score updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScoreResponse'
              example:
                message: Score updated
                merchant_id: test_merchant
                gateway: stripe
                payment_id: pay_001
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
components:
  schemas:
    UpdateGatewayScoreRequest:
      type: object
      required:
        - merchantId
        - gateway
        - paymentId
        - status
      properties:
        merchantId:
          type: string
          example: test_merchant
        gateway:
          type: string
          example: stripe
        paymentId:
          type: string
          example: pay_001
        status:
          type: string
          enum:
            - STARTED
            - AUTHENTICATION_FAILED
            - JUSPAY_DECLINED
            - PENDING_VBV
            - VBV_SUCCESSFUL
            - AUTHORIZED
            - AUTHORIZATION_FAILED
            - CHARGED
            - AUTHORIZING
            - COD_INITIATED
            - VOIDED
            - VOID_INITIATED
            - NOP
            - CAPTURE_INITIATED
            - CAPTURE_FAILED
            - VOID_FAILED
            - AUTO_REFUNDED
            - PARTIAL_CHARGED
            - TO_BE_CHARGED
            - PENDING
            - FAILURE
            - DECLINED
          example: CHARGED
          description: >-
            Transaction status. Must be a TxnStatus value - lowercase values
            such as `success` are rejected with a 400.
        gatewayReferenceId:
          type: string
          example: stripe_ref_001
        enforceDynamicRoutingFailure:
          type: boolean
          default: false
        txnLatency:
          type:
            - object
            - 'null'
          properties:
            gatewayLatency:
              type:
                - number
                - 'null'
              format: double
              example: 120.5
          description: Observed gateway latency, in milliseconds.
        errorInfo:
          type:
            - object
            - 'null'
          description: >-
            Gateway error details for the GSM-based scoring filter. When present
            and the merchant flag is on, user/issuer-originated failures are
            skipped so the gateway is not penalised.
        isSmartRetry:
          type:
            - boolean
            - 'null'
          description: Set by the orchestrator when this call is a smart-retry attempt.
    UpdateScoreResponse:
      type: object
      properties:
        message:
          type: string
        merchant_id:
          type: string
        gateway:
          type: string
        payment_id:
          type: string
        gsm_info:
          type:
            - object
            - 'null'
          description: >-
            GSM lookup result. Present only when `errorInfo` was supplied and a
            matching rule was found.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key created via /api-key/create

````