v1
latestOpenAPI 3.0.02026-07-2417129274.8 KBFailed Payment Authorization
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.
Headers
The merchant shop domain registered with Riskified.
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.
As payloads are sent to Riskified in JSON format, value should be: application/json
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": "123456",
"email": "guest.customer@example.com",
"created_at": "2022-02-20T15:09:00Z",
"currency": "USD",
"gateway": "authorize_net",
"browser_ip": "183.34.15.26",
"total_price": 410,
"total_discounts": 10,
"referring_site": "https://www.google.com/search?q=my+store",
"source": "desktop_web",
"cart_token": "dsh1298sdfvjn123487",
"name": "#1001-C",
"checkout_id": "chkt_e8g4h6k2",
"updated_at": "2022-02-20T15:09:00Z",
"note": "Payment attempt failed at final checkout step.",
"vendor_id": "VNDR7890",
"vendor_name": "Vendor",
"order_type": "test",
"submission_reason": "rule_decision",
"line_items": [
{
"price": 100,
"quantity": 2,
"title": "Large Logo Belted Satchel",
"product_id": "30F1G9HS7B",
"category": "Women",
"brand": "Amazon",
"product_type": "physical",
"requires_shipping": true,
"sku": "dfn239mndf9",
"sub_category": "Handbags",
"delivered_to": "shipping_address"
}
],
"shipping_lines": [
{
"price": 15,
"title": "Express 2-Day Shipping",
"code": "EXPRESS",
"company": "DHL Express"
}
],
"payment_details": [
{
"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,
"payment_frequency": 1,
"authorization_error": {
"created_at": "2025-11-20T10:30:00Z",
"error_code": "CARD_DECLINED_HIGH_RISK",
"message": "card_declined",
"drop_off": true
}
}
],
"customer": {
"email": "guest.customer@example.com",
"first_name": "John",
"last_name": "Test",
"created_at": "2025-11-20T10:00:00Z",
"phone": "+143873984567290",
"account_type": "guest"
},
"billing_address": [
{
"first_name": "John",
"last_name": "Test",
"address1": "123 Smart St",
"country": "United States",
"country_code": "US",
"phone": "+143873984567290",
"city": "Los Angeles",
"zip": "90210",
"province": "California"
}
],
"shipping_address": [
{
"first_name": "John",
"last_name": "Test",
"address1": "123 Smart St",
"country": "United States",
"country_code": "US",
"phone": "+143873984567290",
"city": "Los Angeles",
"zip": "90210",
"province": "California"
}
],
"client_details": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36",
"accept_language": "en-US,en;q=0.9,he-IL;q=0.8"
},
"discount_codes": [
{
"amount": 10,
"code": "TENOFF"
}
],
"charge_free_payment_details": [
{
"amount": 50,
"gateway": "store_credit"
}
],
"passengers": [
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-01",
"nationality_code": "US",
"passenger_type": "Adult"
}
],
"decision": {
"external_status": "declined_business",
"decided_at": "2025-11-20T15:10:00Z",
"reason": "Payment gateway denial triggered order decline.",
"amount": 410,
"currency": "USD"
}
}
}Response
Successful operation
Example response
{
"checkout": {
"id": "53953819"
}
}