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:
    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
    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",
      "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:
    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:
    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:
    Model describing why a checkout was denied authorization. (use when calling checkout_denied endpoint)
    authentication_result:
    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
    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:
    Model describing why a checkout was denied authorization. (use when calling checkout_denied endpoint)
    authentication_result:
    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"
    email
    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:
    • Y
    • N
    • U
    • A
    • C
    • D
    • R
    • I
    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.
      • Note: The session ID should also be passed to Riskified in the cart_token field.
    • 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://')
          + "beacon.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>