Overview Authentication Errors Responses Actions Checkout Create Checkout Denied Create Submit Update Cancel/Full-Refund Partial-Refund Fulfill Decision Chargeback Historical

Models

Order Checkout Line Item Passenger Discount Code Shipping Line Payment Details Customer Client Details Social Details Seller Address Refund Details Charge Free Payment Details Authorization Error Fulfillment Details Decision Details Chargeback Details Dispute Details Recipient 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.

API testing and development are done on Riskifed's Sandbox environment at:
https://sandbox.riskified.com
You can create a Sandbox account by signing up for "API Integration" on our website
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
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.
$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.

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

Example response for successful execution:


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

Example response with warnings:


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

Example response for failed execution:


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

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(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 payments = new CreditCardPaymentDetails(
                avsResultCode: "Y",
                cvvResultCode: "n",
                creditCardBin: "123456",
                creditCardCompany: "Visa",
                creditCardNumber: "XXXX-XXXX-XXXX-4242",
                creditCardToken: "2233445566778899");
payments.AuthorizationError = authorizationError;

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 = 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": {
      "avs_result_code": "Y",
      "credit_card_bin": "123456",
      "credit_card_company": "Visa",
      "credit_card_number": "XXXX-XXXX-XXXX-4242",
      "cvv_result_code": "M",
      "authorization_error": {
        "created_at": "2008-01-10T11:00:00-05:00",
        "error_code": "card_declined",
        "message": "Card was denied."
      }
    }
  }
}

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.

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" : {
        ...
    }
}
$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" : {
        ...
    }
}
$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" : {
        ...
    }
}
$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 cancelled
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",
                "amount" : 10.5,
                "refunded_at" : "2014-01-10T11:00:00Z",
                "currency" : "USD",
                "reason" : "Rebate"
            },
            {
                "refund_id" : "1238",
                "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.setCurrency(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

Notify that an existing order has completed fulfillment, covering both successful and failed attempts.

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

Refer to the Fulfillment Details 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 Fulfillment Details 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.

Parameters

id:
String required
The unique identifier of the order the decision is on.
decision:
DecisionDetails required
The decision details for the order.
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": "chargeback_fraud",
    "reason":"credit card was stolen",
    "decided_at": "2013-04-23T13:36:50-04:00",
    "notes":"check identity next time",
    "amount":"120.0",
    "currency":"USD"
    }
}
}
                        

Chargeback

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
Includes shipping information (required only for tangible goods)
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",
                    feeAmount: 20,
                    feeCurrency: "USD",
                    cardIssuer: "Wells Fargo Bank",
                    gateway: "braintree",
                    cardholder: "John Smith",
                    message: "Cardholder disputes quality/ mischaracterization of service/merchandise. Supply detailed refute of these claims, along with any applicable/supporting doc");

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: "pending",
                            issuerPocPhoneNumber: "+1-877-111-1111",
                            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("pending");

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' => 'pending'
));

$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": {
        "chargeback_at" : "2016-06-10T15:46:51Z",
        "chargeback_currency" : "USD",
        "chargeback_amount" : 50.5,
        "reason_code" : "4863",
        "reason_description" : "Transaction not recognised",
        "chargeback_type" : "cb",
        "mid" : "t_123",
        "credit_card_company" : "visa",
        "respond_by" : "2016-09-01",
        "arn" : "a123456789012bc3de45678901f23a45",
        "fee_amount" : "20",
        "fee_currency" : "USD",
        "card_issuer" : "Wells Fargo Bank",
        "gateway" : "braintree",
        "cardholder" : "John Smith",
        "message" : "Cardholder disputes quality/ mischaracterization of service/merchandise. Supply detailed refute of these claims, along with any applicable/supporting doc"
    },
    "fulfillment" : {
        "fulfillment_id": "12asf123",
        "created_at": "2013-04-23T13:36:50-04:00",
        "status": "success",
        "tracking_company" : "fedex",
        "tracking_numbers": "abc123"
    },
    "dispute_details" : {
        "dispute_type" : "first_dispute",
        "case_id" : "a1234",
        "status" : "pending",
        "issuer_poc_phone_number" : "+1-877-111-1111",
        "disputed_at" : "2016-06-01",
        "expected_resolution_date" : "2016-07-15",
        "dispute_type" : "first_dispute"
        }
    }
}

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

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.
closed_at:
DateTime optional
The date and time when the order was closed.
currency:
String required
The three letter code (ISO 4217) for the currency used for the payment.
updated_at:
DateTime required
The date and time when the order was last modified.
gateway:
String required
The payment gateway used.
browser_ip:
String required
The IP address of the browser used by the customer when placing the order.
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 will 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 required
The session id that this order was created on, this value should match the session id value that is passed in the beacon JavaScript
note:
String optional
The text of an optional note that a shop owner can attach to the order.
referring_site:
String required
The website that the customer clicked on to arrive at 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:
PaymentDetails required
An object containing information about the payment.
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
An unique id representing the selling vendor.
vendor_name:
String optional
The name of the selling vendor.
source:
String optional
The source of where the order was received from (example: website, mobile or phone).
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:
Client Details 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 = 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',
	'closed_at' => null,
	'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,
	'cancel_reason' => 'inventory',
	'cart_token' => '1sdaf23j212',
	'note' => 'Shipped to my hotel.',
	'referring_site' => 'google.com'
));

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

