Overview Authentication Errors Retries Responses Order Actions Checkout Create Checkout Denied Advise Create Submit Update Cancel/Full-Refund Partial-Refund Fulfill Decision Chargeback Decide Historical Account Actions Login Reset Password Customer Create Customer Update Verification Logout Redeem Wishlist Changes Customer Reach-Out

Models

Order Checkout Line Item Passenger Discount Code Shipping Line Payment Details Customer Client Details Social Details Seller Address Refund Details Contact Details Charge Free Payment Details Authorization Error Fulfillment Details Decision Details Chargeback Details Dispute Details Authentication Result Recipient Login Status Contact Method Session Details Verification Session Details Notifications Store Front Beacon Single Page Application

Overview

The Riskified API is organized around REST and exposes endpoints for HTTP requests. The API is designed to have predictable, resource-oriented URLs and uses standard HTTP response codes to indicate the outcome of operations.

In order to make your life just a little bit easier we offer developer kits (SDKs) in various languages.

Sandbox base URL for sending API events: https://sandbox.riskified.com/api/
Production base URL for sending API events: https://wh.riskified.com/api/

API testing and development are done on Riskifed's Sandbox environment at:
https://sandbox.riskified.com

To run the examples with curl, we recommend executing the following lines in your shell first:

                                curl -O {{ EXAMPLE_ORDER_DOMAIN }}/{{ EXAMPLE_ORDER_FILENAME }}
export rskfd_auth_token={{ AUTH_TOKEN }}

There is an SDK for Java developers available at
Riskified's public github repository

Validations

The SDK includes a validation mechanism to help you catch formatting and data issues quickly.
However, it is possible to control the level of validation, through the SDKs Validation object,
which is the forth parameter in the SDK's RiskifiedClient constructor.
For example, you can tell the Validation engine to ignore missing values, by passing the constructor the

Validations.ignoreMissing

like this:

RiskifiedClient client = new RiskifiedClient(domain, authToken, Environment.sandbox, Validation.ignoreMissing);

Or specify the validation type in the config file 'riskified_sdk.properties'.

Available validation types: none, ignoreMissing and all.

There is an SDK for PHP developers available at
Riskified's public github repository

Validations

The SDK includes a validation mechanism to help you catch formatting and data issues quickly.
However, it is possible to control the level of validation, through the SDKs Validation object,
which is the forth parameter in the SDK's Riskified::init() method.
For example, you can tell the Validation engine to ignore missing values, by passing init() the

Validations::IGNORE_MISSING

like this:

Riskified::init($domain, $authToken, Env::SANDBOX, Validations::IGNORE_MISSING);

There is an SDK for .NET developers available at
Riskified's public github repository

Authentication

All requests to the Riskified API must include the following HTTP Headers. These are used to specify the current API version and to verify that the data has not been compromised.

We highly recommend using an SDK that handles the authentication flow automatically.

HTTP Headers

ACCEPT:

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

CONTENT_TYPE:

required

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

X-RISKIFIED-SHOP-DOMAIN:

required

Full domain name of shop that was registered.

X-RISKIFIED-HMAC-SHA256:

required

Verification hash for the Request.
Generated by performing an SHA256 encryption on the request's POST variables string and subsequently calculating the HMAC hash of the result using your Riskified authentication token.

CONTENT-TYPE:

required

Indication of what format the request is being sent in.
The value should always be application/json.

$data_string = "\{foo:\"bar\"}"
$signature = new Signature\HttpDataSignature()
$hmac_signature = $signature->calc_hmac($data_string)
$headers = array(
    'Content-Type: application/json',
    'Content-Length: '.strlen($data_string),
    $signature::SHOP_DOMAIN_HEADER_NAME.':'.'{{DOMAIN}}',
    $signature::HMAC_HEADER_NAME.':'.$hmac_signature
);

Please refer to Overview for instructions on how to download the sample order JSON and export your Auth Token.

To calculate the signature for the request, you can use the openssl command:

$ openssl dgst \
   -sha256 \
   -hmac $rskfd_auth_token \
   < {{ EXAMPLE_ORDER_FILENAME }}

The signature is sent in the X-RISKIFIED-HMAC-SHA256 header. Notice that the request body must fit the signature verbatim, otherwise you'll get a 401 error response.

$ curl -X POST \
   https://sandbox.riskified.com/api/create \
   --data-binary @{{ EXAMPLE_ORDER_FILENAME }} \
   -H "ACCEPT:application/vnd.riskified.com; version=2" \
   -H "Content-Type: application/json" \
   -H "X-RISKIFIED-SHOP-DOMAIN:{{ DOMAIN }}" \
   -H "X-RISKIFIED-HMAC-SHA256:`openssl dgst \
     -sha256 \
     -hmac $rskfd_auth_token \
     < {{ EXAMPLE_ORDER_FILENAME }}`"

Errors

Riskified uses conventional HTTP response codes to indicate success or failure of an API request. Most responses also include a payload detailing the nature of the error. See the Responses section for more.

HTTP Status 200 indicates request success.
HTTP Status 400 indicates an error that resulted from the provided information (e.g. a required parameter was missing, a parameter was given in the wrong format, etc.)
HTTP Status 401 indicates a missing or invalid X_RISKIFIED_HMAC_SHA256 signature.
HTTP Status 404 indicates that the requested endpoint does not exist.
HTTP Status 500 indicates an internal error with Riskified's servers.

