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’s browsing session.

session_details:

SessionDetails required

An object containing basic information regarding the session.

challenge_redirect_url:

String optional

URL to which customer will be redirected to upon taking action from the verification emails.

account_recovery_url:

String optional

URL to which customer will be redirected to upon taking action from the verification emails to recover user account.

localization_language:

String optional

The 2 letter code (ISO 639-1) to indicate the language the user has selected for merchant site content browsing and communications.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "customer_created_at": "2019-09-12T14:04:50-05:00",
  "email": "bob.norman@hostmail.com",
  "login_at_checkout": false,
  "social_login_type": "facebook",
  "login_status": {
    "login_status_type": "failure",
    "failure_reason": "wrong password"
  },
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2018-04-23T13:36:50-04:00",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
    "referring_site": "http://www.nba.com/"
  }
}

Reset Password Request

HTTP Method: POST

Endpoint: /customers/reset_password

Send event when a password-reset action is being requested or processed.

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

status:

Enum of Strings required

Indicates the status of the request.
Must be one of the following:

pending: Password reset has been requested but new password has not been set.
success: Password has successfully been reset and old password is no longer valid.
failed: Password failed to be reset and old password is still valid.

reason:

Enum of Strings required

The reason for the password reset request.
Must be one of the following:

user_requested: Customer is logged in and initiates a password change from their account.
forgot_password: Customer has forgotten password and directly initiates process to create a new password.
forced_reset: An internal system-initiated password reset request.

email:

String required

The email address on the registered customer account

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "status": "success",
  "reason": "user_requested",
  "email" : "great.customer@email.com",
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "created_at": "2018-04-01T11:00:00-05:00",
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "referring_site": "http://www.nba.com/",
    "browser_ip": "111.111.111.111",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF"
  }
}

Customer Create

HTTP Method: POST

Endpoint: /customers/customer_create

Send an event when a new customer account is created

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

customer:

Customer required

An object containing information about the customer.

payment_details:

Array of PaymentDetails optional

The payment details associated with this customer. Should be passed as an array of nested payment_details objects. In cases where several payment methods are sent in the array, the first payment method shall correspond to the first billing address, etc.

billing_address:

Array of Address optional

The billing address associated with this customer. Should be passed as an array of nested billing_address objects. In cases where several billing addresses are sent in the array, the first billing address shall correspond to the first payment method, etc.

shipping_address:

Array of Address optional

The shipping address associated with this customer. Should be passed as an array of nested shipping_address objects.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2013-04-23T13:36:50-04:00",
    "referring_site": "http://www.nba.com/",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF"
  },
  "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",
    "orders_count": 0,
    "date_of_birth": "1994-03-01"
  },
  "payment_details": [
  ]
}

Customer Update

HTTP Method: POST

Endpoint: /customers/customer_update

Send Riskified whenever there is a change or update to a customer record. In case the customer was created before the integration with Riskified, just trigger customer_update and we’ll treat it as customer_create

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

password_changed:

Boolean required

Indicates whether the user changed their password

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

customer:

Customer required

An object containing information about the customer.

payment_details:

Array of PaymentDetails optional

billing_address:

Array of Address optional

shipping_address:

Array of Address optional

The shipping address associated with this customer. Should be passed as an array of nested shipping_address objects.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "password_changed": true,
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2013-04-23T13:36:50-04:00",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
    "referring_site": "http://www.nba.com/"
  },
  "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",
    "orders_count": 0,
    "date_of_birth": "1994-03-01"
  },
  "payment_details": [
  ]
}

Verification

HTTP Method: POST

Endpoint: /customers/verification

Send Riskified events relating to email verifications and associated verification actions.

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

Parameters

event_id:

String required

Riskified-assigned identifier of the associated login that pertains to the verification event.

verified_at:

DateTime required

Date and time of the verification event. Add corresponding timezone indication or ensure correct UTC standard format (ISO8601 -- 2020-07-24T20:55:00+2:00)

status:

Enum of Strings required

Indicates the status of the verification event. Must be one of the following values:

sent: applies when verification email is sent
success: applies when user confirms the action in the verification email
unauthorized: applies when user confirms they did not take the action in question in the verification email
failure: applies if there is an error with the verification token
expired: applies if verification token has expired

email:

String required

Email to which verification email is sent to.

verification_session_details:

VerificationSessionDetails recommended

An object containing basic information regarding the verification session.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
"event_id": "6ecb7620-168d-41ce-be8f-60522ec506a8",
"verified_at": "2020-06-25T13:53:19-04:00",
"email": "customer_email@test.com",
"status": "success",
"verification_session_details": {
  "cart_token": "68778783ad298f1c80c3bafcddeea02f",
  "browser_ip": "111.111.111.111"
  }
}

Logout

HTTP Method: POST

Endpoint: /customers/logout

Send logout event to Riskified

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2013-04-23T13:36:50-04:00",
    "referring_site": "http://www.nba.com/",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF"
  }
}

Redeem

HTTP Method: POST

Endpoint: /customers/redeem

Send event when a customer redeems any type of bonus, promo code, loyalty points, etc.

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

redeem_type:

String required

Redemption type
Must be one of the following values:

promo code
loyalty points
gift card
other

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "redeem_type": "promo code",
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "created_at": "2018-04-23T13:36:50-04:00",
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "referring_site": "http://www.nba.com/",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF"
  }
}

Wishlist Changes

HTTP Method: POST

Endpoint: /customers/wishlist

Send event when a customer adds or removes an item from wishlist

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

wishlist_action:

String required

Implies whether the item was added or removed from the wishlist
Must be one of the following:

add
remove

client_details:

ClientDetails required

Technical information regarding the customer's browsing session.

session_details:

SessionDetails required

Basic information regarding the account event

line_item:

LineItem required

An object containing information about an item (product) removed or added to the wishlist

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "wishlist_action": "add",
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "created_at": "2018-07-31T17:47+03:00",
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
    "referring_site": "http://www.nba.com/"
  },
  "line_item": {
    "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"
  }
}

Customer Reach-Out

HTTP Method: POST

Endpoint: /customers/contact

Send event when a customer contacts the merchant

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

Parameters

customer_id:

String required

A unique numeric identifier for the customer

order_id:

String optional

Order identifier required in case the inquiry was about a specific order

contact_method:

ContactMethod required

An object containing details on the method the customer used to reach out to the merchant.

client_details:

ClientDetails optional

Technical information regarding the customer's browsing session.

session_details:

SessionDetails optional

An object containing basic information regarding the session.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.

{
  "customer_id": "207119551",
  "order_id": "450789469",
  "contact_method": {
    "contact_method_type": "email",
    "email": "bob.norman@hostmail.com"
  },
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2013-04-23T13:36:50-04:00",
    "referring_site": "http://www.nba.com/",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF"
  }
}

Models

Order

id:

String required

The unique identifier for the order.

checkout_id:

String optional

The unique identifier of the Checkout that created this order.

name:

String optional

A secondary identifier for the order (if exists).

email:

String required

The customer's email address.

created_at:

DateTime required

The date and time when the order was first created.

currency:

String required

The three letter code (ISO 4217) for the currency used for the payment.

updated_at:

DateTime optional

The date and time when the order was last modified.

gateway:

String required

The payment gateway used.

browser_ip:

String required

The customer's browser IP address at the time of order checkout.

total_price:

Float required

The sum of all the prices of all the items in the order, taxes and discounts included (must be positive).

total_discounts:

Float required

The total amount of the discounts to be applied to the price of the order.

cancel_reason:

String optional

The reason why the order was cancelled.
If the order was not cancelled, this value is null.
If the order was cancelled, the value must be one of the following:

customer: The customer changed or cancelled the order.
fraud: The order was fraudulent.
inventory: Items in the order were not in inventory.
other: The order was cancelled for a reason not in the list above.

cart_token:

String optional

The session id that this order was created on, this value should match the session id value that is passed in the beacon JavaScript

