Checkout

To request a recommendation at this endpoint use either the Checkout Pre-auth or Checkout Post-auth checkpoint.

Jump to Response

POST api.ravelin.com/v2/checkout

timestamp integer required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

eventType string optional

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$
customerId string important

The ID of the customer navigating through the checkout process. Mutually exclusive with customer.

customer object important

The customer navigating through the checkout process. Mutually exclusive with customerId.

Show definition
tempCustomerId string optional

A temporary ID for a customer when the real account ID has yet to be minted. This must eventually be sent in conjunction with a real customer ID to migrate the data into the full customer account.

order object important

The order describing the goods or services the customer wants to, or has attempted to buy.

Show definition
paymentMethod object important

A primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId and paymentMethods. One of the following:

One of the following:

card: A credit or debit card.

Show definition

paymentMethodCipher: An encrypted payment method, containing the full card details encrypted via a Ravelin SDK.

Show definition

cash: The customer is paying in cash, or a cash-based payment method.

Show definition

bankaccount: Bank Accounts.

Show definition

paypal: PayPal payments.

Show definition

credit: This payment method type should be used for any payments made using credit that a customer has with the merchant.

Show definition

invoice: This payment method should be used whenever the merchant provides credit to the customer.

Show definition

wallet: A digital wallet payment method.

Show definition

fromTransaction: Refer to the payment method used by a named transaction. For usage examples, see Saving payment methods after checkout and Associating refunds with payment methods.

Show definition

directdebit: Direct Debits. - deprecated.

Show definition

banktransfer: Bank Transfers. - deprecated.

Show definition

Others - deprecated.

Show definition

Removal: Used for marking a saved payment method as removed from the account.

Show definition
paymentMethods array important

One or more payment methods to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethodId.

paymentMethodId string important

The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethods.

transaction object important

An attempt to charge a payment method to pay or be refunded for an order. Mutually exclusive with transactions.

Show definition
transactions array important

One or more attempts to charge a payment method to pay or be refunded for an order. Mutually exclusive with transaction.

Show definition
voucherRedemption object optional

A voucher that is being used to pay for some of the order.

Show definition
voucherRedemptions array optional

Any vouchers that are being used to pay for some of the order.

Show definition
device object important

The device used by the customer to trigger this update.

Show definition
deviceId string important

The ID of the device used by the customer to trigger this update.

nationalIdentifications array optional

Identifications are used by online customers to verify their real-world identity. These forms of identification can be authenticated with government authorities or authorised third-parties to confirm the credentials are legitimate. Extra steps should be taken to confirm the customer is the legitimate holder of these credentials.

Show definition
POST https://api.ravelin.com/v2/checkout?score=checkoutPreAuth HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "name": "John Smith",
    "telephone": "+447000000001",
    "telephoneCountry": "GBR"
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "type": "phone",
    "manufacturer": "google",
    "model": "Pixel XL",
    "os": "android",
    "language": "en-US",
    "ipAddress": "81.152.92.84"
  },
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "price": 1500,
    "currency": "GBP",
    "market": "emea",
    "country": "GBR",
    "marketCity": "london",
    "items": [
      {
        "sku": "0001",
        "name": "Margherita Pizza",
        "quantity": 1,
        "price": 1500
      }
    ],
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "shipping": {
      "daysToDispatch": 7,
      "method": "STANDARD",
      "destinationType": "HOME",
      "carrier":"DHL"
    }
  },
  "paymentMethods": [
    {
      "paymentMethodId": "pm-abc123",
      "instrumentId": "fp_abc123",
      "methodType": "card",
      "scheme": "visa",
      "cardBin": "535522",
      "cardLastFour": "0001",
      "expiryMonth": 7,
      "expiryYear": 2020,
      "nameOnCard": "John Smith",
      "billingAddress": {
        "addresseeName": "John Smith",
        "street1": "123 High Street",
        "city": "London",
        "country": "GBR",
        "postalCode": "E1 1AA"
      }
    }
  ],
  "transactions": [
    {
      "transactionId": "123-abc-XYZ",
      "paymentMethodId": "pm-abc123",
      "time": 1512828988826,
      "amount": 1000,
      "currency": "GBP",
      "type": "auth",
      "gateway": "example-gateway"
    }
  ]
}

Response

status integer

The HTTP response status code.

timestamp integer

A unix timestamp indicating when we finished handling the request.

message string

If an error has occurred, a description of the error.

data object

Contains our recommendations and related details.

Show definition
{
  "status": 200,
  "timestamp": 1512828988826,
  "data": {
    "action": "ALLOW",
    "score": 12,
    "source": "RAVELIN",
    "customerId": "abc-123-ZYZ",
    "scoreId": "2bf39d-d1299-31",
    "transactionOptimisation": {
      "transactionId": "123-abc-XYZ",
      "action": "AUTHENTICATE",
      "exemption": "TRANSACTION_RISK_ANALYSIS",
      "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
      "actionSource": "CLIENT_RULE",
      "rules": {
        "triggered": [
          {
            "ruleId": 1,
            "ruleVersion": 1,
            "action": "AUTHENTICATE",
            "exemption": "TRANSACTION_RISK_ANALYSIS",
            "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
            "triggered": true,
            "state": "active"
          }
        ]
      }
    },
    "warnings": [
      {
        "class": "customer-not-found",
        "help": "https://developer.ravelin.com/api/warnings/#customer-not-found",
        "msg": "Customer \"abc-123-ZYZ\" not found."
      }
    ]
  }
}

Response Versions

You can request additional details in the response by specifying a response version in the Accept request header.

The fields which are returned in the different versions are marked in the Checkout Response API reference above.

Each response version will also return all the fields from the versions before it. For example, Response Version 2 will include the fields in Response Version 1.

The request headers for the different response versions are shown below:

Response Version 1: Accept: application/vnd.ravelin.score.v1+json

Response Version 2: Accept: application/vnd.ravelin.score.v2+json

Response Version 3: Accept: application/vnd.ravelin.score.v3+json

Feedback

© Ravelin Technology Ltd. All rights reserved