Riskified's SDKs validate the parameters before sending each request, which means you needn't worry about 4XX status codes. This also allows you to easily spot integration issues.

Retries

General

Riskified recommends the below retry policy in the rare occurrence that an API call to our system returns an error code as outlined in this section.

Maximum hold times and delays between retries should be adjusted according to the system ability and fulfillment requirements of the merchant business.

If you have any questions on how your flow strategy (async/sync and pre/post auth) influences the retry policy, please contact your Integration Engineer or Account Manager for assistance.

Recommended Retry Policy

Async (or post-auth sync merchants)

Attempt up to 3 times on error responses, each attempt to be spaced 2 seconds apart

After 3 attempts, implement further attempts with additional delays:

Call once every 1 minute until 5 minutes
Call once every 5 minutes until 2 hours
Call once every 10 minutes until 4 hours

Orders should be held in queue until Riskified decision is received

Pre-Auth Sync

Attempt up to 3 times on error responses, each attempt to be spaced 0.5 seconds apart

After 4th attempt, order should be approved/confirmed as usual as Riskified should be non-blocking in the order flow

Responses

Every API call returns a payload that describes the result of the action requested.
The response may contain one or more for the following objects:

Order

id:

Unique ID of order being acted upon.

status:

Textual status describing the result of the operation.
Possible values are:

Captured
Submitted
Approved
Declined

description:

Detailed description of the operation, if exists.

Warnings

List of textual warnings that were raised while processing the request.

Error

message:

Details of a critical error that occurred while processing the request.

Authentication Type

auth_type:

Riskified's authentication type recommendation. Must be one of the following values:

fraud
tra
sca
out_of_scope
low_amount

exemption_method:

The method of requesting exemption from the acquirer. Must be one of the following values:

data_only
iso
3ds

Example response for successful execution:


{
  "order" : {
    "id" : 123,
    "status" : "submitted",
    "description" : "order submitted for review successfully"
  }
}

Example response with warnings:


{
  "order" : {
    "status" : "captured",
  },
  "warnings" : [
    "Bad Credit Card Details"
  ]
}

Example response for failed execution:


{
  "error" : {
    "message" : "Something went wrong"
  }
}

Example response describing Riskified's authentication type recommendation:


{
 "checkout": {
  "id": "123abc",
  "status": "captured",
  "authentication_type": {
    "auth_type": "out_of_scope",
    "exemption_method": "data_only"
    
   }
  }
}

Order Actions

Checkout Create

HTTP Method: POST

Endpoint: /api/checkout_create

Creates a new checkout.
Should be called before attempting payment authorization and order creation.

Refer to the Checkout section for details on building the model and constructing individual fields.

Parameters

checkout:

Checkout required

A checkout to create.

CheckoutOrder checkoutOrder = new CheckoutOrder();

RiskifiedClient client = new RiskifiedClient();
Response res = client.checkoutOrder(checkoutOrder);

OrderCheckout orderCheckout = new OrderCheckout(...);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Checkout(orderCheckout);