device_id:

String optional

The mobile device identifier, which corresponds to a value extracted via the Riskified mobile beacon SDK.
Applicable only for native app platforms.

note:

String optional

The text of an optional note that a shop owner can attach to the order.

referring_site:

String required

The webpage from which the customer accessed the shop.

line_items:

Array of LineItem required

A list of line item objects, each one containing information about an item in the order.

passengers:

Array of Passenger optional

Applicable only for Merchants from the travel industry.
A list of passenger objects, each one containing information about a passenger in the order.

discount_codes:

Array of DiscountCode required

A list of discount code objects, each one containing information about an item in the order.

shipping_lines:

Array of ShippingLine required

A list of shipping line objects, each of which details the shipping methods used.

payment_details:

Array of PaymentDetails optional

A list of payment details. Should be passed as an array of nested payment_details objects. In cases where several payment methods are sent in the array, the first payment method shall correspond to the first billing address, etc.

customer:

Customer required

An object containing information about the customer.

billing_address:

Address required

The mailing address associated with the payment method.

shipping_address:

Address required

The mailing address to where the order will be shipped.

vendor_id:

String optional

A unique identifier representing the affiliated partner of selling vendor.
Examples of affiliated partners include: metasearch engine, white label partner.

vendor_name:

String optional

The name of the affiliated partner or selling vendor.
Examples of affiliated partners include: metasearch engine, white label partner.

vendor_integration_type:

String optional

The method by which order data is sent from affiliated partner to merchant systems.
Examples of affiliated partners include: metasearch engine, white label partner.

Recommended values include:

api: Customer places order on the affiliated partner site, and order is then sent to merchant system via an API call.
ui_redirect: Customer is redirected to merchant's domain to complete order submission

source:

String required

The platform that the order originated from.
Must be one of these:

desktop_web: Order was placed on the website, using a desktop device
mobile_web: Order was placed on the mobile website, using a mobile device
mobile_app: Order was placed on the mobile app, with no available info about the type of mobile device used
mobile_app_android: Order was placed on the mobile app, using an android mobile device
mobile_app_ios: Order was placed on the mobile app, using an iOS mobile device
web: Order was placed on the website, with no available info about the type of device used
chat: Order was placed using a chat service
third_party: Order was placed on a third party domain
phone: Order was placed over the phone by a call center support or sales agent
in_store: Order was placed on an in store online device
shopify_draft_order: Order was a Shopify draft order
unknown: Order's origin is unknown

contact_details:

ContactDetails optional

An object containing information about the customer's contact with the merchant when placing an order

order_type:

String optional

Usually omitted, set to 'test' when sending test orders (will be excluded from review).

submission_reason:

String optional

The underlying reason for submitting the order to review. Must be one of the following values:

failed_verification: Order failed (phone, email) verification.
rule_decision: Order was flagged by an automatic rule.
third_party: Order was flagged by a third-party service.
manual_decision: Order was flagged after manual review.
policy_decision Order was flagged by a non-fraud related rule.

decision:

DecisionDetails optional

The merchant decision details for the order.

client_details:

ClientDetails required

An object containing information about the browsing session.

charge_free_payment_details:

Charge Free Payment Details optional

A partial sum of an order as non risk (e.g. gift card amount)

{
	"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(array(
	'id' => '123',
	'name' => '#123',
	'email' => 'great.customer@example.com',
	'total_spent' => 200.0,
	'created_at' => '2010-01-10T11:00:00-05:00',
	'currency' => 'CAD',
	'updated_at' => '2010-01-10T11:00:00-05:00',
	'gateway' => 'mypaymentprocessor',
	'browser_ip' => '124.185.86.55',
	'total_price' => 113.23,
	'total_discounts' => 5.0,
	'cart_token' => '1sdaf23j212',
	'note' => 'Shipped to my hotel.',
	'referring_site' => 'google.com',
    'source' => 'desktop_web'
));

# LineItems
$lineItem1 = new Model\LineItem(array(
	'price' => 100,
	'quantity' => 1,
	'title' => 'ACME Widget',
	'product_id' => '101',
	'sku' => 'ABCD'
));

$lineItem2 = new Model\LineItem(array(
	'price' => 200,
	'quantity' => 4,
	'title' => 'ACME Spring',
	'product_id' => '202',
	'sku' => 'EFGH'
));
$order->line_items = array($lineItem1, $lineItem2);

# DiscountCodes
$discountCode = new Model\DiscountCode(array(
	'amount' => 19.95,
	'code' => '12'
));
$order->discount_codes = $discountCode;

# ShippingLines
$shippingLine = new Model\ShippingLine(array(
	'price' => 123.00,
	'title' => 'Free',
));
$order->shipping_lines = $shippingLine;

# PaymentDetails
$paymentDetails = array(new Model\PaymentDetails(array(
	'credit_card_bin' => '370002',
	'avs_result_code' => 'Y',
	'cvv_result_code' => 'N',
	'credit_card_number' => 'xxxx-xxxx-xxxx-1234',
	'credit_card_company' => 'VISA'
)));
$order->payment_details = $paymentDetails;

# Customer
$customer = new Model\Customer(array(
	'email' => 'email@address.com',
	'first_name' => 'Firstname',
	'last_name' => 'Lastname',
	'id' => '1233',
	'created_at' => '2008-01-10T11:00:00-05:00',
	'orders_count' => 6,
	'verified_email' => true
));
$order->customer = $customer;

# BillingAddress
$billingAddress = new Model\Address(array(
	'first_name' => 'John',
	'last_name' => 'Doe',
	'address1' => '108 Main Street',
	'company' => 'Kansas Computers',
	'country' => 'United States',
	'country_code' => 'US',
	'phone' => '1234567',
	'city' => 'NYC',
	'name' => 'John Doe',
	'address2' => 'Apartment 12',
	'province' => 'New York',
	'province_code' => 'NY',
	'zip' => '64155'
));
$order->billing_address = $billingAddress;

# ShippingAddress
$shippingAddress = new Model\Address(array(
	'first_name' => 'John',
	'last_name' => 'Doe',
	'address1' => '108 Main Street',
	'company' => 'Kansas Computers',
	'country' => 'United States',
	'country_code' => 'US',
	'phone' => '1234567',
	'city' => 'NYC',
	'name' => 'John Doe',
	'address2' => 'Apartment 12',
	'province' => 'New York',
	'province_code' => 'NY',
	'zip' => '64155'
));
$order->shipping_address = $shippingAddress;

var order = new Order(
                merchantOrderId: 132,
                email: "tester@exampler.com", 
                customer: customer, 
                paymentDetails: payments,
                billingAddress: billing,
                shippingAddress: shipping,
                lineItems: items,
                shippingLines: lines,
                gateway: "authorize_net",
                customerBrowserIp: "165.12.1.1",
                currency: "USD", 
                totalPrice: 100.60,
                source: "desktop_web",
                createdAt: DateTime.Now,
                updatedAt: DateTime.Now,
                discountCodes: discountCodes);

Order order = new Order();
order.setId("1234");
order.setEmail("great.customer@example.com");
order.setCreatedAt(new Date(114, 01, 10, 11, 00, 00));
order.setCurrency("CAD");
order.setUpdatedAt(new Date(114, 01, 10, 11, 00, 00));
order.setGateway("mypaymentprocessor");
order.setBrowserIp("124.185.86.55");
order.setTotalPrice(113.23);
order.setTotalDiscounts(5);
order.setCartToken("1sdaf23j212");
order.setReferringSite("google.com");
order.setSource("desktop_web");


# LineItems
order.setLineItems(Arrays.asList(
new LineItem(100, 1, "ACME Widget", 101, "ABCD"),
new LineItem(200, 4, "ACME Spring", 202, "EFGH")));

# DiscountCodes
order.setDiscountCodes(Arrays.asList(new DiscountCode(19.95, "12")));

# ShippingLines
order.setShippingLines(Arrays.asList(new ShippingLine(123, "free")));

