--- title: "Chargeback" method: POST path: "/api/chargeback" tags: ["Automation Endpoints"] --- # Chargeback `POST /api/chargeback` Notifies Riskified that a chargeback has been submitted for a specific order. Note: Riskified offers fully automated chargeback gateway integrations for major gateways: Braintree, Stripe, Adyen, PayPal; this process automates end-to-end chargeback handling from chargeback reporting to the disputing process. Riskified stands behind its chargeback guarantee for all approved orders. ## Headers - `x-riskified-shop-domain` string, required - `x-riskified-hmac-sha256` string, required - `content_type` 'application/json', required - `accept` 'application/vnd.riskified.com; version=2', required ## Request body - ChargebackOrderWrapper - `order` ChargebackOrder, required - `id` string, required — Order ID - `chargeback_details` ChargebackDetails, required - `chargeback_at` string, date-time, required — The chargeback date (ISO8601), as received from the acquirer. - `chargeback_currency` string, required — The chargeback currency, ISO 4217 - `chargeback_amount` number, float, required — The chargeback amount as stated in the chargeback notice, specified as a positive number. For partial chargeback reimbursement, specify the amount lost, no the amount reimbursed. - `reason_code` string, required — The chargeback reason code, as received from the acquirer - `type` 'rfi' | 'cb' | 'tc40', required — The chargeback transaction type, as received from the acquirer: * rfi Request for Information. * cb Notification of Chargeback. * tc40 Card Network Fraud Alert (including SAFE and equivalents) - `gateway` string, required — The payment gateway who processed the order - `id` string, required — The chargeback unique identifier as received from the gateway/acquirer on the chargeback's notice - `reason_description` string — The chargeback reason description, as received from the acquirer - `mid` string — The merchant account id at the payment gateway. - `arn` string — Acquirer Reference Number (ARN) A unique number that tags a credit card transaction when it goes from the merchant's bank (the acquiring bank) through the card scheme to the cardholder's bank (the issuer). - `credit_card_company` string — Credit card brand: VISA, Mastercard, AMEX, JCB, etc. - `respond_by` string, date-time — Last date (ISO8601)to challenge CHB. - `card_issuer` string — The card issuer. - `fee_amount` number, float — The chargeback fee amount. - `fee_currency` string — The chargeback fee currency. - `cardholder` string — The identifier of the person who submitted the CHB, as it appears on the chargeback notice. - `message` string — Optional issuer message. - `transaction_id` string — Unique identifier generated by the payment processor to the original payment transaction/settlement. - `credit_card_bin` string — The issuer identification number (IIN), formerly known as bank identification number (BIN) of the customer's credit card. Made up of the first 6 or 8 digits of the credit card number (per value received from the Payment Service Providers/tokenization response). - `credit_card_last_four_digits` string — The last 4 digits of the card number. - `transaction_store_id` string — Identifier of the store, brand, or business entity associated with the transaction. Primarily relevant for merchants operating multiple stores, brands, or business entities, such as omnichannel merchants. - `transaction_point_of_sale` string — Point of Sale (POS) identifier associated with the transaction. Primarily relevant for merchants operating physical retail locations where transactions are processed through specific POS systems or terminals. - `transaction_cash_register_number` string — Identifier of the specific cash register or POS terminal where the transaction was processed. Primarily relevant for physical retail environments with multiple registers or checkout terminals. - `fulfillment` FulfillmentDetails - `fulfillment_id` string, required — Unique identifier of this fulfillment attempt. - `created_at` string, date-time, required — When (ISO8601) the order was fulfilled. - `status` 'success' | 'cancelled' | 'error' | 'failure' — The fulfillment status. - `line_items` LineItem[] — A list of each line item in the attempted fulfillment. - union - PhysicalLineItem — A line item that is a physical product. This is the default type of line item. - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'physical', required — The product type should contain one the following value: physical. - `requires_shipping` boolean, required — States whether or not the item requires shipping. This field is important for merchants dealing with digital goods. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - DigitalLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'digital', required — The product type should contain the following value: digital - `requires_shipping` boolean, required — Should be `false` for digital items. States whether or not the item requires shipping. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `sender_name` string — The sender name. - `photo_uploaded` boolean — Indicating whether a photo was uploaded. - `photo_url` string — The photo url (if uploaded). - `message` string — The card's message. - `display_name` string — The display name. - `greeting_photo_url` string — The greeting photo url (if exists). - `greeting_message` string — The greeting message. - `card_type` string — The card's type. - `recipient` Recipient, required - … - TravelLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'travel', required — The product type should contain the following value: travel. - `requires_shipping` boolean, required — Should be `false` for travel items that don't require shipping. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `leg_id` string, required — The current leg id.For flight tickets, flight number (e.g. '101').For bus tickets, bus number (e.g: 'A7'). - `departure_city` string, required — The name of the city of departure for the current leg. - `departure_country_code` string, required — The 2 letter country code (ISO 3166-1 alpha-2) for the departure country of the current leg. - `arrival_city` string, required — The name of the city of arrival for the current leg. - `arrival_country_code` string, required — The 2 letter country code (ISO 3166-1 alpha-2) for the arrival country of the current leg. - `departure_date` string, date-time, required — Date and time of departure for the current leg. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T20:55:00+2:00 - `carrier_code` string — A publicly agreed code describing the carrier/company conducting the current leg. For Flights: The IATA 2 letter carrier code. - `route_index` integer, required — A running index (starts with 1), describing the order of routes by time. Each route_index and leg_index combination constitutes an individual line item. The two (2) route example below requires four (4) line items. E.g: If an order contains 2 Routes: New-York->London->Paris (connection in London) New-York->London should have route_index=1, leg_index=1 London->Paris should have route_index=1, leg_index=2 Paris->London->New-York Paris->London should have route_index=2, leg_index=1 London->New-York should have route_index=2, leg_index=2 - `leg_index` integer, required — A running index (starts with 1), describing the order of legs in the same route. For more details, see route_index field. - `transport_method` 'plane' | 'ship' | 'bus' | 'train' | 'tram', required — The method of transportation. - `departure_port_code` string — Departure port code for the current leg. For flights: the 3 letter IATA airport code. - `arrival_port_code` string — Arrival port code for the current leg. For flights: the 3 letter IATA airport code. - `arrival_date` string, date-time — **(Conditional Requirement)** Required for Flights. Date and time of arrival for the current leg. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T20:55:00+2:00 - `carrier_name` string — The name of the carrier/company conducting the current leg. - `ticket_class` string — The class for this leg's ticket (e.g. business, economy, first). - RidesLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'ride', required — The product type should contain the following value: ride. - `requires_shipping` boolean, required — Should be `false` for digital items. States whether or not the item requires shipping. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `pickup_date` string, date-time, required — Ride pickup date. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T14:55:00+2:00 - `route_index` integer, required — A running index (starts with 1), describing the order of routes by time. E.g: A return trip will be represented in two line_items, the onward trip line_item will be assigned with route_index = 1, the return trip line_item with route_index = 2. - `leg_index` integer, required — A running index (starts with 1), describing the order of legs in the same route. E.g: Will always equal 1, unless the rider needs to change a vehicle within a route. - `pickup_latitude` number, float — The latitude part of the pickup location coordinates. - `pickup_longitude` number, float — The longitude part of the pickup location coordinates. - `pickup_address` Address[] — Pickup location address. - … - `dropoff_date` string, date-time — Ride dropoff date. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T14:55:00+2:00 - `dropoff_latitude` number, float — The latitude part of the dropoff location coordinates. - `dropoff_longitude` number, float — The longitude part of the dropoff location coordinates. - `dropoff_address` Address[] — Dropoff location address. - … - `transport_method` 'taxi' | 'car' | 'rv' | 'bus' | 'plane' | 'ship' | 'train' | 'tram' | 'cruise' — The transport method used, such as: taxi, car, rv, bus, plane, ship, train, tram, cruise - `price_by` string — Pricing method: meter/fixed. - `vehicle_class` string — Vehicle class, such as: economy, executive, van, etc. - `carrier_name` string — Ride/taxi company name. - `driver_id` string — Driver ID/vehicle number (if self driven). - `tariff` string — Relevant tariff for the ride, such as: regular, night, 2, etc. - `note_to_driver` string — Additional message to driver. - `meet_n_greet` string — Airport/pickup meet and greet message. - `cancellation_policy` string — Reservation cancellation policy. - `authorized_payment` number, float — Authorized pre-payment value for this ride (order currency). - `damage_excess` number, float — Amount the customer is liable for in case of damage to the vehicle. - EventsLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'event', required — The product type should contain the following value: event - `requires_shipping` boolean, required — Should be equal to `false` for the digital items that don't require shipping. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `event_date` string, date-time, required — The date and time (ISO8601) of the event. - `city` string, required — The city where the event will take place in. - `country_code` string, required — The 2 letter country code (ISO 3166-1 alpha-2) of the country where the event takes place. - `section` string — The assigned seating section in the venue. - `latitude` number, float — The latitude part of the coordinates of the event location. - `longitude` number, float — The longitude part of the coordinates of the event location. - AccommodationLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'accommodation', required — The product type should contain the following value: ccommodation - `requires_shipping` boolean, required — Should be `false` for the items that don't require shipping. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `check_in_date` string, date-time, required — The room check-in date (ISO8601). - `city` string, required — The accommodation city. - `country_code` string, required — The 2 letter country code (ISO 3166-1 alpha-2) of the country where the accommodation is located. - `check_out_date` string, date-time — The room check-out date. - `accommodation_type` string — The accommodation type, such as hotel, B&B, etc. - `room_type` string — The room type, such as single, double, suite, etc. - `number_of_guests` integer — The number of guests expected in the room. - `rating` string — The accommodation rating, as published on the merchant's website. - `cancellation_policy` string, required — The booking cancellation policy. - RemittanceLineItem - `price` number, float, required — The price of the remittance line item. - `quantity` 1, required — Quantity must always be 1 for remittance line items. - `title` string, required — Describes the remittance type (e.g., ACH Transfer, Cash Transfer, Bank Deposit, Cash at Agent, Mobile wallet). - `category` string, required — The category of the item: ACH, Wallet Deposit, etc. - `product_type` 'remittance', required — Specifies that this line item is a remittance type. - `product_id` string, required — The id of the item. Limited to 256 characters - `requires_shipping` true, required — Always true for remittance line items. - `recipient` RecipientACH - … - CryptoLineItem — Represents a cryptocurrency transaction line item. - `price` number, float, required — The amount spent (in order currency) on cryptocurrency or asset(s). - `quantity` 1, required — Quantity must always be 1 for cryptocurrency transactions. - `title` string, required — The abbreviation of the cryptocurrency in all caps. - `product_id` string, required — The full asset name of the cryptocurrency. - `product_type` 'crypto', required — Specifies that this line item represents a digital asset. - `category` 'one_time_buy' | 'one_time_sell' | 'one_time_order' | 'recurring_buy' | 'recurring_sell' | 'checkout' | 'nft', required — The type of cryptocurrency transaction. Use `checkout` if purchasing at a third party merchant using cryptocurrency. - `brand` string — The brand name of the item. - `requires_shipping` false | true, required — States whether or not the item requires shipping. Should be set to False unless crypto is being sent to another customer as remittance. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string, date-time — The timestamp indicating when the cryptocurrency was delivered to the wallet. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `recipient` RecipientCrypto, required - … - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `sender_name` string — The sender name. - `photo_uploaded` boolean — Indicating whether a photo was uploaded. - `photo_url` string — The photo url (if uploaded). - `message` string — The card's message. - `display_name` string — The display name. - `greeting_photo_url` string — The greeting photo url (if exists). - `greeting_message` string — The greeting message. - `card_type` string — The card's type. - GiftcardLineItem - `price` number, float, required — The price of one unit of the product. - `quantity` integer, required — The number of items that were ordered. - `title` string, required — The title of the item. - `product_id` string, required — The id of the item. Limited to 256 characters - `category` string, required — The category of the item. For event tickets, the category of the event. - `brand` string — The brand name of the item. - `product_type` 'giftcard', required — The product type should contain the following value: giftcard - `requires_shipping` boolean, required — States whether or not the item requires shipping. Set to True for a physical gift card and False for a digital gift card. - `sku` string — A unique identifier of the item in the fulfillment. - `condition` string — Description of the physical condition of the item, mostly relevant for used items. - `seller` Seller - … - `sub_category` string — The sub-category of the item. For event tickets, the sub-category of the event. - `delivered_at` string — The planned delivery date of the product or item. - `delivered_to` 'shipping_address' | 'store_pickup' — **(Conditional Requirement)** Required for mixed shipment orders. The delivery type must contain one of the following values shipping_address: The Order's shipping address is the end user's entered address. store_pickup: If the end user selects store pickup, the shipping address value should contain the store's address. - `drop_point` string — If the end user is handing the package at a drop-off point, the shipping address value should contain the drop off location address - `size` string — The size of the item (e.g. shirt or shoe size) - `registry_type` 'wedding' | 'baby' | 'other' — The registry type must contain one of the following values: wedding, baby, other - `shipping_address_id` string — **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `sender_name` string — The sender name. - `photo_uploaded` boolean — Indicating whether a photo was uploaded. - `photo_url` string — The photo url (if uploaded). - `message` string — The card's message. - `display_name` string — The display name. - `greeting_photo_url` string — The greeting photo url (if exists). - `greeting_message` string — The greeting message. - `card_type` string — The card's type. - `recipient` Recipient, required - … - `tracking_company` string, required — The name of the shipping company. Supported values include: - `usps` — USPS - `ups` — UPS - `fedex` — FedEx - `dhl_express` — DHL / DHL Express - `dhl_ecommerce` — DHL Global Mail / DHL eCommerce - `canada_post` — Canada Post If the company is not listed, provide the carrier name as a string. - `tracking_numbers` string, required — A list of shipping numbers, provided by the shipping company. - `tracking_urls` string — The URLs to track the fulfillment. - `message` string — Additional textual description regarding the fulfillment status. - `receipt` string — Information about the receipt. - `dispute_details` DisputeDetails - `case_id` string, required — Dispute identifier as defined by the issuer/gateway - `status` 'won' | 'lost' | 'open' | 'pending' | 'expired' | 'accepted', required — The current status of the dispute. Possible values: * `open` - dispute was created and is awaiting action; * `pending` - evidence was submitted and the dispute is under review; * `expired` - the response window passed without submission and the case is considered lost due to timeout; * `accepted` - the dispute was intentionally accepted and liability is acknowledged; * `won` - the dispute was resolved in the merchant's favor; * `lost` - the dispute was resolved against the merchant. Note: we expect an updated API call when the dispute status changes. - `disputed_at` string, date-time — When (ISO8601) was the dispute sent. - `expected_resolution_date` string, date-time — When (ISO8601) should we expect a decision from the issuer (60-75 days usually). - `dispute_type` 'first_dispute' | 'second_dispute' | 'arbitrary_court' — Note: we expect an updated api call when the dispute type changes ## Response `200` Successful operation - ChargebackResponse — Refund Response - `order` object - `id` string, required — Unique ID of order being acted upon. Note: This value should be later reflected also as order.id on the subsequent calls - `status` 'chargeback', required — Textual status describing the result of Riskified analysis. Always 'approve' for approved orders. Order is approved and guaranteed by Riskified - `description` string, required — Additional context on Riskified decision. - `old_status` string, required — Old order status ## Other responses - `400` — Bad request - `401` — Unauthorized - `404` — Not found - `429` — Too many requests - `500` — Contact Riskified support - `504` — Temporary error, please retry --- [API](https://skmtc.dev/riskified/apis/chargeback-guarantee.md) · [All operations](https://skmtc.dev/riskified/apis/chargeback-guarantee/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riskified/chargeback-guarantee/revisions/2b7df5bce861/schema)