# PaymentDetais
$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'
));
$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;
{
	"cancel_reason": null,
	"cancelled_at": null,
	"cart_token": "68778783ad298f1c80c3bafcddeea02f",
	"closed_at": null,
	"created_at": "2008-01-10T11:00:00-05:00",
	"currency": "USD",
	"email": "bob.norman@hostmail.com",
	"gateway": "authorize_net",
	"id": "450789469",
	"total_discounts": 0.00,
	"total_price": 409.94,
	"updated_at": "2008-01-10T11:00:00-05:00",
	"note": "some note made by the shop’s stuff member",
	"browser_ip": null,
	"discount_codes": [
		{
			"amount": 10.00,
			"code": "TENOFF"
		}
	],
	"line_items": [
		{
			"title": "IPod Nano - 8gb - green",
			"price": 199.00,
			"product_id": 632910392,
			"quantity": 1,
			"sku": "IPOD2008GREEN"
		}
	],
	"shipping_lines": [
		{
			"code": "Free Shipping",
			"price": 0.00,
			"title": "Free Shipping"
		}
	],
	"payment_details": {
		"avs_result_code": null,
		"credit_card_bin": null,
		"credit_card_company": "Visa",
		"credit_card_number": "XXXX-XXXX-XXXX-4242",
		"cvv_result_code": null
	},
	"billing_address": {
		"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"
	},
	"shipping_address": {
		"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"
	},
	"customer": {
		"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
	}
}
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,
                createdAt: DateTime.Now,
                updatedAt: DateTime.Now,
                discountCodes: discountCodes);
Order order = new Order();
order.setId("1234");
order.setName("#1234");
order.setEmail("great.customer@example.com");
order.setCreatedAt(new Date(114, 01, 10, 11, 00, 00));
order.setClosedAt(null);
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.setAdditionalEmails(Arrays.asList("my@email.com", "second@email.co.uk"));
order.setNote("Shipped to my hotel.");
order.setReferringSite("google.com");


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

# PaymentDetais
order.setPaymentDetails(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:
int 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)
  • event: This is an event industry product (e.g. concert ticket)
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)

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 (ISO8601)
arrival_date:
DateTime optional
Date and time of arrival for the current leg (ISO8601).
carrier_name:
String optional
The name of the carrier/company conducting the current leg.
carrier_code:
String optional
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

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.
$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
  }
]
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.
$shippingLine = new Model\ShippingLine(array(
	'price' => 123.00,
	'title' => 'Free',
));
{
	"code": "Free Shipping",
	"price": 0.00,
	"title": "Free Shipping"
}
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.
cvv_result_code:
String required
Card Verification Value response code.
The code is a single letter, see this chart for more.
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_company:
String required
The company who issued the customer's credit card.
authorization_id:
String optional
Unique identifier of the payment transaction as granted by the processing gateway.
authorization_error:
Model describing why a checkout was denied authorization. (use when calling checkout_denied 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
authorization_error:
Model describing why a checkout was denied authorization. (use when calling checkout_denied endpoint)
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"
}

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

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"
}
Credit card:

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

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

Paypal:

var payments = 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.
first_name:
String required
The customer's first name.
last_name:
String required
The customer's last name.
id:
String required
A unique numeric identifier for the customer.
created_at:
DateTime required
The date and time when the customer record was created.
first_purchase_at:
DateTime optional
The date and time when the customer first purchased items in the shop.
orders_count:
int required
The number of orders placed by this customer to a shop.
verified_email:
Boolean required
Whether the customer's email was verified.
account_type:
String optional
The type of the customer's account (free/premium).
social:
Array of Social optional
List of the customer's known social identities.
$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
}
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.
{
  "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:
int 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:
int optional
Number of users following the customer on the social network.
followed:
int optional
Number of users followed by the customer on the social network.
posts:
int 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:
int 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.
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 optional
The zip or postal code 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
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,
                      amount: 5.3,
                      currency: "USD",
                      reason: "Customer partly refunded on shipping fees");