# PaymentDetails
order.setPaymentDetails(Arrays.asList(new CreditCardPaymentDetails("370002", "y", "n", "xxxx-xxxx-xxxx-1234", "VISA")));

# Customer
Customer customer = new Customer(
    "email@address.com",
    "Firstname",
    "Lastname",
    "1233",
    new Date(),
    True,
    "6");
order.setCustomer(customer);
    
# BillingAddress
Address address = new Address("John", "Doe", "108 Main Street", "NYC", "1234567", "United States");
address.setCompany("Kansas Computers");
address.setCountryCode("US");
address.setName("John Doe");
address.setAddress2("Apartment 12");
address.setProvince("New York");
address.setProvinceCode("NY");
address.setZip("64155");
order.setBillingAddress(address);

# ShippingAddress
Address address = new Address("John", "Doe", "108 Main Street", "NYC", "1234567", "United States");
address.setCompany("Kansas Computers");
address.setCountryCode("US");
address.setName("John Doe");
address.setAddress2("Apartment 12");
address.setProvince("New York");
address.setProvinceCode("NY");
address.setZip("64155");
order.setBillingAddress(address);

Checkout

An object describing a pre-order checkout, prior to authorization by the payment gateway.

The Checkout object has exactly the same structure as an Order model, with one difference, noted below:

The id field holds the checkout identifier which is used to link between this Checkout model and its matching Order model.

Please note: After a checkout is successfully authorized and an order is created/submitted, the matching Order model's checkout_id field should hold the corresponding checkout identifier.

CheckoutOrder checkoutOrder = new CheckoutOrder(...);

OrderCheckout orderCheckout = new OrderCheckout(...);

$checkout = new Model\Checkout(array(
    ...
));

{
  "checkout": {
    ...
  }
}

Line Item

An object containing information about an item (product) in the order.
Travel or events tickets product should have the required general fields plus the travel/events industry fields respectively.

General:

price:

Float required

The price of the item.

requires_shipping:

Boolean optional

States whether or not the fulfillment requires shipping. This field is important for merchants dealing with digital goods.

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.

sku:

String optional

A unique identifier of the item in the fulfillment.

condition:

String optional

Description of the physical condition of the item, mostly relevant for used items.

seller:

Seller optional

public_username Details about the seller of the item, relevant for marketplace orders.

category:

String required

The category of the item.
For event tickets: the category of the event.

sub_category:

String optional

The sub-category of the item.
For event tickets: the sub-category of the event.

brand:

String required

The brand name of the item.

product_type:

String required

The product type should contain one of the following values:

physical: This is a tangible/physical product.
digital: This is a digital product (e.g. gift card).
travel: This is a travel industry product (e.g. flight ticket)
ride: This is a travel ride product (e.g. taxi)
event: This is an event industry product (e.g. concert ticket)
accommodation: This is an accommodation industry product (e.g. hotel room)

delivered_at:

Date optional

The planned delivery date of the product or item.

delivered_to:

String optional

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.

size:

String optional

The size of the item (e.g. shirt or shoe size)

registry_type:

String optional

The registry type must contain one of the following values:

wedding
baby
other

Digital Goods Industry:

sender_name:

String required

The sender name

display_name:

String optional

The display name

photo_uploaded:

Boolean required

Photo was uploaded?

photo_url:

String required

The photo url (if uploaded)

greeting_photo_url:

String optional

The greeting photo url (if exists)

message:

String required

The card's message

greeting_message:

String optional

The greeting message

card_type:

String optional

The card's type

card_sub_type:

String optional

The card's sub type

sender_email:

String optional

The sender's email

recipient:

Recipient optional

Recipient details

Travel Tickets Industry:

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_port_code:

String optional

Departure port code for the current leg. For flights: the 3 letter IATA airport code.

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_port_code:

String optional

Arrival port code for the current leg.
For flights: the 3 letter IATA airport code.

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:

DateTime 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

arrival_date:

DateTime optional

Date and time of arrival for the current leg.
Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T22:30:00-3:00

carrier_name:

String optional

The name of the carrier/company conducting the current leg.

carrier_code:

String required

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.
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.

ticket_class:

String optional

The class for this leg's ticket (e.g. business, economy, first)

transport_method:

String required

The method of transportation. Valid values are:

plane
ship
bus
train
tram

Travel Rides Industry:

pickup_date:

DateTime required

Ride pickup date.
Add corresponding timezone indication or ensure correct UTC standardization (ISO8601)
e.g. 2019-07-24T14:55:00+2:00

pickup_latitude:

Float optional

The latitude part of the pickup location coordinates.

pickup_longitude:

Float optional

The longitude part of the pickup location coordinates.

pickup_address:

Array of Address optional

Pickup location address.

dropoff_date:

DateTime optional

Ride dropoff date.
Add corresponding timezone indication or ensure correct UTC standardization (ISO8601)
e.g. 2019-07-24T15:25:00+2:00

dropoff_latitude:

Float optional

The latitude part of the dropoff location coordinates.

dropoff_longitude:

Float optional

The longitude part of the dropoff location coordinates.

dropoff_address:

Array of Address optional

Dropoff location address.

transport_method:

String optional

The transport method used, such as: taxi, car, scooter, etc.

price_by:

String optional

Pricing method: meter/fixed.

vehicle_class:

String optional

Vehicle class, such as: economy, executive, van, etc.

carrier_name:

String optional

Ride/taxi company name.

driver_id:

String optional

Driver ID/vehicle number (if self driven).

tariff:

String optional

Relevant tariff for the ride, such as: regular, night, 2, etc.

note_to_driver:

String optional

Additional message to driver.

meet_n_greet:

String optional

Airport/pickup meet and greet message.

cancellation_policy:

String optional

Reservation cancellation policy.

authorized_payments:

Float optional

Authorized pre-payment value for this ride (order currency).

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.

Events Tickets Industry:

section:

String optional

The assigned seating section in the venue.

event_date:

DateTime required

The date and time 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.

latitude:

Float optional

The latitude part of the coordinates of the event location.

longitude:

Float optional

The longitude part of the coordinates of the event location.

Accommodation Industry:

check_in_date:

DateTime required

The room check-in date.

check_out_date:

DateTime optional

The room check-out date.

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.

accommodation_type:

String optional

The accommodation type, such as hotel, B&B, etc.

room_type:

String optional

The room type, such as single, double, suite, etc.

number_of_guests:

Integer optional

The number of guests expected in the room.

rating:

String optional

The accommodation rating, as published on the merchant’s website

cancellation_policy:

String optional

The booking cancellation policy

$lineItem2 = new Model\LineItem(array(
	'price' => 200,
	'quantity' => 4,
	'title' => 'ACME Spring',
	'product_id' => '202',
	'sku' => 'EFGH'
));

[
  {
    "title": "IPod Nano - 8gb - green",
    "price": 199.00,
    "product_id": "632910392",
    "quantity": 1,
    "sku": "IPOD2008GREEN"
  },

  // Digital Goods product example using "requires_shipping":false
  {
    "title": "Giftcard",
    "price": 100.00,
    "product_id": 632910399,
    "quantity": 1,
    "sku": "giftcard1",
    "requires_shipping":false
  },

  // Accommodation Industry example using "requires_shipping":false
  {
    "product_type": "accommodation",
    "requires_shipping": false,
    "product_id": "hilton1234standard0123456",
    "title": "Catalonia Honeymoon Suite with breakfast included",
    "category": "hotel accommodation",
    "price": 2314.98,
    "quantity": 1,
    "title": "hilton",
    "room_type": "Honeymoon Suite",
    "city": "Riviera Maya",
    "country_code": "MX",
    "check_in_date": "2016-04-14T14:00:00-0",
    "check_out_date": "2016-05-02T14:00",
    "rating": "4",
    "number_of_guests": 3,
    "cancellation_policy": "none",
    "accommodation_type": "b&b"
  }
]

