RIriskified
Pre-Authorization Flow

Failed Payment Authorization

Changed on

The /checkout_denied endpoint is used to inform Riskified that the payment gateway declined the payment authorization. The gateway’s authorization error message and error code are passed to Riskified. When this endpoint is called, Riskified does not review the order or provide a decision.

Implementing this endpoint improves decision accuracy, helps prevent fraud rings and account takeover attacks, and enables Riskified to identify risky carding behavior. Without it, Riskified will not be aware of gateway-declined transactions. By sharing the reason for the decline, merchants enable Riskified to track failed authorization attempts and more effectively analyze subsequent successful orders.

This endpoint can be used in either pre-authorization or post-authorization integrations to report failed authorization events, and it can be called multiple times for the same order ID.

By reporting checkout denials, you give Riskified full visibility into the complete order flow — from failed payment attempts through successful order submissions — allowing for more accurate fraud analysis and model performance.

post/api/checkout_denied

Request

  • Base URL
    https://sandbox.riskified.com
  • URL
    https://sandbox.riskified.com/api/checkout_denied
  • Auth
    none declared. Required headers: x-riskified-shop-domain, x-riskified-hmac-sha256, Content-Type, accept

Headers

x-riskified-shop-domainstring required
Example:merchant.example.com

The merchant shop domain registered with Riskified.

x-riskified-hmac-sha256string required
Example:b1946ac92492d2347c6235b4d2611184

Verification hash for the Request. Generated by performing an SHA256 encryption on the request's POST body and calculating the HMAC hash of the result using your Riskified authentication token. Please use UTF8 encoding.

Content-Type'application/json' required

As payloads are sent to Riskified in JSON format, value should be: application/json

accept'application/vnd.riskified.com; version=2' required

Specify the version of the API to target. For example, to target the latest version of the API, use the following: application/vnd.riskified.com; version=2

Request body

Example request

{
  "checkout": {
    "id": "450789469",
    "payment_details": [
      {
        "payment_type": "card",
        "credit_card_bin": "482932",
        "avs_result_code": "N",
        "cvv_result_code": "N",
        "credit_card_company": "Visa",
        "credit_card_number": "9876",
        "authorization_id": "FAILED_AUTH_1122",
        "initial_payment_amount": 400,
        "authorization_error": {
          "created_at": "2025-11-19T10:30:00Z",
          "error_code": "CARD_DECLINED_HIGH_RISK",
          "message": "card_declined",
          "drop_off": true
        }
      }
    ]
  }
}

Response

Successful operation

Example response

{
  "checkout": {
    "id": "53953819"
  }
}

Changes

  • 4b9133c61e7fRevision changes
    • breaking

      added the new required header request parameter Content-Type

    • breaking

      removed from the // request property anyOf list

    • warning

      deleted the header request parameter content_type

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      api tag Pre-Authorization Flow added

    • info

      api tag Post-Authorization Flow removed

    • info

      added to the // request property anyOf list

    • info

      added the new ach enum value to the request property /////

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status