$refund = new Model\RefundDetails(array(
                'refund_id' => '1235',
                'amount' => 10.5,
                'refunded_at' => '2014-01-10T11:00:00Z',
                'currency' => 'USD',
                'reason' => 'Rebate'
));
{
    "refund_id" : "1235",
    "amount" : 10.5,
    "refunded_at" : "2014-01-10T11:00:00Z",
    "currency" : "USD",
    "reason" : "Rebate"
}
RefundDetails refundDetail = new RefundDetails();
refundDetail.setRefundId("refund_001");
refundDetail.setAmount(33.12);
refundDetail.setCurrency("USD");
refundDetail.setCurrency(new Date());
refundDetail.setReason("Product Missing");

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:
String 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, valid values are:
  • 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
message:
String optional
The authorization response description.
AuthorizationError authorizationError = new AuthorizationError("invalid_number", new Date(114, 01, 10, 11, 00, 00));
authorizationError.setMessage("Checkout denied reason: invalid number for creadit card.");
AuthorizationError authorizationError = new AuthorizationError(
                                    createdAt: new DateTime(2013, 12, 8, 14, 12, 12),
                                    errorCode: AuthorizationErrorCode.IncorrectNumber,
                                    message: "credit card expired.");
$authorization_error =  new Model\AuthorizationError(array(
    'created_at' => '2008-01-10T11:00:00-05:00',
    'error_code' => 'card_rejected'
));

{
    "created_at": "2008-01-10T11:00:00-05:00",
    "error_code": "card_declined",
    "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 required
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 optional
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 optional
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_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 fullfilled due to non-fraud reasons such as not in stock, customer cancelled, credit card was declined etc).
  • declined_fraud The order was not fullfilled 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."));

{
"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.0"
"currency":"USD"
}
                            

Chargeback Details

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

id:
String optional
The chargeback notice id (if applicable)
chargeback_at:
DateTime required
The chargeback date, as received form the acquirer
chargeback_currency:
String required
The chargeback currency, ISO 4217
chargeback_amount:
float required
The chargeback amount as stated in the chargeback notice
reason_code:
string required
The chargeback reason code, as received from the acquirer
reason_description:
String required
The chargeback reason description, 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.
  • cb2 Second Chargeback.
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 required
Last date to challenge CHB
fee_amount:
float required
The chargeback fee amount
fee_currency:
String optional
The chargeback fee currency
card_issuer:
String optional
The card issuer
gateway:
String optional
The payment gateway who processed the order
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": {
"chargeback_at" : "2016-06-10T15:46:51Z",
"chargeback_currency" : "USD",
"chargeback_amount" : 50.5,
"reason_code" : "4863",
"reason_description" : "Transaction not recognised",
"chargeback_type" : "cb",
"mid" : "t_123",
"credit_card_company" : "visa",
"respond_by" : "2016-09-01",
"arn" : "a123456789012bc3de45678901f23a45",
"fee_amount" : "20",
"fee_currency" : "USD",
"card_issuer" : "Wells Fargo Bank",
"gateway" : "braintree",
"cardholder" : "John Smith",
"message" : "Cardholder disputes quality/ mischaracterization of service/merchandise. Supply detailed refute of these claims, along with any applicable/supporting doc"
}
                        

Dispute Details

An object containing the dispute details as sent to the gateway or issuer

case_id:
string required
Dispute identifier as defined by the issuer/gateway
status:
String required
One of the following:
  • candidate
  • ineligible
  • pending
  • won
  • lost
Note: we expect to update the api when the dispute status changes
disputed_at:
DateTime required
When was the dispute sent
expected_resolution_date:
DateTime required
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
issuer_poc_phone_number:
String required
Credit card issuer or gateway provider phone number

{
"dispute_details" : {
"dispute_type" : "first_dispute",
"case_id" : "a1234",
"status" : "pending",
"issuer_poc_phone_number" : "+1-877-111-1111",
"disputed_at" : "2016-06-01",
"expected_resolution_date" : "2016-07-15",
"dispute_type" : "first_dispute"
}
}
                        

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

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.

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