LineItem lineItem = new LineItem(title: "ACME Spring",
                                 price: 200.0,
                                 quantityPurchased: 4,
                                 productId: 202,
                                 sku: "EFGH");

LineItem lineItem = new LineItem(100, 1, "ACME Widget", 101, "ABCD");

// For travel industries:
TravelLineItem travelLineItem = new TravelLineItem(340, 1, "Flight from Israel to France", "211", "B11", 1, 1);
travelLineItem.setDeparturePortCode("LLBG");
travelLineItem.setDepartureCountryCode("IL");
travelLineItem.setDepartureCity("Tel Aviv");
travelLineItem.setDepartureDate(getDate(2014, Calendar.MARCH, 5, 12, 30, 0));
travelLineItem.setArrivalPortCode("LBG");
travelLineItem.setArrivalCountryCode("FR");
travelLineItem.setArrivalCity("Paris");
travelLineItem.setArrivalDate(getDate(2014, Calendar.MARCH, 5, 15, 30, 0));
travelLineItem.setTicketClass("economy");
travelLineItem.setCarrierCode("AF");
travelLineItem.setCarrierName("Air France");
travelLineItem.setRequiresShipping(false);
travelLineItem.setTransportMethod("bus");

Passenger

Applicable for merchants of the travel industry only.
Passenger information for each passenger included in this order.
Each passenger is assumed to be assigned to all tickets in the order (all line-items).

first_name:

String required

The first name of the passenger.

last_name:

String required

The last name (surname) of the passenger.

date_of_birth:

Date required

Date of birth for the passenger. Date part only (ISO8601).

nationality_code:

String required

The 2 letter country code (ISO 3166-1 alpha-2) matching the passenger's nationality country.

insurance_type:

String optional

The passenger's insurance type/plan for his trip.

insurance_price:

Float optional

The passenger's insurance plan price matching the order currency.

document_number:

String required

The used document (Passport,ID,Visa) identification number.

document_type:

String required

The document type used for identification of the passenger (one of [Passport,ID,Visa]).

document_issue_date:

Date optional

The issuing date of the passenger document (date part only using ISO8601 format).

document_expiration_date:

Date optional

The expiration date of the passenger document (date part only using ISO8601 format).

passenger_type:

String optional

Type of passenger - (Senior/Adult/Child)

{
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "2015-07-28",
  "nationality_code": "US",
  "insurance_type": "Silver",
  "insurance_price": 20.11,
  "document_number": "2020202020",
  "document_type": "Passport",
  "document_issue_date": "2015-01-01",
  "document_expiration_date": "2025-01-01",
  "passenger_type": "Adult"
}

Passenger passenger = new Passenger("john","smith");
passenger.setDateOfBirth(getDate(1988, Calendar.MARCH, 5));
passenger.setNationalityCode("IL");
passenger.setInsuranceType("full");
passenger.setInsurancePrice(11);
passenger.setDocumentNumber("123456");
passenger.setDocumentType("Passport");
passenger.setDocumentIssueDate(getDate(1988, Calendar.MARCH, 5));
passenger.setDocumentExpirationDate(getDate(2020, Calendar.MARCH, 5));
passenger.setPassengerType("Adult");

Discount Code

Discount codes that were applied to the order.

amount:

Float required

The amount of the discount.

code:

String required

The code of the discount.

$discountCode = new Model\DiscountCode(array(
	'amount' => 19.95,
	'code' => '12'
));

{
	"amount": 10.00,
	"code": "TENOFF"
}

var discountCode = new DiscountCode(moneyDiscountSum: 7, code: "1");

DiscountCode discountCodes = new DiscountCode(19.95, "12");

Shipping Line

Details the shipping methods used.

price:

Float required

The price of the shipping method.

title:

String required

The title of the shipping method.

code:

String optional

Code of the shipping method.

company:

String optional

The name of the shipping company.

$shippingLine = new Model\ShippingLine(array(
	'price' => 123.00,
	'title' => 'Free',
));

{
	"code": "FreeShipping2018",
	"price": 0.00,
	"title": "Free Shipping",
	"company": "USPS"
}

var shippingLine = new ShippingLine(price: 2,title: "Ship",code: "A22F");

new ShippingLine(123, "free");

Payment Details

An object containing information about the payment (the fields are dependant on the payment type - credit card / paypal).

Credit card details:

credit_card_bin:

String required

The issuer identification number (IIN), formerly known as bank identification number (BIN) of the customer's credit card.
Made up of the first 6 digits of the credit card number.

avs_result_code:

String required

Address Verification System response code.
The code is a single letter, see this chart for more.
Required only in Order Model, optional on Account Actions Customer Create / Customer Update events.

cvv_result_code:

String required

Card Verification Value response code.
The code is a single letter, see this chart for more.
Required only in Order Model, optional on Account Actions Customer Create / Customer Update events.

credit_card_number:

String required

The credit card number, with leading digits redacted with Xs.
(only the last four digits are not hidden)

credit_card_token:

String optional

The token returned from the credit card company.

credit_card_company:

String required

The company who issued the customer's credit card.

cardholder_name:

String optional

Name of the cardholder.

stored_payment_created_at:

DateTime optional

Date and time (ISO8601) when the payment method was saved to the customer's account.

stored_payment_updated_at:

DateTime optional

Most recent date and time (ISO8601) when the saved payment method was updated by the customer.

installments:

Integer optional

Number of payment installments.

authorization_id:

String optional

Unique identifier of the payment transaction as granted by the processing gateway.

mid:

String optional

The merchant account id at the payment gateway

_type:

String required for PSD2 advise implementation

Payment method type. Must be one of the following values:

credit_card
paypal

id:

String optional

A unique identifier of the payment detail object within the array of payment details. When this is not provided, a default running number will be attached to each element in the payment details array.

gateway:

String required for PSD2 advise implementation

The payment gateway that processes the order

acquirer_bin:

String optional

The acquirer identification number (IIN), formerly known as bank identification number (BIN) of the merchant's acquirer

authorization_error:

Authorization Error optional

Model describing why a checkout was denied authorization. (use when calling checkout_denied endpoint)

authentication_result:

Authentication Result optional

Model describing authentication 3ds result by the issuer (use after calling advise endpoint).

Paypal details:

payer_email:

String required

The payer email assigned to his paypal account as received from paypal

payer_status:

String required

The payer status as received from paypal

payer_address_status:

String required

The payer address status as received from paypal

protection_eligibility:

String required

The merchants protection eligibility for the order as received from paypal.

payment_status:

String optional

The payment status as recieved from paypal.

pending_reason:

String optional

The pending reason received from paypal.

authorization_id:

String optional

The authorization Id received from paypal

mid:

String optional

The merchant account id at the payment gateway

_type:

String required for PSD2 advise implementation

Payment method type. Must be one of the following values:

credit_card
paypal

id:

String optional

gateway:

String required for PSD2 advise implementation

The payment gateway that processes the order

acquirer_bin:

String optional

The acquirer identification number (IIN), formerly known as bank identification number (BIN) of the merchant's acquirer

authorization_error:

Authorization Error optional

Model describing why a checkout was denied authorization. (use when calling checkout_denied endpoint)

authentication_result:

Authentication Result optional

Model describing authentication 3ds result by the issuer (use after calling advise endpoint).

Bank Wire / ACH details:

account_number:

String required

The last 4 digits of the account number

routing_number:

String required

The routing number (ABA) of the customer's bank

Credit card:

$paymentDetails = new Model\PaymentDetails(array(
	'credit_card_bin' => '370002',
	'avs_result_code' => 'Y',
	'cvv_result_code' => 'N',
	'credit_card_number' => 'xxxx-xxxx-xxxx-1234',
	'credit_card_company' => 'VISA'
));

-------------------------------------------

Paypal:

$paymentDetails = new Model\PaymentDetails(array(
	'authorization_id' => 'd3j555kdjgnngkkf3_1',
    'payer_email' => 'customer1@service-mail.com',
    'payer_status' => 'verified',
    'payer_address_status' => 'unconfirmed',
    'protection_eligibility' => 'Eligible',
    'payment_status' => 'completed',
    'pending_reason' => 'None'
));

Credit card:

{
	"avs_result_code": "Y",
	"credit_card_bin": "123456",
	"credit_card_company": "Visa",
	"credit_card_number": "XXXX-XXXX-XXXX-4242",
	"cvv_result_code": "M",
	"stored_payment_created_at": "2019-08-21T12:50:00+00:00",
	"stored_payment_updated_at": "2020-01-13T12:51:00+00:00"
}

---------------------------------------

Paypal:

{
    "authorization_id": "d3j555kdjgnngkkf3_1",
    "payer_email": "customer1@service-mail.com",
    "payer_status": "verified",
    "payer_address_status": "unconfirmed",
    "protection_eligibility": "Eligible",
    "payment_status": "completed",
    "pending_reason": "None"
}

---------------------------------------

Bank Wire / ACH:

{
    "account_number": "XXXXXXXXXX1234",
    "routing_number": "123456789"
}

Credit card:

new CreditCardPaymentDetails(
    avsResultCode: "Y",
    cvvResultCode: "n",
    creditCardBin: "124580",
    creditCardCompany: "Visa",
    creditCardNumber: "XXXX-XXXX-XXXX-4242"
);

 ---------------------------------------

Paypal:

new PaypalPaymentDetails(
    paymentStatus: "Authorized",
    authorizationId: "ajbfshjkfdkskf_32_aa",
    payerEmail: "payer@gmail.com",
    payerStatus: "verified",
    payerAddressStatus: "unconfirmed",
    protectionEligibility: "Partly Eligibile",
    pendingReason: "Review"
);

Credit card:

new CreditCardPaymentDetails("370002", "y", "n", "xxxx-xxxx-xxxx-1234", "VISA");

-------------------------------------------

Paypal:

new PaypalPaymentDetails("customer1@service-mail.com", "verified", "unconfirmed", "Eligible");

Customer

An object containing information about the customer.

email:

String required

The customer's email address.

verified_email:

Boolean required

Indicates whether the merchant verified the customer’s email

verified_email_at:

DateTime optional

Date and time of customer email verification

first_name:

String required

The customer's first name.

last_name:

String required

The customer's last name.

id:

String required

The customer’s ID in the merchant’s system

created_at:

DateTime required

The timestamp of the initial registration of the customer's account in the merchant's systems

updated_at:

DateTime optional

The timestamp of the most recent update to the customers account

note:

String optional

Any notes related to the customer in the merchant's system.

total_spent:

Float optional

The total amount spent by the customer across all their orders in the merchant's system.

group_name:

String optional

The name of the group the customer belongs to in the merchant's system.

accepts_marketing:

Boolean optional

Indicates whether the customer accepts marketing.

last_order_id:

String optional

The ID of the last order purchased by the customer.

tags:

String optional

Any tags related to the customer in the merchant's system.

buy_attempts:

Integer optional

The number of attempts the customer has made to purchase an item in the merchant's system.

sell_attempts:

Integer optional

The number of attempts the customer has made to sell an item in the merchant's system.

first_purchase_at:

DateTime optional

The timestamp for the first purchase of this user on the merchant’s website

orders_count:

Integer optional

The number of orders made by the customer on the site in the past

account_type:

String optional

The customer’s account type. Recommended values include:

guest
registered
premium
business
If customer logged in via SSO, enter platform used here (i.e. Facebook, Google, etc.)

phone:

String optional

The customer’s phone number

verified_phone:

Boolean optional

Indicates whether the customer's phone number was verified

verified_phone_at:

DateTime optional

Date and time of customer phone number verification.

date_of_birth:

Date optional

Customer’s date of birth. Date part only (ISO8601).

gender:

String optional

The customer's gender

Male
Female

user_name:

String optional

Required in case the site user name is not the email address

social:

Array of Social optional

An array of Social Details, each of which lists a known social identity of the customer

linked_accounts:

Integer optional

Specifies how many different accounts the customer making the order is linked to in your current database (via payment data or any other method of your choosing). This integer value can be sent to Riskified to customize into the decisioning engine and setup rules around.

phone_mandatory:

Boolean optional

Indicates whether phone was a required field during registration.
This parameter is only relevant for Account Actions.

referrer_customer_id:

String optional

The customer ID of the customer that referred the current customer to the merchant website.
This parameter is only relevant for Account Actions.

social_signup_type:

String optional

In case the user signed up with any social network. Must be one of the following:

facebook
google
linkedin
twitter
yahoo
other

This parameter is only relevant for Account Actions.

address:

Array of Address optional

The address of the customer.

$customer = new Model\Customer(array(
	'email' => 'email@address.com',
	'first_name' => 'Firstname',
	'last_name' => 'Lastname',
	'id' => '1233',
	'created_at' => '2008-01-10T11:00:00-05:00',
	'orders_count' => 6,
	'verified_email' => true
));

{
	"created_at": "2013-04-23T13:36:50-04:00",
	"email": "bob.norman@hostmail.com",
	"first_name": "Bob",
	"id": 207119551,
	"last_name": "Norman",
	"note": null,
	"orders_count": 0,
	"verified_email": true,
	"phone_mandatory": false,
	"referrer_customer_id": "207119512",
	"social_signup_type": "facebook",
	"account_type": "registered"
}

var customer = new Customer(
                firstName: "John",
                lastName: "Doe",
                id: 405050606,
                ordersCount: 4,
                email: "test@example.com",
                verifiedEmail: true,
                createdAt: new DateTime(2013, 12, 8, 14, 12, 12),
                notes: "No additional info");

Customer customer = new Customer(
    "email@address.com",
    "Firstname",
    "Lastname",
    "1233",
    new Date(),
    True,
    "6");

Client Details

Technical information regarding the customer's browsing session.

accept_language:

String optional

List of two-letter language codes sent from the client.

user_agent:

String optional

The full User-Agent sent from the client.
Required for Account Action endpoints.

{
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)"
  }
}

Social Details

An object containing information about the customer.

network:

String required

The name of the social network.

public_username:

String required

The customer's public username.

community_score:

Integer optional

Aggregate community score for the customer.

profile_picture:

String optional

URL of the customer's profile picture.

email:

String optional

Customer's email address registered on the social network.

bio:

String optional

Short biography of the customer on the social network.

account_url:

String required

Direct URL to the customer's profile page on the social network.

following:

Integer optional

Number of users following the customer on the social network.

followed:

Integer optional

Number of users followed by the customer on the social network.

posts:

Integer optional

Number of posts published by the customer on the social network.

id:

String required

The customer's profile id.

auth_token:

String optional

The authentication token of the user.

social_data:

Object optional

The user data from the network.

{
  "network": "internal",
  "public_username": "donnie7",
  "community_score": 68,
  "profile_picture": "http://img.com/abc.png",
  "email": "donnie@mail.com",
  "bio": "avid mountaineer...",
  "account_url": "http://shop.com/user/donnie7",
  "following": 231,
  "followed": 56,
  "post": 17,
  "id": "123",
  "auth_token": "a1k4jf"
}

$social = new Model\SocialDetails(array(
  'network' => 'twitter',
  'public_username' => 'donnie7',
  'community_score' => 68,
  'profile_picture' => 'http://img.com/abc.png',
  'email' => 'donnie@mail.com',
  'bio' => 'avid mountaineer...',
  'account_url' => 'http://shop.com/user/donnie7',
  'following' => 231,
  'followed' => 56,
  'posts' => 10
))

SocialDetails socialDetails = new SocialDetails(network: "Facebook",
                                                publicUserName: "john.smith");
socialDetails.AccountUrl = "http://www.facebook.com/john.smith";
socialDetails.Email = "john.smith@gmail.com";
socialDetails.ProfilePicture = "http://img.com/profile123412.gif";
socialDetails.Bio = "john smith is ...";
socialDetails.Following = 120;
socialDetails.Followed = 28;