$checkout = new Model\Checkout(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->createCheckout($checkout);

{
  "checkout": {
    "id" : "checkout_id",
    ...
  }
}

Checkout Denied

HTTP Method: POST

Endpoint: /api/checkout_denied

Alert that a checkout was denied authorization.

Refer to the Checkout section for details on building the model and constructing individual fields.
In addition to all required Checkout fields, please make sure you fill out the Authorization Error object within the Payment Details section.

Parameters

checkout:

Checkout required

A checkout to alert as denied.

AuthorizationError authorizationError = new AuthorizationError(AuthorizationErrorType.expiredCard, new Date(114, 01, 10, 11, 00, 00));
authorizationError.setMessage("expired credit card.");

CreditCardPaymentDetails creditCardPaymentDetails = new CreditCardPaymentDetails("123456", "full", "m", "4242", "VISA");
creditCardPaymentDetails.setAuthorizationError(authorizationError);

CheckoutDeniedOrder checkoutDeniedOrder = new CheckoutDeniedOrder("cd12345");
checkoutDeniedOrder.setPaymentDetails(Array.asList(creditCardPaymentDetails));

RiskifiedClient client = new RiskifiedClient();
Response res = client.checkoutDeniedOrder(checkoutDeniedOrder);

var authorizationError = new AuthorizationError(
                createdAt: new DateTime(2013, 12, 8, 14, 12, 12, DateTimeKind.Local),
                errorCode: AuthorizationErrorCode.CardDeclined,
                message: "Card was Declined.");

var payment = new CreditCardPaymentDetails(
                avsResultCode: "Y",
                cvvResultCode: "n",
                creditCardBin: "123456",
                creditCardCompany: "Visa",
                creditCardNumber: "XXXX-XXXX-XXXX-4242",
                creditCardToken: "2233445566778899");
payment.AuthorizationError = authorizationError;

var payments = new [] {
    payment
}

var orderCheckoutDenied = new OrderCheckoutDenied(orderNum.ToString());
orderCheckoutDenied.PaymentDetails = payments;

OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");

OrderNotification notification = gateway.CheckoutDenied(orderCheckoutDenied);

$checkout = new Model\Checkout(...);
$checkout->payment_details = array(new Model\PaymentDetails(array(
     'credit_card_bin' => '123456',
     'credit_card_number' => 'xxxx-xxxx-xxxx-4242',
     'credit_card_company' => 'VISA',
     'credit_card_token' => '0022334466',
     'authorization_error' => new Model\AuthorizationError(array(
                                  'created_at' => '2008-01-10T11:00:00-05:00',
                                  'error_code' => 'card_rejected'
                              ))
 )));

$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->deniedCheckout($checkout);

{
  "checkout": {
    "id": "checkout_id",
    "payment_details": [
      {
        "authorization_error": {
          "created_at": "2008-01-10T11:00:00-05:00",
          "error_code": "card_declined",
          "message": "Card was denied."
        },
        "avs_result_code": "Y",
        "credit_card_bin": "123456",
        "credit_card_company": "Visa",
        "credit_card_number": "XXXX-XXXX-XXXX-4242",
        "cvv_result_code": "M"
      }
    ],
    "email": "bob.norman@hostmail.com",
    "created_at": "2018-06-15T11:00:00-05:00",
    "currency": "USD",
    "updated_at": "2018-06-15T11:00:00-05:00",
    "gateway": "authorize_net",
    "browser_ip": "111.111.111.111",
    "total_price": 319.00,
    "total_discounts": 10.00,
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "referring_site": "google.com",
    "line_items": [
      {
        "price": 329.00,
        "quantity": 1,
        "title": "Apple Watch Series 3 GPS, 38mm Silver Aluminum Case with Fog Sport Band",
        "product_id": "632910392",
        "category": "electronics",
        "brand": "apple",
        "product_type": "physical"
      }
    ],
    "discount_codes": [
      {
        "amount": 10.00,
        "code": "TENOFF"
      }
    ],
    "shipping_lines": [
      {
        "price": 0.00,
        "title": "Free Shipping"
      }
    ],
    "customer": {
      "email": "bob.norman@hostmail.com",
      "verified_email": true,
      "first_name": "Bob",
      "last_name": "Norman",
      "id": "207119551",
      "created_at": "2013-04-23T13:36:50-04:00"
    },
    "billing_address": {
      "first_name": "Bob",
      "last_name": "Norman",
      "address1": "Chestnut Street 92",
      "country": "United States",
      "country_code": "US",
      "phone": "555-625-1199",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "zip": "40202"
    },
    "shipping_address": {
      "first_name": "Bob",
      "last_name": "Norman",
      "address1": "Chestnut Street 92",
      "country": "United States",
      "country_code": "US",
      "phone": "555-625-1199",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "zip": "40202"
    },
    "source": "desktop_web",
    "client_details": {
      "accept_language": "en-CA",
      "user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
    }
  }
}

Advise

HTTP Method: POST

Endpoint: /api/advise

Creates a new checkout. Returns a synchronous response, AuthenticationType, indicating Riskified's authentication recommendation.
Should be called before attempting payment authorization and order creation.

Refer to the Checkout section for details on building the model and constructing individual fields.
Note the additional required fields in the PaymentDetails model when calling this endpoint.

Parameters

checkout:

Checkout required

A checkout to create.

CheckoutOrder checkoutOrder = new CheckoutOrder();

RiskifiedClient client = new RiskifiedClient();
Response res = client.checkoutOrder(checkoutOrder);

OrderCheckout orderCheckout = new OrderCheckout(...);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Checkout(orderCheckout);

$checkout = new Model\Checkout(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->createCheckout($checkout);

{
  "checkout": {
    "id" : "checkout_id",
    ...
  }
}

Create

HTTP Method: POST

Endpoint: /api/create

Send a new order to Riskified.
Depending on your current plan, the newly created order might not be submitted automatically for review.

Refer to the Models section for details on building the model and constructing individual fields.

Sandbox URL: https://sandbox.riskified.com/api/create
Production URL: https://wh.riskified.com/api/create

Expected responses will be returned asynchronously to the pre-defined notification endpoint in the following format. Refer to the Notifications section for further information on handling Riskified's response.

JSON keys

Order

id:

Unique ID of order being acted upon.

status:

Textual status describing the result of the operation. Expected values include:

approved
declined

description:

Detailed description of the operation, if exists.

old_status:

Textual status describing the original status of the order.

Parameters

order:

Order required

An order to create.
Any missing fields (such as BIN number or AVS result code) that are unavailable during the time of the request should be skipped or passed as null.

{
	"order": {
		"id": "450789469",
		"email": "bob.norman@hostmail.com",
		"created_at": "2018-06-15T11:00:00-05:00",
		"currency": "USD",
		"updated_at": "2018-06-15T11:00:00-05:00",
		"gateway": "authorize_net",
		"browser_ip": "111.111.111.111",
		"total_price": 319.00,
		"total_discounts": 10.00,
		"cart_token": "68778783ad298f1c80c3bafcddeea02f",
		"device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
		"referring_site": "google.com",
		"line_items": [
			{
				"price": 329.00,
				"quantity": 1,
				"title": "Apple Watch Series 3 GPS, 38mm Silver Aluminum Case with Fog Sport Band",
				"product_id": "632910392",
				"category": "electronics",
				"brand": "apple",
				"product_type": "physical"
			}
		],
		"discount_codes": [
			{
				"amount": 10.00,
				"code": "TENOFF"
			}
		],
		"shipping_lines": [
			{
				"price": 0.00,
				"title": "Free Shipping"
			}
		],
		"payment_details": [
			{
				"credit_card_bin": "414049",
				"avs_result_code": "A",
				"cvv_result_code": "M",
				"credit_card_number": "XXXX-XXXX-XXXX-4242",
				"credit_card_company": "Visa",
				"stored_payment_created_at": "2019-08-21T12:50:00+00:00",
				"stored_payment_updated_at": "2020-01-13T12:51:00+00:00"
			}
		],
		"customer": {
			"email": "bob.norman@hostmail.com",
			"verified_email": true,
			"first_name": "Bob",
			"last_name": "Norman",
			"id": "207119551",
			"created_at": "2013-04-23T13:36:50-04:00",
			"account_type": "registered"
		},
		"billing_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"shipping_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"source": "desktop_web",
		"client_details": {
			"accept_language": "en-CA",
			"user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
		}
	}
}

$order = new Model\Order(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->createOrder($order);

Order order = new Order(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Create(order);

Order order = new Order();

RiskifiedClient client = new RiskifiedClient();
Response res = client.createOrder(order);

Submit

HTTP Method: POST

Endpoint: /api/submit

Submit a new or existing order to Riskified for review.
Forces the order to be submitted for review, regardless of your current plan.

Refer to the Models section for details on building the model and constructing individual fields.

Parameters

order:

Order required

An order to submit for review.
Any missing fields (such as BIN number or AVS result code) that are unavailable during the time of the request should be skipped or passed as null.

{
	"order": {
		"id": "450789469",
		"email": "bob.norman@hostmail.com",
		"created_at": "2018-06-15T11:00:00-05:00",
		"currency": "USD",
		"updated_at": "2018-06-15T11:00:00-05:00",
		"gateway": "authorize_net",
		"browser_ip": "111.111.111.111",
		"total_price": 319.00,
		"total_discounts": 10.00,
		"cart_token": "68778783ad298f1c80c3bafcddeea02f",
		"device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
		"referring_site": "google.com",
		"line_items": [
			{
				"price": 329.00,
				"quantity": 1,
				"title": "Apple Watch Series 3 GPS, 38mm Silver Aluminum Case with Fog Sport Band",
				"product_id": "632910392",
				"category": "electronics",
				"brand": "apple",
				"product_type": "physical"
			}
		],
		"discount_codes": [
			{
				"amount": 10.00,
				"code": "TENOFF"
			}
		],
		"shipping_lines": [
			{
				"price": 0.00,
				"title": "Free Shipping"
			}
		],
		"payment_details": [
			{
				"credit_card_bin": "414049",
				"avs_result_code": "A",
				"cvv_result_code": "M",
				"credit_card_number": "XXXX-XXXX-XXXX-4242",
				"credit_card_company": "Visa",
				"stored_payment_created_at": "2019-08-21T12:50:00+00:00",
				"stored_payment_updated_at": "2020-01-13T12:51:00+00:00"
			}
		],
		"customer": {
			"email": "bob.norman@hostmail.com",
			"verified_email": true,
			"first_name": "Bob",
			"last_name": "Norman",
			"id": "207119551",
			"created_at": "2013-04-23T13:36:50-04:00",
			"account_type": "registered"
		},
		"billing_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"shipping_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"source": "desktop_web",
		"client_details": {
			"accept_language": "en-CA",
			"user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
		}
	}
}

$order = new Model\Order(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->submitOrder($order);

Order order = new Order(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Submit(order);

Order order = new Order();

RiskifiedClient client = new RiskifiedClient();
Response res = client.submitOrder(order);

Update

HTTP Method: POST

Endpoint: /api/update

Update details of an existing order.
Orders are differentiated by their id field. To update an existing order, include its id and any up-to-date data.

Parameters

order:

Order required

A (possibly incomplete) order to update.
The order must have an id field referencing an existing order and at least one additional field to update.

{
	"order": {
		"id": "450789469",
		"email": "bob.norman@hostmail.com",
		"created_at": "2018-06-15T11:00:00-05:00",
		"currency": "USD",
		"updated_at": "2018-06-15T11:00:00-05:00",
		"gateway": "authorize_net",
		"browser_ip": "111.111.111.111",
		"total_price": 319.00,
		"total_discounts": 10.00,
		"cart_token": "68778783ad298f1c80c3bafcddeea02f",
		"device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
		"referring_site": "google.com",
		"line_items": [
			{
				"price": 329.00,
				"quantity": 1,
				"title": "Apple Watch Series 3 GPS, 38mm Silver Aluminum Case with Fog Sport Band",
				"product_id": "632910392",
				"category": "electronics",
				"brand": "apple",
				"product_type": "physical"
			}
		],
		"discount_codes": [
			{
				"amount": 10.00,
				"code": "TENOFF"
			}
		],
		"shipping_lines": [
			{
				"price": 0.00,
				"title": "Free Shipping"
			}
		],
		"payment_details": [
			{
				"credit_card_bin": "414049",
				"avs_result_code": "A",
				"cvv_result_code": "M",
				"credit_card_number": "XXXX-XXXX-XXXX-4242",
				"credit_card_company": "Visa",
				"stored_payment_created_at": "2019-08-21T12:50:00+00:00",
				"stored_payment_updated_at": "2020-01-13T12:51:00+00:00"
			}
		],
		"customer": {
			"email": "bob.norman@hostmail.com",
			"verified_email": true,
			"first_name": "Bob",
			"last_name": "Norman",
			"id": "207119551",
			"created_at": "2013-04-23T13:36:50-04:00",
			"account_type": "registered"
		},
		"billing_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"shipping_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"source": "desktop_web",
		"client_details": {
			"accept_language": "en-CA",
			"user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
		}
	}
}

$updatedOrder = new Model\Order(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->updateOrder($updatedOrder);

Order order = new Order(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Update(order);

Order order = new Order();

RiskifiedClient client = new RiskifiedClient();
Response res = client.updateOrder(order);

Cancel/Full-Refund

HTTP Method: POST

Endpoint: /api/cancel

Mark a previously submitted order as cancelled.
If the order has not yet been reviewed, it is excluded from future review.
If the order has already been reviewed and approved, cancelling it will also trigger a full refund on any associated charges.
An order can only be cancelled during a relatively short time window after its creation.

Parameters

id:

String required

The unique identifier of the order to cancel.

cancel_reason:

String required

A reason for cancelling or fully refunding the order

cancelled_at:

DateTime required

The date and time when the order was canceled

OrderCancellation cancellation = new OrderCancellation(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Cancel(cancellation);

{
    "order" : {
        "id" : "123",
        "cancel_reason" : "Product out of stock",
        "cancelled_at" : "2014-01-10T11:00:00Z"
    }
}

$order = new Model\Order(array(
    'id' => '123',
    'cancel_reason' => 'Out of stock',
    'cancelled_at' => '2010-01-10T11:00:00-05:00'
));
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->cancelOrder($order);

CancelOrder cancel = new CancelOrder();
        cancel.setId("123");
        cancel.setCancelReason("Out of stock");
        cancel.setCancelledAt(new Date());

RiskifiedClient client = new RiskifiedClient();
Response res = client.cancelOrder(cancel);

Partial-Refund

HTTP Method: POST

Endpoint: /api/refund

Issue a partial refund for an existing order.
Any associated charges will be updated to reflect the new order total amount.

Parameters

id:

String required

The unique identifier of the order to refund.

refunds:

Array of RefundDetails required

A list of partial refunds for the order.

OrderPartialRefund partialRefund = new OrderPartialRefund(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.PartlyRefund(partialRefund);

{
    "order" : {
        "id" : "123",
        "refunds" : [
            {
                "refund_id" : "1235",
                "sku" : "ABCD004245",
                "amount" : 10.5,
                "refunded_at" : "2014-01-10T11:00:00Z",
                "currency" : "USD",
                "reason" : "Rebate"
            },
            {
                "refund_id" : "1238",
                "sku" : "EFGH008482",
                "amount" : 22,
                "refunded_at" : "2014-02-10T11:00:00Z",
                "currency" : "USD",
                "reason" : "Product not shipped"
            }
        ]
    }
}

$refund = new Model\RefundDetails(array(
                'refund_id' => '1235',
                'amount' => 10.5,
                'refunded_at' => '2014-01-10T11:00:00Z',
                'currency' => 'USD',
                'reason' => 'Rebate'
));
$order = new Model\Order(array(
    'id' => '123',
    'refunds' => array($refund)
));
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->refundOrder($order);

RefundOrder refund = new RefundOrder();
refund.setId("123");

RefundDetails refundDetail = new RefundDetails();
refundDetail.setRefundId("refund_001");
refundDetail.setAmount(33.12);
refundDetail.setCurrency("USD");
refundDetail.setRefundedAt(new Date());
refundDetail.setReason("Product Missing");

refund.setRefunds(Arrays.asList(refundDetail));

RiskifiedClient client = new RiskifiedClient();
Response res = client.refundOrder(refund);

Fulfill

HTTP Method: POST

Endpoint: /api/fulfill

Notifies Riskified that the fulfillment information has been generated for a particular order, including successful and failed attempts.

Include the tracking_company and tracking_numbers fields to eliminate delays during the chargeback reimbursement process.

Refer to the FulfillmentDetails section for details on building the model and constructing individual fields.

Parameters

id:

String required

The unique identifier of the order that completed fulfillment.

fulfillments:

Array of FulfillmentDetails required

A list of fulfillment attempts for the order.

List<FulfillmentDetails> fulfillments = new ArrayList<FulfillmentDetails>();
FulfillmentDetails fulfilmentDetails1 = new FulfillmentDetails("33", new Date(114, 01, 10, 11, 00, 00), "success");
fulfillments.add(fulfilmentDetails1);
FulfillmentOrder fulfillmentOrder = new FulfillmentOrder("1235", fulfillments);

RiskifiedClient client = new RiskifiedClient();
Response res = client.fulfillOrder(fulfillmentOrder);

OrderFulfillment orderFulfillment = new OrderFulfillment(
                                    merchantOrderId: fulfillOrderId,
                                    fulfillments: new FulfillmentDetails[] {
                                        new FulfillmentDetails(
                                            fulfillmentId: "123",
                                            createdAt: new DateTime(2013, 12, 8, 14, 12, 12),
                                            status: StatusCode.Success,
                                            lineItems: new LineItem[] { new LineItem("Bag", 10.0, 1) },
                                            trackingCompany: "TestCompany")
                                    }));


OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");

OrderNotification notification = gateway.Fulfill(orderFulfillment);

$fulfillment =  new Model\Fulfillment(array(
    'id' => $order->id,
    'fulfillments' => array(new Model\FulfillmentDetails(array(
        'fulfillment_id' => 'f12124',
        'created_at' => '2008-01-10T11:00:00-05:00',
        'status' => 'success',
        'tracking_company' => 'UPS',
        'tracking_numbers' => '76XD82'
    )))
));
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->fulfillOrder($fulfillment);

{
  "order": {
    "id": "123",
    "fulfillments": [
      {
        "created_at": "2013-04-23T13:36:50-04:00",
        "status": "success",
        "tracking_company": "fedex",
        "tracking_numbers": "abc123",
        "tracking_urls": "http://fedex.com/track?q=abc123",
        "message": "estimated delivery 2 days",
        "receipt": "authorization: 765656"
      },
      {
        "created_at": "2013-04-23T13:36:50-04:00",
        "status": "failure",
        "message": "item out of stock"
      }
    ]
  }
}

Decision

HTTP Method: POST

Endpoint: /api/decision

Update existing order external status.
Let us know what was your decision on your order.
For pre-authorization flow: Complete missing payment details based on gateway authorization response to allow better processing and dispute of chargebacks

Parameters

id:

String required

The unique identifier of the order the decision is on.

decision:

DecisionDetails required

The decision details for the order.

If you are integrated in a pre-authorization flow:

gateway:

String required

If the gateway is unknown during order submission, please provide the gateway name in this call

payment_details:

PaymentDetails required

Please provide updated payment details based on gateway authorization response, including avs_result_code, cvv_result_code, and authorization_id results.

authorization_id is required to support automated processing and dispute of chargebacks. Contact your dedicated integration engineer or account manager for more details on direct chargeback reporting and disputing

DecisionDetails decision = new DecisionDetails();
decision.setExternalStatus(DecisionType.declined);
decision.setReason("known fraudster");
decision.setDecidedAt(new Date(114, 01, 11, 11, 00, 00));
DecisionOrder decisionOrder = new DecisionOrder(ORDER_MERCHANT_ID, decision);

RiskifiedClient client = new RiskifiedClient();
Response res = client.decisionOrder(decisionOrder);

OrderDecision orderDecision = new OrderDecision(merchantOrderId,
            new DecisionDetails(ExternalStatusType.ChargebackFraud, DateTime.Now, "stolen credit card."));
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Decision(orderDecision);

{
  "order": {
    "id": "123",
    "decision": {
      "external_status": "approved",
      "reason": "transaction authorized and order confirmed",
      "decided_at": "2013-04-23T13:36:50-04:00",
      "notes": "",
      "amount": "120.0",
      "currency": "USD"
    },
    "gateway" : "Adyen",
    "payment_details" : [{
      "avs_result_code" : "8",
      "cvv_result_code" : "M",
      "authorization_id" : "134678ac"
    }]
  }
}

Chargeback

Please contact us before implementing this API flow

HTTP Method: POST

Endpoint: /api/chargeback

The chargeback API will allow merchants to request a fraud-related chargeback reimbursement. The submitted request will be processed within 48 hours. Eligible requests will trigger an automatic credit refund by Riskified. An eligible chargeback reimbursement request must match the details provided originally within the order JSON and contain a fraudulent chargeback reason code. For tangible goods, Riskified uses the tracking number provided in the fulfillment parameter to ensure the parcel was delivered to the address provided within the order JSON. Riskified reserves the right to request additional documentation pertaining to submitted chargebacks as part of the eligibility review process.

Refer to the ChargebackDetails, Fulfillment and DisputeDetails sections for details on building the model and constructing individual fields.

Parameters

id:

String required

The original order ID

chargeback_details:

ChargebackDetails required

An object containing information about the chargeback.

fulfillment:

Fulfillment conditional

Required for tangible goods includes shipping information

dispute_details:

DisputeDetails conditional

In case a dispute was sent from a merchant or is going to be sent from riskified

ChargebackDetails chargebackDetails = new ChargebackDetails(id: "id1234",
                    charegbackAt: new DateTime(2015, 12, 8, 14, 12, 12, DateTimeKind.Local),
                    chargebackCurrency: "USD",
                    chargebackAmount: (float)50.5,
                    reasonCode: "4863",
                    reasonDesc: "Transaction not recognised",
                    type: "cb",
                    mid: "t_123",
                    creditCardCompany: "visa",
                    respondBy: new DateTime(2016, 9, 1),
                    arn: "a123456789012bc3de45678901f23a45",
                    cardIssuer: "Wells Fargo Bank",
                    gateway: "braintree";

FulfillmentDetails fulfillmentDetails = new FulfillmentDetails(
                                 fulfillmentId: "123",
                                 createdAt: new DateTime(2015, 12, 8, 14, 12, 12, DateTimeKind.Local),
                                 status: FulfillmentStatusCode.Success,
                                 lineItems: new LineItem[] { new LineItem("Bag", 10.0, 1) },
                                 trackingCompany: "TestCompany");

DisputeDetails disputeDetails = new DisputeDetails(
                            disputeType: "first_dispute",
                            caseId: "a1234",
                            status: "won",
                            disputedAt:  new DateTime(2016, 9, 15),
                            expectedResolutionDate: new DateTime(2016, 11, 1));

OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Chargeback(id, chargebackDetails, fulfillmentDetails, disputeDetails);

ChargebackOrder chargebackOrder = new ChargebackOrder();
chargebackOrder.setId("id");

ChargebackDetails chargebackDetails = new ChargebackDetails();
chargebackDetails.setId("chargeback_details_id");
chargebackDetails.setChargebackAmount(1233.0);
chargebackOrder.setChargebackDetails(chargebackDetails);

FulfillmentDetails fulfillment = new FulfillmentDetails("fulfillment_id", new Date(114, 01, 10, 11, 00, 00), "success");
chargebackOrder.setFulfillment(fulfillment);

DisputeDetails disputeDetails = new DisputeDetails();
disputeDetails.setCaseID("case_id");
disputeDetails.setStatus("won");

chargebackOrder.setDisputeDetails(disputeDetails);

Response chbOrder = client.chargebackOrder(chargebackOrder);

$chargebackDetails = new Model\ChargebackDetails(array(
    'id' => 'chargeback_details_id',
    'chargeback_at' => '2008-01-10T11:00:00-05:00',
    'chargeback_amount' => 12.0,
    'chargeback_currency' => 'USD'
));
$disputeDetails = new Model\DisputeDetails(array(
    'case_id' => 'case_id',
    'status' => 'won'
));

$fulfillmentDetails = new Model\FulfillmentDetails(array(
    'fulfillment_id' => 'fulfillment_id',
    'status' => 'success'
));
$chargeback = new Model\OrderChargeback(array(
    'id' => 'id'
));
$chargeback->chargeback_details = $chargebackDetails;
$chargeback->dispute_details = $disputeDetails;
$chargeback->fulfillment = $fulfillmentDetails;

$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->chargebackOrder($chargeback);

{
  "order": {
    "id": "123456",
    "chargeback_details": {
      "id": "15673",
      "chargeback_at" : "2016-06-10T15:46:51Z",
      "chargeback_currency" : "USD",
      "chargeback_amount" : 50.5,
      "reason_code" : "4863",
      "type" : "cb",
      "gateway" : "braintree",
      "reason_description" : "Transaction not recognised",
      "mid" : "t_123",
      "arn" : "a123456789012bc3de45678901f23a45",
      "credit_card_company" : "visa",
      "respond_by" : "2016-09-01",
      "card_issuer" : "Wells Fargo Bank"
    },
    "fulfillment": {
      "fulfillment_id": "12asf123",
      "created_at": "2013-04-23T13:36:50-04:00",
      "status": "success",
      "tracking_company": "fedex",
      "tracking_numbers": "abc123"
    },
    "dispute_details" : {
      "case_id" : "a1234",
      "status" : "won",
      "disputed_at" : "2017-06-01",
      "expected_resolution_date" : "2017-07-15",
      "dispute_type" : "first_dispute"
    }
  }
}

Decide

HTTP Method: POST

Endpoint: /api/decide

Analyzes the order synchronically, the returned status is Riskified's analysis review result. (Only for merchants with sync flow)
Must use https://wh-sync.riskified.com as the production base url for this endpoint only.

Production url: https://wh-sync.riskified.com/api/decide.
Sandbox url: https://sandbox.riskified.com/api/decide.

Refer to the Models section for details on building the model and constructing individual fields.

Expected responses will be returned synchronously to the request sent to our API endpoint. Refer to the Notifications section for further information on handling Riskified's response.

JSON keys

Order

id:

Unique ID of order being acted upon.

status:

Textual status describing the result of the operation. Expected values include:

approved
declined
captured

description:

Detailed description of the operation, if exists.

Parameters

order:

Order required

An order to create.
Any missing fields (such as BIN number or AVS result code) that are unavailable during the time of the request should be skipped or passed as null.

{
	"order": {
		"id": "450789469",
		"email": "bob.norman@hostmail.com",
		"created_at": "2018-06-15T11:00:00-05:00",
		"currency": "USD",
		"updated_at": "2018-06-15T11:00:00-05:00",
		"gateway": "authorize_net",
		"browser_ip": "111.111.111.111",
		"total_price": 319.00,
		"total_discounts": 10.00,
		"cart_token": "68778783ad298f1c80c3bafcddeea02f",
		"device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
		"referring_site": "google.com",
		"line_items": [
			{
				"price": 329.00,
				"quantity": 1,
				"title": "Apple Watch Series 3 GPS, 38mm Silver Aluminum Case with Fog Sport Band",
				"product_id": "632910392",
				"category": "electronics",
				"brand": "apple",
				"product_type": "physical"
			}
		],
		"discount_codes": [
			{
				"amount": 10.00,
				"code": "TENOFF"
			}
		],
		"shipping_lines": [
			{
				"price": 0.00,
				"title": "Free Shipping"
			}
		],
		"payment_details": [
			{
				"credit_card_bin": "414049",
				"avs_result_code": "A",
				"cvv_result_code": "M",
				"credit_card_number": "XXXX-XXXX-XXXX-4242",
				"credit_card_company": "Visa",
				"stored_payment_created_at": "2019-08-21T12:50:00+00:00",
				"stored_payment_updated_at": "2020-01-13T12:51:00+00:00"
			}
		],
		"customer": {
			"email": "bob.norman@hostmail.com",
			"verified_email": true,
			"first_name": "Bob",
			"last_name": "Norman",
			"id": "207119551",
			"created_at": "2013-04-23T13:36:50-04:00",
			"account_type": "registered"
		},
		"billing_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"shipping_address": {
			"first_name": "Bob",
			"last_name": "Norman",
			"address1": "Chestnut Street 92",
			"country": "United States",
			"country_code": "US",
			"phone": "555-625-1199",
			"city": "Louisville",
			"province": "Kentucky",
			"province_code": "KY",
			"zip": "40202"
		},
		"source": "desktop_web",
		"client_details": {
			"accept_language": "en-CA",
			"user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
		}
	}
}

$order = new Model\Order(...);
$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());
$response = $transport->decideOrder($order);

Order order = new Order(....);
OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
OrderNotification notification = gateway.Decide(order);

Order order = new Order();

RiskifiedClient client = new RiskifiedClient();
Response res = client.analyzeOrder(order);

Historical

HTTP Method: POST

Endpoint: /api/historical

Send an array (batch) of existing/historical orders to Riskified.
Orders sent will be used to build analysis models to better analyze newly received orders.
Order data should be similar to the data sent to the /api/create endpoint and include all available parameters of these orders (shipping/billing addresses, payment details, etc)

Tagging financial status of historical orders

In addition to the order parameters, provide Riskified with information regarding the order decision and outcome.
There are two possible ways to provide this data:

Use the decision field (DecisionDetails) to provide information regarding each order status.
Send the information as a CSV file with this format: [ID],[TAG]
[ID] is your order ID (the same parameter you passed in the order JSON as 'id')
[TAG] is the value of external_status, which is a field inside decision. (use external_status field values that are described in DecisionDetails).

Parameters

orders:

Array of Orders required

A list of historical orders to send

var historicalData = new[] {
    new Order(...),
    new Order(...),
    new Order(...)
}

OrdersGateway gateway = new OrdersGateway(RiskifiedEnvironment.Sandbox, "authToken", "domain");
Dictionary<string,string> errorsForOrders;
bool success = gateway.SendHistoricalOrders(historicalData,out errorsForOrders);

{
    "orders" : [{o1...},{o2...},{o3...}]
}

Riskified::init($domain, $authToken, Env::SANDBOX);

$first_order = new Model\Order(...);
$second_order = new Model\Order(...);

$orders = array($first_order, $second_order);

$transport = new Transport\CurlTransport(new Signature\HttpDataSignature());

try {
    $response = $transport->sendHistoricalOrders($orders);
    echo PHP_EOL."Upload succeeded. Response: ".PHP_EOL.json_encode($response).PHP_EOL;
} catch(\Riskified\OrderWebhook\Exception\UnsuccessfulActionException $uae) {
    echo PHP_EOL."Upload failed. Status code was: ".$uae->statusCode." and body was: "
        .json_encode($uae->jsonResponse).PHP_EOL;
} catch(Exception $e) {
    echo PHP_EOL."Upload failed. Exception: ".$e->getMessage().PHP_EOL;
}

ArrayOrders orders = new ArrayOrders();
        orders.getOrders().add(new Order());
        orders.getOrders().add(new Order());

RiskifiedClient client = new RiskifiedClient();
Response res = client.historicalOrders(orders);

Account Actions

For account actions, all API configurations will remain the same (e.g. headers and response codes), the only differences will be server URLs used for Sandbox and Production:

Sandbox: "https://api-sandbox.riskified.com/customers/"
Production: "https://api.riskified.com/customers/"

Login

HTTP Method: POST

Endpoint: /customers/login

Send a new login attempt to Riskified

Refer to the ClientDetails, SessionDetails, and LoginStatus sections for details on building the model and constructing individual fields.

Parameters

customer_id:

String required

A unique numeric identifier for the customer.
customer_id should be null for failed logins (login_status_type = 'failure') where the failure_reason = 'nonexistent account' or 'other'.
Please refer to the Login Status section for documentation on these parameters

customer_created_at:

DateTime conditional

required if login_status_type = 'success'
The timestamp of the initial registration of the customer's account in the merchant's systems.
customer_created_at should be null for failed logins (login_status_type = 'failure') where the failure_reason = 'nonexistent account' or 'other'.

email:

String required

The email address used for the login attempt

login_at_checkout:

Boolean optional

Indicates whether the login attempt was made at checkout

social_login_type:

String optional

In case the user used a social network to log in, send one of the following values:

facebook
google
amazon
linkedin
twitter
yahoo
apple
other

login_status:

LoginStatus required

An object containing details of the customer's login attempt.

client_details:

ClientDetails required

An object containing technical information regarding the customer