SocialDetails social = new SocialDetails("Facebook", "john.smith", "http://www.facebook.com/john.smith");
social.setEmail("john.smith@facebook.com");
social.setProfilePicture("http://img.com/pic121333.gif");

Seller

An object containing information about the seller (relevant for marketplaces).

customer:

Customer required

A Customer object representing the seller.

correspondence:

Integer optional

Number of messages sent between the customer and the seller.

price_negotiated:

Boolean optional

True if the seller and customer negotiated the price between themselves.

starting_price:

Float optional

The original price of the order, prior to any negotiation between seller and customer.

{
  "customer": { "id" : 27346, ... },
  "correspondence": 33,
  "price_negotiated": true,
  "starting_price" : 177.3
}

$seller = new Model\Seller(array(
  'customer' => $sellerCustomer,
  'correspondence' => 77,
  'price_negotiated' =>  false,
  'starting_price' => 100.3
));

Seller seller = new Seller(customer: customer,correspondence: 1, priceNegotiated: true, startingPrice: 120);

Seller seller = new Seller(customer);
seller.setPriceNegotiated(true);
seller.setStartingPrice(400);

Address

Object containing information about a billing or shipping address.

first_name:

String required

The first name of the person associated with the address.

last_name:

String required

The last name of the person associated with the address.

address1:

String required

The street address of the billing address.

address2:

String optional

An optional additional field for the street address.

company:

String optional

The company of the person associated with the address.

country:

String required

The name of the country of the address.

country_code:

String optional

The two-letter abbreviation of the country of the address.
see this chart for code mappings.

phone:

String required

The phone number at the address.

additional_phone:

String optional

Additional phone number at the address.

verified_phone:

Boolean optional

Indicates whether the provided phone number was verified

city:

String required

The city of the address.

province:

String optional

The name of the state or province of the address.

province_code:

String optional

The two-letter abbreviation of the state or province of the address.

zip:

String required

The zip or postal code of the address.

latitude:

Float optional

The latitude coordinates of the address.

longitude:

Float optional

The longitude coordinates of the address.

$address = new Model\Address(array(
	'first_name' => 'John',
	'last_name' => 'Doe',
	'address1' => '108 Main Street',
	'company' => 'Kansas Computers',
	'country' => 'United States',
	'country_code' => 'US',
	'phone' => '1234567',
	'city' => 'NYC',
	'name' => 'John Doe',
	'address2' => 'Apartment 12',
	'province' => 'New York',
	'province_code' => 'NY',
	'zip' => '64155'
));

{
  "address1": "Chestnut Street 92",
  "address2": "",
  "city": "Louisville",
  "company": null,
  "country": "United States",
  "country_code": "US",
  "first_name": "Bob",
  "last_name": "Norman",
  "name": "Bob Norman",
  "phone": "555-625-1199",
  "province": "Kentucky",
  "province_code": "KY",
  "zip": "40202"
}

var address = new AddressInformation(firstName: "Ben",
                                     lastName: "Rolling",
                                     address1: "27 5th avenue",
                                     city: "Manhattan",
                                     country: "United States",
                                     countryCode: "US",
                                     phone: "5554321234",
                                     address2: "Apartment 5",
                                     zipCode: "54545",
                                     province: "New York",
                                     provinceCode: "NY",
                                     company: "IBO",
                                     fullName: "Ben Philip Rolling");

Address address = new Address("John", "Doe", "108 Main Street", "NYC", "1234567", "United States");
        address.setCompany("Kansas Computers");
        address.setCountryCode("US");
        address.setName("John Doe");
        address.setAddress2("Apartment 12");
        address.setProvince("New York");
        address.setProvinceCode("NY");
        address.setZip("64155");
        order.setShippingAddress(address);

Refund Details

An object containing information about a partial refund.

refund_id:

String required

Unique identifier for this refund

sku:

String required

A unique identifier of the item in the refund

refunded_at:

DateTime required

When the refund was issued to the customer

amount:

Float required

Total amount of refund, specified as a positive number

currency:

String required

The 3-letter code (ISO 4217) for the currency used for the payment.
Defaults to USD

reason:

String required

Text note detailing the reason this refund was issued

RefundDetails refund =
    new RefundDetails(refundedAt: DateTime.Now,
                      sku: "ABCD004245",
                      amount: 5.3,
                      currency: "USD",
                      reason: "Customer partly refunded on shipping fees");

$refund = new Model\RefundDetails(array(
                'refund_id' => '1235',
                'sku' => "ABCD004245"
                'amount' => 10.5,
                'refunded_at' => '2014-01-10T11:00:00Z',
                'currency' => 'USD',
                'reason' => 'Rebate'
));

{
    "refund_id" : "1235",
    "sku" : "ABCD004245",
    "amount" : 10.5,
    "refunded_at" : "2014-01-10T11:00:00Z",
    "currency" : "USD",
    "reason" : "Rebate"
}

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

Contact Details

An object containing information about the customer's contact with the merchant when placing an order

contact_type

String required

The type of contact by the customer.
Must be one of the following:

email
phone
facebook
website_chat
other

phone

String optional

The customer's phone number.
Mandatory if contact_type = "phone"

String optional

The customer's email address.
Mandatory if contact_type = "email"

facebook_account_url

String optional

The customer's facebook account url.
Mandatory if contact_type = "facebook"

agent_name

String optional

The name of the handling agent

agent_id

String optional

The id of the handling agent

conversation_duration

Integer optional

The duration of the conversation in seconds (either until it is over or checkout is executed)

waiting_duration

Integer optional

Duration of waiting time before getting actual agent to answer, in seconds

conversation_language

String optional

The language of the conversation

agent_impression

String optional

The overall impression the agent had towards the customer's legitimacy.
Must be one of the following:

positive
neutral
negative

inbound_outbound

String optional

The direction of the contact initiation: was it made by the customer or by the agent?
Must be one of the following:

inbound
outbound

customer_verified_by

String optional

The way the agent verified the customer details (if the customer is registered or had past orders)

{
  "contact_details" : {
    "contact_type" : "email",
    "email" : "great.customer@email.com",
    "agent_name" : "Al Doe",
    "agent_id" : "567",
    "conversation_duration" : 345,
    "waiting_duration" : 123,
    "agent_impression" : "neutral",
    "inbound_outbound" : "inbound",
    "customer_verified_by" : "cc_4_digits"
  }
}

Charge Free Payment Details

Charge free payment details, where a merchant can pass a partial sum of an order as non risk (e.g. gift card amount)

gateway:

String required

The non risk gateway (e.g. giftcard)

amount:

Float required

The non risk amount

Authorization Error

An object describing the failed result of an authorization attempt by a payment gateway.

created_at:

DateTime required

When the checkout was denied by the payment gateway.

error_code:

String required

The authorization error code received from the payment gateway.

message:

String required

The authorization response description. Please be sure to send the raw values received from the payment gateway. Below are examples for illustrative purposes:

incorrect_number
invalid_number
invalid_expiry_date
invalid_cvc
expired_card
incorrect_cvc
incorrect_zip
incorrect_address
card_declined
processing_error
call_issuer
pick_up_card
risk_system_declined

AuthorizationError authorizationError = new AuthorizationError(new Date(114, 01, 10, 11, 00, 00));
authorizationError.setErrorCode("201");
authorizationError.setMessage("invalid number for credit card");

AuthorizationError authorizationError = new AuthorizationError(
                                    createdAt: new DateTime(2013, 12, 8, 14, 12, 12),
                                    errorCode: "2004",
                                    message: "credit card expired.");

$authorization_error =  new Model\AuthorizationError(array(
    'created_at' => '2008-01-10T11:00:00-05:00',
    'error_code' => '2002',
    'message' => 'Limit Exceeded'
));

{
  "authorization_error": {
    "created_at": "2008-01-10T11:00:00-05:00",
    "error_code": "2001",
    "message": "insufficient funds"
  }
}

Fulfillment Details

An object describing the final fulfillment status of an order.

fulfillment_id:

String required

Unique identifier of this fulfillment attempt.

created_at:

DateTime required

When the order was fulfilled.

status:

String optional

The fulfillment status, valid values are:

success The fulfillment was successful.
cancelled The fulfillment was cancelled.
error There was an error with the fulfillment request.
failure The fulfillment request failed.

line_items:

Array of LineItem optional

A list of each line item in the attempted fulfillment.

tracking_company:

String required

The name of the shipping company, valid values are:

usps USPS.
ups UPS.
fedex Fedex.
dhl_express DHL / DHL Express.
dhl_ecommerce DHL Global Mail.
dhl_ecommerce DHL eCommerce.
canada_post Canada Post.
other If the company is not listed, insert the name.

tracking_numbers:

String required

A list of shipping numbers, provided by the shipping company.

tracking_urls:

String optional

The URLs to track the fulfillment.

message:

String optional

Additional textual description regarding the fulfillment status.

receipt:

String optional

Information about the receipt.

List<FulfillmentDetails> fulfillments = new ArrayList<FulfillmentDetails>();
FulfillmentDetails fulfilmentDetails = new FulfillmentDetails("33", new Date(114, 01, 10, 11, 00, 00), "success");

fulfilmentDetails.setLineItems(Arrays.asList(
        new LineItem(100, 1, "ACME Widget", 101, "ABCD"),
        new LineItem(200, 4, "ACME Spring", 202, "EFGH")));

fulfilmentDetails.setTrackingCompany("UPS");
fulfilmentDetails.setTrackingNumbers("11X63b");

fulfillments.add(fulfilmentDetails);
FulfillmentOrder fulfillmentOrder = new FulfillmentOrder("1235", fulfillments);

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

$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'
    )))
));

{
  "fulfillment": {
    "fulfillment_id": "12asf123",
    "created_at": "2013-04-23T13:36:50-04:00",
    "status": "success",
    "line_items": [
      {
        "title": "IPod Nano - 8gb - green",
        "price": 199.00,
        "product_id": "632910392",
        "quantity": 1,
        "sku": "IPOD2008GREEN",
        "fulfillment_service": "manual",
        "fulfillment_status" : "success"
      }
    ],
    "tracking_company": "fedex",
    "tracking_numbers": "abc123",
    "tracking_urls": "http://fedex.com/track?q=abc123",
    "message": "fulfillment message",
    "receipt": "authorization: 765656"
  }
}

Decision Details

An object describing the decision made by the merchant of an order.
Notice: decision details does not hold Riskified's decision on an order.

external_status:

String required

The external status, valid values are:

approved The order was approved.
declined The order was declined without being submitted to Riskified or despite Riskified recommendation to approve.
checkout The order is in checkout stage.
cancelled The order was cancelled (The order was not fulfilled due to non-fraud reasons such as not in stock, customer cancelled, etc).
declined_fraud The order was not fulfilled due to fraud related reasons.
chargeback_fraud The order was chargeback with fraud related reasons.
chargeback_not_fraud The order was chargeback with no fraud related reasons.
declined_business The order was declined by the merchant for business reasons.

decided_at:

DateTime required

When the order was decided.

reason:

String optional

A reason for the decision.

amount:

Float optional

The amount the decision is relevant on.

currency:

String optional

The three letter code (ISO 4217) for the currency used for the payment.

notes:

String optional

Free text for describing the decision.

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);

OrderDecision orderDecision = new OrderDecision(merchantOrderId,
            new DecisionDetails(ExternalStatusType.ChargebackFraud, DateTime.Now, "stolen credit card."));

{
  "decision": {
    "external_status": "chargeback_fraud",
    "reason": "credit card was stolen",
    "decided_at": "2013-04-23T13:36:50-04:00",
    "notes": "check identity next time",
    "amount": 120.00,
    "currency": "USD"
  }
}

Chargeback Details

An object containing the chargeback details as received from the gateway or the issuer

id:

String required

The chargeback unique identifier as received from the gateway/acquirer on the chargeback's notice.
Mandatory when multiple chargebacks per order scenario is possible.

chargeback_at:

DateTime required

The chargeback date, as received from the acquirer

chargeback_currency:

String required

The chargeback currency, ISO 4217

chargeback_amount:

Float required

The chargeback amount as stated in the chargeback notice, specified as a positive number

reason_code:

String required

The chargeback reason code, as received from the acquirer

type:

String 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

reason_description:

String optional

The chargeback reason description, as received from the acquirer

mid:

String optional

The merchant account id at the payment gateway

arn:

String optional

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 optional

Credit card brand: VISA, Mastercard, AMEX, JCB, etc.

respond_by:

DateTime optional

Last date to challenge CHB

card_issuer:

String optional

The card issuer

fee_amount:

Float optional

The chargeback fee amount

fee_currency:

String optional

The chargeback fee currency

cardholder:

String optional

The identifier of the person who submitted the CHB, as it appears on the chargeback notice

message:

String optional

Optional issuer message

{
  "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"
  }
}

Dispute Details

An object containing information about the dispute as sent to the gateway or issuer

case_id:

String required

Dispute identifier as defined by the issuer/gateway

status:

String optional

One of the following:

won
lost

Note: we expect to update the api when the dispute status changes

disputed_at:

DateTime optional

When was the dispute sent

expected_resolution_date:

DateTime optional

When should we expect a decision from the issuer (60-75 days usually)

dispute_type:

String optional

One of the following:

first_dispute
second_dispute
arbitrary_court

Note: we expect to update the api when the dispute type changes

{
  "dispute_details" : {
    "case_id" : "a1234",
    "status" : "won",
    "disputed_at" : "2017-06-01",
    "expected_resolution_date" : "2017-07-15",
    "dispute_type" : "first_dispute"
  }
}

Authentication Result

An object describing authentication 3DS result by the issuer.

created_at:

DateTime optional

The date and time of the authentication.

eci:

String required

The Electronic Commerce Indicator (eci), a number that indicates authentication result and liability shift. Must be one of the following values:

"00"
"01"
"02"
"05"
"06"
"07"

liability_shift:

Boolean required

A field indicating if the liability for the transaction was shifted to the Issuer.

cavv:

String optional

Cardholder Authentication Verification Value (cavv) response codes, indicating authentication result and reason.

trans_status:

String optional

The transStatus value as defined in the 3D Secure 2 specification. Must be one of the following values:

trans_status_reason:

String optional

The transStatusReason value as defined in the 3D Secure 2 specification. Must be one of the following values:

"01"
"02"
"03"
"04"
"05"
"06"
"07"
"08"
"09"
"10"

"11"
"12"
"13"
"14"
"15"
"16"
"17"
"18"
"19"
"20"

"21"
"22"
"23"
"24"
"25"
"26"
"27"
"80"
"99"

{
  "authentication_result": {
    "created_at": "2018-01-10T11:00:00-05:00",
    "eci": "07",
    "liability_shift": true,
    "cavv": "05",
    "trans_status": "Y",
    "trans_status_reason": "01"
  }
}

Recipient

An object containing information about the recipient of digital goods.

email:

String optional

The recipient's email address.

phone:

String optional

The recipient's phone number.

social:

Social optional

Recipient's known social identity.


$recipient = new Model\Recipient(array(
'email' => '1@gmail.com',
'phone' => '1234567',
'social' => new Model\SocialDetails(array(
'network' => 'internal',
'public_username' => 'donnie7',
'id' => "123",
'community_score' => 68,
'profile_picture' => 'http://img.com/abc.png',
'email' => 'donnie@mail.com',
'bio' => 'avid mountaineer...',
'account_url' => 'http://shop.com/user/donnie7',
'following' => 231,
'followed' => 56,
'posts' => 10
))));

{
  "recipient": {
    "email": "1@gmail.com",
    "phone": "1234567",
    "social": {
      "network": "internal",
      "public_username": "donnie7",
      "id": "123",
      "community_score": 68,
      "profile_picture": "http://img.com/abc.png",
      "email": "donnie@mail.com",
      "bio": "avid mountaineer...",
      "account_url": "http://shop.com/user/donnie7",
      "following": 231,
      "followed": 56,
      "posts": 10
    }
  }
}

var recipientSocial = new SocialDetails(
                                        network: "Facebook",
                                        publicUsername: "john.smith",
                                        accountUrl: "http://www.facebook.com/john.smith");

var recipient = new Recipient(
    email: "aa@bb.com",
    phone: "96522444221",
    social: recipientSocial);

Login Status

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

login_status_type:

Enum of Strings required

Indicates the success or failure of a login attempt.
Must be one of the following values:

success
failure

failure_reason:

Enum of Strings optional

The reason for the unsuccessful login, required if login_status_type = 'failure'.
Must be one of the following values:

wrong password
captcha
disabled account
nonexistent account
other
expired

{
  "login_status": {
    "login_status_type": "failure",
    "failure_reason": "captcha"
  }
}

Contact Method

An object containing details on the method the customer used to reach out to the merchant.

contact_method_type:

String required

How the customer contacted the merchant. Recommended values include:

email
website_chat
facebook
phone
other

email:

String optional

Required in case contacted merchant via email.

phone:

String optional

Required in case contacted merchant by phone.

facebook_account_url:

String optional

Required in case contacted merchant via Facebook.

number_of_messages:

String optional

When contacted merchant via chat or Facebook, the number of messages the customer sent during the conversation.

chat_subject:

String optional

In case contacted merchant via chat, the subject of the conversation.

{
  "contact_method": {
    "contact_method_type": "email",
    "email": "example@gmail.com"
  }
}

Session Details

An object containing basic information regarding the session.

created_at:

DateTime required

The date and time of the request.

cart_token:

String required

The session id at the time that the user is on the login webpage, prior to authentication attempt.
This value should match the session id value that is passed in the beacon JavaScript.

browser_ip:

String required

The customer's browser IP address during the session.

source:

Enum of Strings required

The platform that the session originated from.
Must be one of the following values:

desktop_web: Session originated on the website, using a desktop device
mobile_web: Session originated on the mobile website, using a mobile device
web: Session originated on the website, with no available info about the type of device used
mobile_app: Session originated on the mobile app, using a mobile device
other: The session's origin is unknown

device_id:

String optional

The mobile device identifier, which corresponds to a value extracted via the Riskified mobile beacon SDK.
Applicable only for native app platforms.

referring_site:

String optional

The webpage from which the customer accessed the shop.

{
  "session_details": {
    "created_at": "2018-04-01T11:00:00-05:00",
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
    "referring_site": "http://www.nba.com/"
  }
}

$session = new Model\SessionDetails(array(
                'created_at' => "2018-04-01T11:00:00-5:00",
                'cart_token' => "68778783ad298f1c80c3bafcddeea02f",
                'browser_ip' => "111.111.111.111",
                'source' => "mobile_app",
                'device_id' => "01234567-89ABCDEF-01234567-89ABCDEF",
                'referring_site' => "http://www.nba.com"
));

SessionDetails session =
    new SessionDetails(createdAt: DateTime.Now,
                      cartToken: "68778783ad298f1c80c3bafcddeea02f",
                      browserIp: "111.111.111.111",
                      source: "mobile_app",
                      deviceId: "01234567-89ABCDEF-01234567-89ABCDEF",
                      referringSite: "http://www.nba.com/");

SessionDetails session = new SessionDetails();
session.setCreatedAt("2018-04-01T11:00:00-5:00");
session.setCartToken("68778783ad298f1c80c3bafcddeea02f");
session.setBrowserIp("111.111.111.111");
session.setSource("mobile_app");
session.setDeviceId("01234567-89ABCDEF-01234567-89ABCDEF");
session.setReferringSite("http://www.nba.com/");

Verification Session Details

An object containing basic information regarding the verification session.

cart_token:

String recommended

The session id at the time of the verification event.

browser_ip:

String optional

Required if verification.status is NOT: sent
The customer's browser IP address at the time of the verification event.

{
"verification_session_details": {
  "cart_token": "68778783ad298f1c80c3bafcddeea02f",
  "browser_ip": "111.111.111.111"
  }
}

Notifications

Riskified can send an automated decision notification when approving/declining an order to the endpoint of your choosing. Start out by specifying the endpoint in your account settings.

Riskified expects to find a HTTP/1.1 compliant web server listening at the endpoint. You can test your setup by initiating test decision notifications via the 'Test API' functionality in the settings page.

A decision notification is sent as a JSON encoded payload in a standard HTTP POST request, and is identical in structure to the common endpoint responses.

Each decision notification also includes a X-RISKIFIED-HMAC-SHA256 header that can be used to validate the integrity of the notification's payload. This header is generated using the same method described under Authentication.

Upon an HTTP error (any return code other than 2xx) Riskified will reattempt to send the notification in the following frequency: 10 times in gaps of 5 minutes each and then 10 more times in gaps of 1 hour each.

Note: Shop URL is available as a notification parameter depending on your account’s setup; please contact your Integration Engineer or Account Manager if you have questions on this.
It is a non-best-practice to use shop url in the notifications programmatically as this field will be not be supported long term in API notifications

JSON keys

Order

id:

Unique ID of order being acted upon.

status:

Textual status describing the result of the operation.

description:

Detailed description of the operation, if exists.

old_status:

Textual status describing the original status of the order.

Example JSON payload on order approval notification:


{
"order" : {
    "id" : "950406",
    "description" : "Reviewed and approved by Riskified",
    "status" : "approved",
    "old_status": "submitted"
}
}

Store Front Beacon

The Riskified store front beacon is a snippet of code embedded in the pages of your webstore. It is important that the code be added into the header or footer of your website so data is collected from every page. It loads asynchronously and does not affect page load time.

Implementation steps:

Copy the JavaScript snippet below, and replace the highlighted variables with:
- Your store domain - the same domain you use for logging into the app.
- Session ID - the unique identifier created when a user arrives at your website. The session ID must be created at the start of the user’s visit to your store, and not just when the shopping cart is created.
Paste the modified beacon JavaScript snippet into the HTML of your website.
To verify that the beacon has been successfully added, go to the API developer section within your Riskified account.

Single Page Application (SPA)

The Riskified Store Front Beacon supports sites whose content is loaded dynamically without traditional full page loads. To track dynamically loaded content as distinct pageviews you can send a pageview hit to Riskified's Beacon and specify the page name as a String type parameter.

RISKX.go('/new-page')

For Single Page Applications that may need to change the value of the session ID (due to user inactivity, for instance), specify the newly generated session ID as a String type parameter.

RISKX.go(url) // sends a beacon reading with the session ID
//sent in the < script > tag
RISKX.setSid('B') // changes the session ID to 'B'
RISKX.go(url) // sends a beacon reading with the session ID 'B'

                            <script type="text/javascript">
//<![CDATA[
(function() {
  function riskifiedBeaconLoad() {
    var store_domain = '{{ DOMAIN }}';
    var session_id = 'SESSION ID GOES HERE - as passed to Order->cart_token';
    var url = ('https:' == document.location.protocol ? 'https://' : 'http://')
      + "c.riskified.com?shop=" + store_domain + "&sid=" + session_id;
    var s = document.createElement('script');
    s.type = 'text/javascript';
    s.async = true;
    s.src = url;
    var x = document.getElementsByTagName('script')[0];
    x.parentNode.insertBefore(s, x);
  }
  if (window.attachEvent)
    window.attachEvent('onload', riskifiedBeaconLoad)
  else
    window.addEventListener('load', riskifiedBeaconLoad, false);
})();
//]]>
</script>