timestamp
required
|
|
integer |
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).
|
1512828988826
|
eventType
optional
|
|
string |
An eventType should identify what event in your system triggered this API call.
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$
|
|
customerId
important
|
|
string |
The ID of the customer navigating through the checkout process.
Mutually exclusive with customer.
|
"abc-123-ZYZ"
|
customer
important
|
|
object |
The customer navigating through the checkout process. Mutually
exclusive with customerId.
Show definition
|
|
Name |
|
Type |
Description |
Example |
customerId
required
|
|
string |
The unique identifier of the customer. If your system allows anonymous
checkout then we recommend making this the customer's email address.
|
"abc-123-ZYZ"
|
registrationTime
important
|
|
integer |
The time that the customer registered. If this value is unknown, you
can set it to 'now' - Ravelin will retain the earliest value you have
sent for this customer ID.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
email
important
|
|
string |
The email address of the customer.
|
"jsmith123@example.com"
|
emailVerifiedTime
optional
|
|
integer |
The time at which the customer verified their email, usually by
following a link back to your website from an email you sent to
their address.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
name
important
|
|
string |
The full name of the customer. If you have the name split into parts,
consider familyName and givenName instead.
|
"John Smith"
|
familyName
important
|
|
string |
The surname/last name of the customer. If you do not have the name
split into parts, consider name instead.
|
"Smith"
|
givenName
important
|
|
string |
The first/given names of the customer. If you do not have the name
split into parts, consider name instead.
|
"John"
|
telephone
important
|
|
string |
The telephone number of the customer. Best in
E.164 format with an
international dialing code.
|
"+16045555555"
|
telephoneVerifiedTime
optional
|
|
integer |
The time at which the customer verified their telephone number,
usually by confirming a code from an SMS you sent to the number.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
telephoneCountry
optional
|
|
string |
The country the telephone number directs to. Note that the country is
not an adequate replacement for the international dialing code in the
Dominican Republic or Puerto Rico where multiple dialing codes are
used.
A ISO 3166-1 Alpha 3
or Alpha 2 country code.
|
"DOM"
|
passwordBcrypted
optional
|
|
string |
The bcypted form of the password for this user. By its nature, the bcrypt operation is slow. Consider using passwordHashed if this is too slow for you.
|
|
passwordHashed
optional
|
|
string |
The SHA256 form of the password for this user. This must be base64 encoded.
|
|
password
optional
|
|
string |
The plaintext password for the user. We never store the raw password but for security we recommend using one of the hashing options instead of the plaintext option.
|
|
passwordChanged
optional
|
|
boolean |
Set to true on events where the password has been changed, false or omit otherwise.
|
|
tags
optional
|
|
object |
The tags to set or unset. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.
|
|
location
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
username
deprecated
|
|
string |
The username the customer would log in with.
|
|
gender
deprecated
|
|
string |
The gender of the customer.
|
|
balance
deprecated
|
|
object |
The wallet contents of the customer, in the form of an object whose
keys are currencies and values the amount held in that currency, in
the currency's basic units.
|
|
banned
deprecated
|
|
boolean |
Whether the customer is banned in your systems.
|
|
country
deprecated
|
|
string |
The home country for this customer. Doesn't change when the customer is briefly abroad. See markets.
|
|
market
deprecated
|
|
string |
The logical region in which this customer exists. See markets.
Pattern: ^[0-9a-z-]*$
|
|
marketCity
deprecated
|
|
string |
The logical city in which this customer exists. See markets.
Pattern: ^[0-9a-z-]*$
|
|
|
tempCustomerId
optional
|
|
string |
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.
|
"abc-123-XYZ"
|
order
important
|
|
object |
The order describing the goods or services the customer wants to, or has
attempted to buy. (See orders.)
Show definition
|
|
Name |
|
Type |
Description |
Example |
orderId
required
|
|
string |
A unique identifier for this order.
|
"abcde12345-ZXY"
|
creationTime
important
|
|
integer |
The time that the order was submitted by the customer. Used in reporting.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
app
important
|
|
object |
The mobile or web app that this order was submitted on. Used for
segmenting business analytics and creating app-specific risk profiles.
Show definition
|
|
Name |
|
Type |
Description |
Example |
name
optional
|
|
string |
The name or brand of the app, used to segment orders. Use the name
that customer sees when installing and using the app, or the
website title. Shouldn't repeat the platform or domain.
|
"Our App Lite"
|
platform
optional
|
|
string |
One of:
ios , android , web , or mobile-web .
|
"web"
|
domain
optional
|
|
string |
The domain from the URL of the web app, using the characters a-z0-9-. .
Pattern: ^[a-z0-9-\.]+$
|
"us.brand.com"
|
|
status
important
|
|
|
The stage of order in the purchase and delivery flow. Used in reporting.
One of the following:
|
{
"stage": "pending",
"actor": "merchant"
}
|
|
•
Pending: The order is yet to be submitted for payment and processing, and you are yet to decide whether you will accept the order.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
pending .
|
"pending"
|
actor
optional
|
|
string |
The actor who caused the status change e.g. buyer, merchant.
|
"merchant"
|
|
|
•
Accepted: The customer has submitted the order and you intend to fulfill it. This stage is useful if you provide the goods and services before taking payment. If you take payment immediately, you can consider the order fulfilled.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
accepted .
|
"accepted"
|
actor
optional
|
|
string |
The actor who accepted the order.
|
"merchant"
|
|
|
•
Failed: Something went wrong, and the order can no longer be fulfilled.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
failed .
|
"failed"
|
reason
required
|
|
string |
Description of why the order has failed.
One of:
payment_declined , seller_rejected , or system_error .
|
"payment_declined"
|
actor
optional
|
|
string |
The actor who caused the status change e.g. buyer, merchant.
|
"buyer"
|
|
|
•
Cancelled: The order has been cancelled.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
cancelled .
|
|
reason
required
|
|
string |
Description of why the order has been cancelled.
One of:
buyer , seller , merchant , ravelin , or other_fraud_tool .
|
"buyer"
|
actor
optional
|
|
string |
The actor who caused the status change e.g. buyer, merchant.
|
"buyer"
|
|
|
•
Fulfilled: The goods have been provided to the customer and payment has been successfully taken.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
fulfilled .
|
"fulfilled"
|
actor
optional
|
|
string |
The actor who caused the status change e.g. buyer, merchant.
|
"buyer"
|
|
|
•
Refunded: The order has been refunded.
Show definition
|
Name |
|
Type |
Description |
Example |
stage
required
|
|
string |
Only:
refunded .
|
"refunded"
|
reason
required
|
|
string |
A description of why the order has been refunded.
One of:
returned , complaint , or ato .
|
"returned"
|
actor
optional
|
|
string |
The actor who caused the status change e.g. buyer, merchant.
|
"buyer"
|
|
price
important
|
|
integer |
The total price for this order, including delivery and taxes, in the currency's basic units. This price should always equal the sum of each items', tickets', and rooms' price times quantity.
|
10000
|
currency
important
|
|
string |
The currency of the price for this order as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
country
important
|
|
string |
The country the order should be attributed to for reporting and risk bucketing. See markets. Should reflect the country segmentation that you use for your reporting internally, whether that's by billing or shipping address, for example.
|
"GBR"
|
market
important
|
|
string |
The country-group market the customer belongs to. E.g. 'southamerica', 'europe', 'emea'. Used for reporting and risk bucketing. See markets.
Pattern: ^[0-9a-z-]*$
|
"emea"
|
marketCity
important
|
|
string |
The city that the customer belongs to. Used for reporting and risk bucketing. See markets.
Pattern: ^[0-9a-z-]*$
|
"london"
|
category
optional
|
|
string |
The highest level category that applies to this order as a whole, e.g.
the type of service provided. See item.category to describe
individual order items.
|
"delivery"
|
to
important
|
|
object |
The delivery or drop-off location of the order. For taxis, can be the
requested drop-off location to begin, and updated to the actual
drop-off location once known.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
from
optional
|
|
object |
The pick-up location of the order. For taxis, can be the requested
pick-up location to begin, and updated to the actual pick-up location
once known.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
items
important
|
|
array |
The line items of the order, describing what the customer is
purchasing. Including, but not limited to, products, services,
journeys, tips, taxes, and delivery fees.
Show definition
|
|
Name |
|
Type |
Description |
Example |
quantity
required
|
|
integer |
Number of copies of this item that are present in the basket (set to 0 to remove).
|
1
|
sku
optional
|
|
string |
A merchant specific identifier for an item or a service.
|
"delivery"
|
name
optional
|
|
string |
The name of the product or service that is being purchased.
|
"Delivery Fee"
|
price
important
|
|
integer |
|
10000
|
currency
optional
|
|
string |
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
brand
optional
|
|
string |
The name of the brand that the item is from.
|
|
upc
optional
|
|
string |
The name of the Universal Item Code.
|
|
category
optional
|
|
string |
The highest level category that this item is sold in.
|
"delivery"
|
subcategory
optional
|
|
string |
A category that this item is sold in.
|
|
executionTime
optional
|
|
integer |
The scheduled time for the service described by this item.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
eventTicket
optional
|
|
object |
If the item being purchased is a ticket for an event, associate the ticket and event information here.
Show definition
|
|
Name |
|
Type |
Description |
Example |
ticket
required
|
|
object |
The ticket information for this event.
Hide definition
|
|
Name |
|
Type |
Description |
Example |
ticketId
required
|
|
string |
A unique identifier for this ticket.
|
"ticket_123"
|
ticketType
optional
|
|
string |
A short human-readable description of the type of ticket.
|
"Adult Single Day Pass"
|
validFromTime
optional
|
|
integer |
Timestamp at which this ticket is valid from.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480330580
|
validUntilTime
optional
|
|
integer |
Timestamp at which this ticket is valid until.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580
|
refundable
optional
|
|
boolean |
Whether this ticket is refundable or not.
|
|
|
event
required
|
|
object |
The event the ticket is granting access to. This could be a access to an event, an attraction, or any other activity the customer is purchasing a ticket to attend.
Hide definition
|
|
Name |
|
Type |
Description |
Example |
eventId
required
|
|
string |
A unique identifier for this event.
|
"event_123"
|
category
required
|
|
string |
The category that best described the type of event.
One of:
adventure , attraction , conference , convention , culinary , business , family , festival , health , live show , music , party , social , sport , or other .
|
"music"
|
venue
required
|
|
object |
The location the event will take place.
Hide definition
|
|
Name |
|
Type |
Description |
Example |
name
required
|
|
string |
|
"Royal Albert Hall"
|
location
required
|
|
object |
Hide definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
|
name
optional
|
|
string |
|
"The Fitzwilliam Museum."
|
description
optional
|
|
string |
A short description of the event.
|
"Fitzwilliam Museum, Exhibition of Old Things"
|
startTime
optional
|
|
|
Timestamp at which event is scheduled to start. If the event is ongoing/recurring, you can use the ticket time here.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580
|
endTime
optional
|
|
|
Timestamp at which event is scheduled to end. If the event is ongoing/recurring, you can use the ticket time here.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580
|
|
guest
optional
|
|
object |
The individual who will be attending the event.
Show definition
|
|
Name |
|
Type |
Description |
Example |
givenName
required
|
|
string |
The named guest's given name.
|
"John"
|
familyName
required
|
|
string |
The named guest's family name.
|
"Smith"
|
name
optional
|
|
string |
The named guest's full name.
|
"John Smith"
|
purchaser
optional
|
|
boolean |
Whether this guest is the individual who is purchasing the tickets.
|
|
|
|
travelTicket
optional
|
|
|
If the item being purchased is a ticket for travel, associate the journey information here.
Show definition
|
|
Name |
|
Type |
Description |
Example |
ticketId
required
|
|
string |
A unique identifier for the ticket
|
"tk_123"
|
description
optional
|
|
string |
A human-readable text description of what the ticket provides
|
"Standard Advanced Single - Adult - Full Fare"
|
passenger
optional
|
|
object |
The person travelling with this ticket.
Show definition
|
|
Name |
|
Type |
Description |
Example |
familyName
optional
|
|
string |
|
"Smith"
|
givenName
optional
|
|
string |
|
"John"
|
name
optional
|
|
string |
|
"John Smith"
|
email
optional
|
|
string |
|
"jsmith@example.com"
|
telephone
optional
|
|
string |
|
"+447546186424"
|
telephoneCountry
optional
|
|
string |
|
"GBR"
|
documentType
optional
|
|
string |
The type of document the passenger is traveling under
One of:
passport , driverslicense , or id .
|
"passport"
|
documentNumber
optional
|
|
string |
The number that identifies the document
|
"1234-abcd"
|
documentIssuingCountry
optional
|
|
string |
The 3 country code of the issuing country for the document
|
"GBR"
|
documentIssueTime
optional
|
|
integer |
The Unix timestamp that the document was issued
|
1479122053910
|
documentExpiryTime
optional
|
|
integer |
The Unix timestamp that the document expires
|
1479122053910
|
nationality
optional
|
|
string |
|
"GBR"
|
passengerType
optional
|
|
string |
The type of passenger this is
One of:
adult , child , infant , or senior .
|
"adult"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
gender
deprecated
|
|
string |
|
|
|
routes
optional
|
|
array |
The list of routes that this ticket grants the holder travel on.
Show definition
|
|
Name |
|
Type |
Description |
Example |
direction
optional
|
|
string |
The direction of travel along this route, e.g. 'outward' or 'return'.
|
"outward"
|
journeyId
optional
|
|
string |
This is an optional unique id to tie routes together. For example, You can tie a outbound and return route together with this. This way you can have multiple return tickets in one order and routes can be logically grouped together. This must be GLOBALLY UNIQUE
|
"xyz-123-ABC"
|
legs
optional
|
|
array |
This is the list of travel legs taken by the passengers. It may contain any number of legs but must start at the first departure and end up at the final destination
Show definition
|
|
Name |
|
Type |
Description |
Example |
legId
required
|
|
string |
The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')
|
"leg-a1B2c3D4e5F6g7H"
|
departurePortCode
optional
|
|
string |
Departure port code for the current leg. For flights: the 3 letter IATA airport code.
|
"LHR"
|
departurePort
optional
|
|
object |
The location of the departure port for the current leg. For flights: the location of the airport.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
departureCity
optional
|
|
string |
The name of the city of departure for the current leg.
|
"London"
|
departureCountryCode
optional
|
|
string |
The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.
|
"GBR"
|
departureTime
optional
|
|
integer |
The departure time for the current leg.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1478883331000
|
arrivalPortCode
optional
|
|
string |
Arrival port code for the current leg. For flights: the 3 letter IATA airport code.
|
"SFO"
|
arrivalPort
optional
|
|
object |
The location of the arrival port for the current leg. For flights: the location of the airport.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
arrivalCity
optional
|
|
string |
The name of the city of arrival for the current leg.
|
"London"
|
arrivalCountryCode
optional
|
|
string |
The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.
|
"GBR"
|
arrivalTime
optional
|
|
integer |
The arrival time for the current leg.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1478883331000
|
carrierName
optional
|
|
string |
The name of the carrier/company conducting the current leg.
|
"air canada"
|
carrierCode
optional
|
|
string |
A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.
|
"AC"
|
transportationType
optional
|
|
string |
The type of transportation.
One of:
plane , train , bus , or ship .
|
|
seatReservation
optional
|
|
boolean |
Whether there are seat reservations on this leg.
|
false
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
travelInsurance
optional
|
|
boolean |
If the passenger purchased travel insurance.
|
true
|
ticketClass
optional
|
|
string |
The class of travel this ticket grants access to.
One of:
business , economy , first , or standard .
|
"first"
|
ticketType
optional
|
|
string |
The type of ticket this belongs to. This includes round trip, multi city, open return, etc
|
"openreturn"
|
validUntilTime
optional
|
|
integer |
The time that this ticket can be used until.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1478883331000
|
fulfilmentMethod
optional
|
|
string |
The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc
|
"email"
|
loyaltyCardId
optional
|
|
string |
The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field
|
"abc-123-loyalty-xyz"
|
discountCardId
optional
|
|
string |
The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field
|
"abc-123-loyalty-xyz"
|
|
accommodation
optional
|
|
object |
If the item being purchased represents accommodation being booked, associate the trip information here.
Show definition
|
|
Name |
|
Type |
Description |
Example |
refundable
required
|
|
boolean |
Whether this booking is refundable or not.
|
false
|
payOnArrival
required
|
|
boolean |
Whether the payment is taken at the hotel during check-in.
|
true
|
guest
optional
|
|
object |
The individual the booking is registered under (i.e the individual who will be checking in to the hotel). Either the current customer or another individual who the customer is booking the room on behalf of.
Show definition
|
|
Name |
|
Type |
Description |
Example |
familyName
optional
|
|
string |
The booked guest's family name.
|
"Smith"
|
givenName
optional
|
|
string |
The booked guest's given name.
|
"John"
|
name
optional
|
|
string |
The booked guest's full name.
|
"John Smith"
|
|
freeCancellationUntilTime
optional
|
|
integer |
Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.
|
1480340580291
|
paymentDueBeforeTime
optional
|
|
integer |
Timestamp at which payment is due. Ignore if payment is taken immediately at booking.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580910
|
hotel
optional
|
|
object |
Information on the hotel that the room is located in.
Show definition
|
|
Name |
|
Type |
Description |
Example |
name
optional
|
|
string |
|
"The Overlook Hotel"
|
location
optional
|
|
object |
The location of the hotel.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
starRating
optional
|
|
integer |
The star-rating awarded to this hotel. Use an 'offical' hotel classification value here, not a customer rating value.
|
|
|
room
optional
|
|
object |
Information on room being booked.
Show definition
|
|
Name |
|
Type |
Description |
Example |
name
optional
|
|
string |
|
"Grand Deluxe Double King Suite"
|
checkInTime
optional
|
|
integer |
Timestamp at which guest check-in opens for the room.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
checkOutTime
optional
|
|
integer |
Timestamp at which guest check-out closes for the room.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
capacity
optional
|
|
integer |
Maximum number of adult guests the room can accomodate.
|
|
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
note
optional
|
|
string |
Descriptive text relating to the contents or nature of the order being completed.
|
|
email
optional
|
|
string |
Contact e-mail for this order.
|
"jsmith@example.com"
|
telephone
optional
|
|
string |
Contact phone number for this order. Best in E.164 format with an international dialing code.
|
"+441234558887"
|
telephoneCountry
optional
|
|
string |
Contact phone number's country
|
"GBR"
|
sellerId
deprecated
|
|
string |
The unique identifier of the seller/counterparty in the transaction,
if not your business. E.g. The restaurant, driver ID, etc.
|
"abcde12345-ZXY"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
executionTime
deprecated
|
|
integer |
Deprecated in favour of items.executionTime . Execution or pick-up time of the order.
|
1512828988826
|
suppliers
optional
|
|
array |
Suppliers (e.g. restaurants, couriers or drivers) involved in this order. See Suppliers for more information.
Show definition
|
|
Name |
|
Type |
Description |
Example |
supplierId
required
|
|
string |
The unique identifier of this supplier.
|
"abc-123-ZYZ"
|
type
required
|
|
string |
One of:
driver , courier , restaurant , shop , seller , or other .
|
"courier"
|
status
important
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
stage
optional
|
|
string |
The order processing stage reached by this supplier.
One of:
accepted , in-progress , fulfilled , or cancelled .
|
"fulfilled"
|
timestamp
optional
|
|
integer |
The time when the supplier's status changed.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
reason
optional
|
|
string |
The reason provided by the supplier for this status change.
|
"Could not find passenger"
|
|
fee
important
|
|
integer |
|
250
|
debt
optional
|
|
integer |
The value of a debt the supplier accrues to the platform as a result of this order, in
the currency's basic units. For example, a supplier may accrue a debt if they accept a
cash payment on behalf of the platform. The supplier's fee should not be deducted from the debt
- e.g. if the supplier's fee is £2.50 and the customer pays the supplier £10 in cash, the debt should be
1000
and the fee 250 .
|
1000
|
tip
optional
|
|
integer |
A voluntary tip paid by the customer to the supplier for the order, in
the currency's basic units. This is in addition to the supplier's fee.
|
200
|
currency
optional
|
|
string |
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
|
|
paymentMethod
important
|
|
object |
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
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Vault card payment method indicator.
One of:
card , creditcard , or debitcard .
|
"card"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
scheme
optional
|
|
string |
The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the cardBin, which should be preferred.
|
"visa"
|
instrumentId
important
|
|
string |
A unique identifier for the physical card, shared between users. Used
to link cards in Connect. Must not be a hash of the PAN.
If you use multiple PSPs who each generate their own equivalent of an
instrumentId, you should consider prefixing their values to indicate
their origin to avoid collisions. Common examples include Stripe's
fingerprint,
or Braintree's
unique_number_identifier).
|
"fp_abc123"
|
pan
pci, optional
|
|
string |
The full Primary Account Number of the card. Used by Ravelin to determine the
instrumentId for this card. If specified, you do not need to provide instrumentId , cardBin
or cardLastFour .</br></br>
Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests
containing this field to api.ravelin.com , and must instead use pci.ravelin.com .</br></br>
Please see <a href='/guides/pci'>our PCI DSS documentation</a> for more information.
|
4111111111111111
|
cardBin
important
|
|
string |
The first six digits of the card number/PAN. The Bank Identification
Number (BIN), recently more commonly known as the Issuer
Identification Number (IIN).
Given the BIN, Ravelin will populate the issuer, country of issuance,
and card type on your behalf.
|
"535522"
|
cardLastFour
important
|
|
string |
The last four digits of the card number/PAN.
|
"0001"
|
issuer
optional
|
|
string |
The card issuer, who the true cardholder will report fraud to. Ravelin
will identify the issuer on your behalf if you send the cardBin ,
which should be preferred.
|
|
prepaidCard
optional
|
|
boolean |
Whether this is a prepaid debit card. Ravelin will identify whether
the card is prepaid on your behalf if you send the cardBin which
should be preferred.
|
|
countryIssued
optional
|
|
string |
The country that the card was issued in. Ravelin will identify the
country of issuance on your behalf if you send the cardBin , which
should be preferred.
A ISO 3166-1 Alpha 3
or Alpha 2 country
code.
|
|
expiryMonth
important
|
|
integer |
The expiry month of the card.
|
7
|
expiryYear
important
|
|
integer |
The expiry year of the card.
|
2020
|
eWallet
deprecated
|
|
string |
The e-Wallet to which the customer associated the card.
One of:
applepay , googlepay , samsungpay , amazonpay , or visacheckout .
|
"applepay"
|
nameOnCard
important
|
|
string |
|
"John Smith"
|
billingAddress
important
|
|
object |
The address of the registered cardholder, as used to pass
AVS
checks. It is common to have fewer location details for this address,
but provide what you have.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
corporateCard
optional
|
|
boolean |
Whether this payment method is a corporate card.
|
true
|
virtualCard
optional
|
|
boolean |
Whether this payment method is a virtual card.
|
true
|
successfulRegistration
optional
|
|
boolean |
Whether the card was successfully registered with your gateway/PSP.
|
true
|
registrationTime
important
|
|
integer |
The time that the card was saved to the customer's account. (Not the card start date.)
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
lastVerified
optional
|
|
integer |
The time at which the payment method was last verified by the customer.
An example mechanism would be a random amount charged to the
customer's card that they can confirm the amount of.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
compromised
optional
|
|
boolean |
Whether the card has been compromised.
|
true
|
compromisedReason
important
|
|
string |
The reason why the card is considered compromised.
One of:
cloned , databreach , found , lost , stolen , frozen , defrosted , or uncompromised .
|
"stolen"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
active
deprecated
|
|
boolean |
Whether this card is still saved to the customer's account.
|
|
banned
deprecated
|
|
boolean |
Whether this card has been banned.
|
|
nickName
deprecated
|
|
string |
The nickname the customer has given the payment method.
|
|
cardType
deprecated
|
|
string |
The card network or scheme, such as visa or mastercard . Ravelin
will identify the cardType on your behalf if you send the cardBin ,
which should be preferred.
|
|
|
|
•
paymentMethodCipher : An encrypted payment method, containing the full card details encrypted via a
Ravelin SDK.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Client-side encrypted card payment method indicator.
Only:
paymentMethodCipher .
|
"paymentMethodCipher"
|
cardCiphertext
required, pci
|
|
string |
The card ciphertext produced by the Ravelin SDK card encryption.
This field constitutes cardholder data, and submission of this field therefore requires PCI DSS
SAQ-A or SAQ-AEP certification. You must not send requests containing this field to
api.ravelin.com , and must instead use pci.ravelin.com .
Please see <a href="/guides/pci">our PCI DSS documentation</a> for more information.</p>
|
|
aesKeyCiphertext
required
|
|
string |
The AES Key ciphertext produced by the Ravelin SDK card encryption.
|
|
algorithm
required
|
|
string |
The algorithm used to generate the ciphertexts.
|
|
paymentMethodId
optional
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
ravelinSDKVersion
optional
|
|
string |
The version of the Ravelin SDK that performed this encryption.
|
|
keyIndex
optional
|
|
integer |
The index of the public RSA key used to encrypt the card.
|
|
keySignature
optional
|
|
string |
An identifier for the public key used during encryption.
|
|
billingAddress
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
registrationTime
optional
|
|
integer |
When the payment method was added to the user's account. Note: this is not the card start date.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
ravelinjsVersion
deprecated
|
|
string |
The version of the ravelinjs library that performed this encryption.
|
|
|
|
•
cash : The customer is paying in cash, or a cash-based payment method.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Indicator of a cash payment, or cash-based payment method (e.g. paysafecard).
Only:
cash .
|
"cash"
|
scheme
optional
|
|
string |
The name of the cash-based payment service used, if applicable.
|
"paysafecard"
|
|
|
•
bankaccount : Bank Accounts.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Only:
bankaccount .
|
"bankaccount"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
transferType
required
|
|
string |
The type of transfer: whether the customer is initiating the payment, or you are withdrawing funds from the customer's bank account based on an agreement to initiate payments on their behalf. Use "push" for a customer-initiated payment (e.g. a bank transfer) and "pull" for a merchant-initiated payment (e.g. Direct Debit).
One of:
push , or pull .
|
"push"
|
scheme
important
|
|
string |
The name of the payment scheme or instrument used for the transfer of funds.
|
"sepa"
|
iban
optional
|
|
string |
IBAN (International Bank Account Number)
Following the ISO 13616:2007 standard.
|
"GB15HBUK40127612345678"
|
countryIssued
optional
|
|
string |
|
"GBR"
|
accountAddress
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
accountOwnerName
optional
|
|
string |
The name of the account owner.
|
"John Smith"
|
bankCode
optional
|
|
string |
Code assigned by central bank to identify bank that account is associated with.
Multiple bank code formats are supported.
|
"401276"
|
bankName
optional
|
|
string |
Name of bank which account belongs to.
|
"HSBC Bank"
|
bic
optional
|
|
string |
BIC - business identifier code for banks and other institutions.
Following the ISO9362 standard.
|
"HBUKGB4B"
|
accountNumber
optional
|
|
string |
The account number issued by the bank.
|
"12345678"
|
nickName
optional
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
"joescard"
|
registrationTime
important
|
|
integer |
The time that the card was saved to the customer's account. (Not the card start date.)
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
|
•
paypal : PayPal payments.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Only:
paypal .
|
"paypal"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
payerId
optional
|
|
string |
|
"WDJJHEBZ4X2LY"
|
email
important
|
|
string |
|
"hello@examples.ru"
|
billingAddress
optional
|
|
object |
The address of the account holder. It is common to have fewer location
details for this address, but provide what you have.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
registrationTime
important
|
|
integer |
The time that the card was saved to the customer's account. (Not the card start date.)
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
lastVerified
optional
|
|
integer |
The time at which the payment method was last verified by the customer.
An example mechanism would be a random amount charged to the
customer's card that they can confirm the amount of.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
nickName
optional
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
|
countryIssued
optional
|
|
string |
|
"GB"
|
verifiedAccount
optional
|
|
boolean |
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
banned
deprecated
|
|
boolean |
If the payment method has been banned
|
|
active
deprecated
|
|
boolean |
Whether the payment method is active for use by this account
|
|
|
|
•
credit : This payment method type should be used for any payments made using credit that a customer has with the merchant.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Credit payment indicator.
Only:
credit .
|
"credit"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
scheme
optional
|
|
string |
The name of the store credit scheme used as a payment method, if applicable.
|
"store-credit"
|
registrationTime
optional
|
|
integer |
When the payment method was added to the user's account.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
lastVerified
optional
|
|
integer |
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
|
•
invoice : This payment method should be used whenever the merchant provides credit to the customer.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Invoice payment indicator.
Only:
invoice .
|
"invoice"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
scheme
important
|
|
string |
The name of the invoice or 'buy now, pay later' scheme used, if applicable.
|
"klarna-pay-later"
|
registrationTime
optional
|
|
integer |
When the payment method was added to the user's account.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
lastVerified
optional
|
|
integer |
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
accountOwnerName
optional
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
|
accountAddress
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
email
optional
|
|
string |
The email address used by the customer to register an invoice or 'buy now, pay later' payment method.
|
"jsmith123@example.com"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
|
•
wallet : A digital wallet payment method.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Vault card payment method indicator.
Only:
wallet .
|
"wallet"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
scheme
required
|
|
string |
The name of the digital wallet scheme or electronic payment service.
|
"applepay"
|
cardScheme
optional
|
|
string |
The card network or scheme of the card used within a wallet payment method,
such as visa or mastercard. Ravelin will identify the cardScheme on your behalf
if you send the cardBin, which should be preferred.
|
"visa"
|
instrumentId
important
|
|
string |
A unique identifier for the physical card, shared between users. Used
to link cards in Connect. Must not be a hash of the PAN.
If you use multiple PSPs who each generate their own equivalent of an
instrumentId, you should consider prefixing their values to indicate
their origin to avoid collisions. Common examples include Stripe's
fingerprint,
or Braintree's
unique_number_identifier).
|
"fp_abc123"
|
pan
pci, optional
|
|
string |
The full Primary Account Number of the card. Used by Ravelin to determine the
instrumentId for this card. If specified, you do not need to provide instrumentId , cardBin
or cardLastFour .</br></br>
Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests
containing this field to api.ravelin.com , and must instead use pci.ravelin.com .</br></br>
Please see <a href='/guides/pci'>our PCI DSS documentation</a> for more information.
|
4111111111111111
|
cardBin
important
|
|
string |
The first six digits of the card number/PAN. The Bank Identification
Number (BIN), recently more commonly known as the Issuer
Identification Number (IIN).
Given the BIN, Ravelin will populate the issuer, country of issuance,
and card type on your behalf.
|
"535522"
|
cardLastFour
important
|
|
string |
The last four digits of the card number/PAN.
|
"0001"
|
cardType
deprecated
|
|
string |
The card network or scheme, such as visa or mastercard . Ravelin
will identify the cardType on your behalf if you send the cardBin ,
which should be preferred.
|
|
issuer
optional
|
|
string |
The card issuer, who the true cardholder will report fraud to. Ravelin
will identify the issuer on your behalf if you send the cardBin ,
which should be preferred.
|
|
prepaidCard
optional
|
|
boolean |
Whether this is a prepaid debit card. Ravelin will identify whether
the card is prepaid on your behalf if you send the cardBin which
should be preferred.
|
|
countryIssued
optional
|
|
string |
The country that the card was issued in. Ravelin will identify the
country of issuance on your behalf if you send the cardBin , which
should be preferred.
A ISO 3166-1 Alpha 3
or Alpha 2 country
code.
|
|
expiryMonth
important
|
|
integer |
The expiry month of the card.
|
7
|
expiryYear
important
|
|
integer |
The expiry year of the card.
|
2020
|
nameOnCard
important
|
|
string |
|
"John Smith"
|
billingAddress
important
|
|
object |
The address of the registered cardholder, as used to pass
AVS
checks. It is common to have fewer location details for this address,
but provide what you have.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
successfulRegistration
optional
|
|
boolean |
Whether the card was successfully registered with your gateway/PSP.
|
true
|
registrationTime
important
|
|
integer |
The time that the card was saved to the customer's account. (Not the card start date.)
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
lastVerified
optional
|
|
integer |
The time at which the payment method was last verified by the customer.
An example mechanism would be a random amount charged to the
customer's card that they can confirm the amount of.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
active
deprecated
|
|
boolean |
Whether this card is still saved to the customer's account.
|
|
banned
deprecated
|
|
boolean |
Whether this card has been banned.
|
|
nickName
deprecated
|
|
string |
The nickname the customer has given the payment method.
|
|
|
|
•
fromTransaction : Refer to the payment method used by a named
transaction. For usage examples, see saving cards after
checkout or refunds to unknown
cards.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Only:
fromTransaction .
|
"fromTransaction"
|
transactionId
important
|
|
string |
The transaction ID to look up the payment method from.
|
"tx-123"
|
gateway
important
|
|
string |
The gateway that the transaction was processed through.
|
"adyen"
|
gatewayReference
important
|
|
string |
The gateway ref provided by the gateway for the transaction.
|
"39407366378-1"
|
paymentMethodId
optional
|
|
string |
When present, will duplicate the payment method from the referenced
transaction and save it under this paymentMethodId for use later. Used
when saving cards after
checkout.
|
"pm-abc123"
|
|
|
•
directdebit : Direct Debits. - deprecated.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Only:
directdebit .
|
"directdebit"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
transferType
required
|
|
string |
Only:
directdebit .
|
|
scheme
required
|
|
string |
The type of direct debit scheme.
One of:
autogiro , bacs , becs , becsnz , betalingsservice , or sepa .
|
|
iban
optional
|
|
string |
IBAN (International Bank Account Number)
Following the ISO 13616:2007 standard.
|
"GB15HBUK40127612345678"
|
countryIssued
optional
|
|
string |
|
|
accountAddress
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
accountOwnerName
optional
|
|
string |
The name of the account owner.
|
"John Smith"
|
bankCode
optional
|
|
string |
Code assigned by central bank to identify bank that account is associated with.
Multiple bank code formats are supported.
|
"401276"
|
bankName
optional
|
|
string |
Name of bank which account belongs to.
|
"HSBC Bank"
|
bic
optional
|
|
string |
BIC - business identifier code for banks and other institutions.
Following the ISO9362 standard.
|
"HBUKGB4B"
|
accountNumber
optional
|
|
string |
The account number issued by the bank.
|
"12345678"
|
mandateRef
optional
|
|
string |
The unique reference issued for the direct debit mandate.
|
"DDREF12345"
|
mandateURL
optional
|
|
string |
A URL to access the direct debit mandate agreement.
|
"https://somesite.com/ddportal/mandates/DDREF12345"
|
nickName
optional
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
"joescard"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
|
•
banktransfer : Bank Transfers. - deprecated.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Only:
banktransfer .
|
"banktransfer"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
transferType
required
|
|
string |
One of:
bancontact , eps , giropay , ideal , inghomepay , sofort , or sepa .
|
|
iban
optional
|
|
string |
IBAN (International Bank Account Number)
Following the ISO 13616:2007 standard.
|
"GB15HBUK40127612345678"
|
countryIssued
optional
|
|
string |
|
"GBR"
|
accountAddress
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
accountOwnerName
optional
|
|
string |
The name of the account owner.
|
"John Smith"
|
bankCode
optional
|
|
string |
Code assigned by central bank to identify bank that account is associated with.
Multiple bank code formats are supported.
|
"401276"
|
bankName
optional
|
|
string |
Name of bank which account belongs to.
|
"HSBC Bank"
|
bic
optional
|
|
string |
BIC - business identifier code for banks and other institutions.
Following the ISO9362 standard.
|
"HBUKGB4B"
|
accountNumber
optional
|
|
string |
The account number issued by the bank.
|
"12345678"
|
nickName
optional
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
"joescard"
|
registrationTime
important
|
|
integer |
The time that the card was saved to the customer's account. (Not the card start date.)
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
|
•
Others - deprecated.
Show definition
|
Name |
|
Type |
Description |
Example |
methodType
required
|
|
string |
Other method type indicator.
One of:
voucher , bitcoin , transfer , paysafe , cheque , or edenred .
|
"voucher"
|
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
registrationTime
optional
|
|
integer |
When the payment method was added to the user's account.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
|
lastVerified
optional
|
|
integer |
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
nickName
deprecated
|
|
string |
The nickname for the payment method that the customers gives, if applicable.
|
|
banned
deprecated
|
|
boolean |
If the payment method has been banned
|
|
active
deprecated
|
|
boolean |
Whether the payment method is active for use by this account
|
|
|
|
•
Removal: Used for marking a saved payment method as removed from the account.
Show definition
|
Name |
|
Type |
Description |
Example |
paymentMethodId
required
|
|
string |
A unique identifier for this payment, specific to this customer. Two
customers should not use the same paymentMethodId.
|
"pm-abc123"
|
active
required
|
|
boolean |
False to indicate the payment method has been deactivated.
Only:
false .
|
false
|
|
paymentMethods
important
|
|
array |
One or more payment methods to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethodId.
|
|
paymentMethodId
important
|
|
string |
The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethods.
|
"pm-abc123"
|
transaction
important
|
|
object |
An attempt to charge a payment method to pay or be refunded for an order. Mutually exclusive with transactions.
Show definition
|
|
Name |
|
Type |
Description |
Example |
transactionId
important
|
|
string |
A unique identifier for the transaction.
Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference .
|
"123-abc-XYZ"
|
time
important
|
|
integer |
The time that the transaction is being attempted.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580291
|
amount
important
|
|
integer |
|
1000
|
currency
optional
|
|
string |
The currency of the amount of this transaction, as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
type
important
|
|
string |
The type of transaction interacting with the payment method.
auth : An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
capture : A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
auth_capture : A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
refund : A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refund transaction payment methods.
void : A void transaction is the explicit discarding of authorization of funds.
use , redeem : Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.
One of:
preauth , auth , capture , auth_capture , void , refund , redeem , or use .
|
"auth_capture"
|
paymentMethodId
important
|
|
string |
The ID of the payment method to be charged in this transaction.
|
"pm-abc123"
|
gateway
important
|
|
string |
The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.
|
"braintree"
|
gatewayReference
important
|
|
string |
The reference given to this transaction by the processing gateway. Used to link to chargebacks. Usually only available after attempting the payment. Each transaction should have a unique gateway reference.
|
"123-abc-XYZ"
|
success
important
|
|
boolean |
Whether the transaction successfully completed with no error.
|
true
|
3ds
optional
|
|
object |
Details on how 3D Secure (3DS) was used to authenticate the transaction.
Show definition
|
|
Name |
|
Type |
Description |
Example |
attempted
optional
|
|
boolean |
Set to true if the 3D Secure authentication process was initiated for the transaction. The 3DS process is considered initiated when a check is performed to confirm issuer and cardholder enrolment, before asking for a challenge to be performed.
This is set to false if the 3DS process was not initiated and the transaction proceeded to authorisation.
|
true
|
challenged
optional
|
|
boolean |
Set to true if a step-up authentication was initiated, for example, the user was asked to enter a password or use a form of biometric authentication.
If attempted is set to false , then challenged should be omitted. If attempted is set to true , and a challenge was not presented to the user, then this field should be set to false .
In 3DS2, if a user achieves a frictionless authentication this should also be set to false .
|
true
|
success
optional
|
|
boolean |
Set to true if the user was successfully authenticated using 3D Secure (either through frictionless authentication or a challenge) and the 3DS process was completed successfully.
This field should be set to false if the user was unable to authenticate themselves during the challenge process, if an error occured, or frictionless authentication was not successful.
This field should be omitted if attempted is set to false .
|
true
|
startTime
optional
|
|
integer |
The time at which the user was directed to 3DS.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1479231064910
|
endTime
optional
|
|
integer |
The time at which the user returned from 3DS.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1479231064919
|
timedOut
optional
|
|
boolean |
Whether the user is believed to have abandoned 3DS.
|
false
|
version
optional
|
|
string |
The version of 3DS which was used to authenticate the user. Either 1.0.2 or 2.1.0
|
"1.0.2"
|
liabilityShifted
optional
|
|
boolean |
Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer.
(See Liability Shifted Chargebacks.)
|
true
|
authenticationValue
deprecated
|
|
string |
This field is deprecated, we do not use it in the Ravelin platform.
|
|
eci
optional
|
|
string |
The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.
|
"5"
|
transStatus
optional
|
|
string |
The Transaction Status (transStatus) value received in the final authentication message. The final message type (PaRes, ARes, CRes) will vary depending on the version of 3DS and whether the user was challenged.
|
"Y"
|
transStatusReason
optional
|
|
string |
Provides information on why the transStatus field has the specified value. Will only be provided by the issuer when the transStatus value is N, U or R. (3DS 2 only)
|
"01"
|
messageType
optional
|
|
string |
Identifies the type of message from which the transStatus value was received. (3DS 2 only)
|
"ARes"
|
iReqCode
optional
|
|
string |
If the transStatus value is U the accompanying invalid request code (iReqCode) should be provided to further explain the reason authentication could not be performed. (3DS 1 only)
|
"55"
|
|
declineCode
important
|
|
string |
the decline code from the payment gateway, if applicable.
|
"1234"
|
authCode
optional
|
|
string |
A code returned from the payment gateway after an attempt to charge, if applicable.
|
"1234"
|
avsResultCode
optional
|
|
object |
The result of AVS checks. You must have at least one of street or postal code.
Any of the following:
Show definition
|
|
Name |
|
Type |
Description |
Example |
street
optional
|
|
string |
Compatible with common PSP codes
|
"pass"
|
postalCode
optional
|
|
string |
Compatible with common PSP codes
|
"unchecked"
|
|
|
|
|
|
cvvResultCode
optional
|
|
string |
The result of CVV verification from the issuer, compatible with common PSP codes.
|
"pass"
|
mcc
optional
|
|
string |
|
"0742"
|
mid
optional
|
|
string |
The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.
|
"mid-1"
|
acquirerId
optional
|
|
string |
The acquirer is a financial institution with whom the merchant has a bank account.
|
"adyen"
|
acquirerBin
optional
|
|
string |
The BIN (Bank Identification Number) of the acquirer.
|
"123456"
|
acquirerCountryCode
optional
|
|
string |
The three letter country code of the country in which your acquirer will settle the payment.
|
"GBR"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
chargeback
deprecated
|
|
boolean |
Whether this transaction is associated with a chargeback.
|
|
email
deprecated
|
|
string |
The e-mail that the customer wants to be notified about this
transaction on.
|
|
debit
deprecated
|
|
integer |
Deprecated in favour of amount . The debit amount of the
transaction in the lowest denomination of the currency.
|
|
credit
deprecated
|
|
integer |
Deprected in favour of amount . The credit amount of the
transaction in the lowest denomination of the currency.
|
|
|
transactions
important
|
|
array |
One or more attempts to charge a payment method to pay or be refunded for an order. Mutually exclusive with transaction.
Show definition
|
|
Name |
|
Type |
Description |
Example |
transactionId
important
|
|
string |
A unique identifier for the transaction.
Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference .
|
"123-abc-XYZ"
|
time
important
|
|
integer |
The time that the transaction is being attempted.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1480340580291
|
amount
important
|
|
integer |
|
1000
|
currency
optional
|
|
string |
The currency of the amount of this transaction, as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
type
important
|
|
string |
The type of transaction interacting with the payment method.
auth : An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
capture : A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
auth_capture : A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
refund : A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refund transaction payment methods.
void : A void transaction is the explicit discarding of authorization of funds.
use , redeem : Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.
One of:
preauth , auth , capture , auth_capture , void , refund , redeem , or use .
|
"auth_capture"
|
paymentMethodId
important
|
|
string |
The ID of the payment method to be charged in this transaction.
|
"pm-abc123"
|
gateway
important
|
|
string |
The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.
|
"braintree"
|
gatewayReference
important
|
|
string |
The reference given to this transaction by the processing gateway. Used to link to chargebacks. Usually only available after attempting the payment. Each transaction should have a unique gateway reference.
|
"123-abc-XYZ"
|
success
important
|
|
boolean |
Whether the transaction successfully completed with no error.
|
true
|
3ds
optional
|
|
object |
Details on how 3D Secure (3DS) was used to authenticate the transaction.
Show definition
|
|
Name |
|
Type |
Description |
Example |
attempted
optional
|
|
boolean |
Set to true if the 3D Secure authentication process was initiated for the transaction. The 3DS process is considered initiated when a check is performed to confirm issuer and cardholder enrolment, before asking for a challenge to be performed.
This is set to false if the 3DS process was not initiated and the transaction proceeded to authorisation.
|
true
|
challenged
optional
|
|
boolean |
Set to true if a step-up authentication was initiated, for example, the user was asked to enter a password or use a form of biometric authentication.
If attempted is set to false , then challenged should be omitted. If attempted is set to true , and a challenge was not presented to the user, then this field should be set to false .
In 3DS2, if a user achieves a frictionless authentication this should also be set to false .
|
true
|
success
optional
|
|
boolean |
Set to true if the user was successfully authenticated using 3D Secure (either through frictionless authentication or a challenge) and the 3DS process was completed successfully.
This field should be set to false if the user was unable to authenticate themselves during the challenge process, if an error occured, or frictionless authentication was not successful.
This field should be omitted if attempted is set to false .
|
true
|
startTime
optional
|
|
integer |
The time at which the user was directed to 3DS.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1479231064910
|
endTime
optional
|
|
integer |
The time at which the user returned from 3DS.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1479231064919
|
timedOut
optional
|
|
boolean |
Whether the user is believed to have abandoned 3DS.
|
false
|
version
optional
|
|
string |
The version of 3DS which was used to authenticate the user. Either 1.0.2 or 2.1.0
|
"1.0.2"
|
liabilityShifted
optional
|
|
boolean |
Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer.
(See Liability Shifted Chargebacks.)
|
true
|
authenticationValue
deprecated
|
|
string |
This field is deprecated, we do not use it in the Ravelin platform.
|
|
eci
optional
|
|
string |
The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.
|
"5"
|
transStatus
optional
|
|
string |
The Transaction Status (transStatus) value received in the final authentication message. The final message type (PaRes, ARes, CRes) will vary depending on the version of 3DS and whether the user was challenged.
|
"Y"
|
transStatusReason
optional
|
|
string |
Provides information on why the transStatus field has the specified value. Will only be provided by the issuer when the transStatus value is N, U or R. (3DS 2 only)
|
"01"
|
messageType
optional
|
|
string |
Identifies the type of message from which the transStatus value was received. (3DS 2 only)
|
"ARes"
|
iReqCode
optional
|
|
string |
If the transStatus value is U the accompanying invalid request code (iReqCode) should be provided to further explain the reason authentication could not be performed. (3DS 1 only)
|
"55"
|
|
declineCode
important
|
|
string |
the decline code from the payment gateway, if applicable.
|
"1234"
|
authCode
optional
|
|
string |
A code returned from the payment gateway after an attempt to charge, if applicable.
|
"1234"
|
avsResultCode
optional
|
|
object |
The result of AVS checks. You must have at least one of street or postal code.
Any of the following:
Show definition
|
|
Name |
|
Type |
Description |
Example |
street
optional
|
|
string |
Compatible with common PSP codes
|
"pass"
|
postalCode
optional
|
|
string |
Compatible with common PSP codes
|
"unchecked"
|
|
|
|
|
|
cvvResultCode
optional
|
|
string |
The result of CVV verification from the issuer, compatible with common PSP codes.
|
"pass"
|
mcc
optional
|
|
string |
|
"0742"
|
mid
optional
|
|
string |
The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.
|
"mid-1"
|
acquirerId
optional
|
|
string |
The acquirer is a financial institution with whom the merchant has a bank account.
|
"adyen"
|
acquirerBin
optional
|
|
string |
The BIN (Bank Identification Number) of the acquirer.
|
"123456"
|
acquirerCountryCode
optional
|
|
string |
The three letter country code of the country in which your acquirer will settle the payment.
|
"GBR"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
chargeback
deprecated
|
|
boolean |
Whether this transaction is associated with a chargeback.
|
|
email
deprecated
|
|
string |
The e-mail that the customer wants to be notified about this
transaction on.
|
|
debit
deprecated
|
|
integer |
Deprecated in favour of amount . The debit amount of the
transaction in the lowest denomination of the currency.
|
|
credit
deprecated
|
|
integer |
Deprected in favour of amount . The credit amount of the
transaction in the lowest denomination of the currency.
|
|
|
voucherRedemption
optional
|
|
object |
A voucher that is being used to pay for some of the order.
Show definition
|
|
Name |
|
Type |
Description |
Example |
paymentMethodId
required
|
|
string |
A unique identifier for the voucher usage. A transactionId for vouchers.
|
"VOUCH-89-abc-123-ZYZ"
|
voucherCode
required
|
|
string |
The string customers actually see in their app.
|
"VOUCH-89"
|
value
required
|
|
integer |
|
10000
|
redemptionTime
required
|
|
integer |
The time that the customer is utilising the voucher.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
success
required
|
|
boolean |
Whether the voucher has successfully been used by the customer.
|
true
|
currency
optional
|
|
string |
The currency of the value of this voucher, as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
expiry
optional
|
|
integer |
The time the after which the voucher can no longer be redeemed.
A unix timestamp as an
integer count of milliseconds, or nanoseconds since 1970-01-01T00:00
UTC.
|
|
voucherType
optional
|
|
string |
The type of the voucher. If REFERRAL , also set the referredId so
Ravelin will create a network of who has invited who.
One of:
REFERRAL , REACTIVATION , or GENERAL .
|
"GENERAL"
|
referrerId
optional
|
|
string |
The customerId of the customer who created this voucher.
|
|
referralValue
optional
|
|
integer |
|
|
failureReason
optional
|
|
string |
Optional reason why the attempt was not successful.
One of:
EXPIRED , NOT_NEW_CUSTOMER , ALREADY_USED , ABUSER , SYSTEM_FAILURE , or MAX_ALLOWED_TIMES .
|
|
failureSource
optional
|
|
string |
The source of why the voucher failed.
One of:
RAVELIN , or CLIENT .
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
voucherRedemptions
optional
|
|
array |
Any vouchers that are being used to pay for some of the order.
Show definition
|
|
Name |
|
Type |
Description |
Example |
paymentMethodId
required
|
|
string |
A unique identifier for the voucher usage. A transactionId for vouchers.
|
"VOUCH-89-abc-123-ZYZ"
|
voucherCode
required
|
|
string |
The string customers actually see in their app.
|
"VOUCH-89"
|
value
required
|
|
integer |
|
10000
|
redemptionTime
required
|
|
integer |
The time that the customer is utilising the voucher.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
|
1512828988826
|
success
required
|
|
boolean |
Whether the voucher has successfully been used by the customer.
|
true
|
currency
optional
|
|
string |
The currency of the value of this voucher, as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
|
"GBP"
|
expiry
optional
|
|
integer |
The time the after which the voucher can no longer be redeemed.
A unix timestamp as an
integer count of milliseconds, or nanoseconds since 1970-01-01T00:00
UTC.
|
|
voucherType
optional
|
|
string |
The type of the voucher. If REFERRAL , also set the referredId so
Ravelin will create a network of who has invited who.
One of:
REFERRAL , REACTIVATION , or GENERAL .
|
"GENERAL"
|
referrerId
optional
|
|
string |
The customerId of the customer who created this voucher.
|
|
referralValue
optional
|
|
integer |
|
|
failureReason
optional
|
|
string |
Optional reason why the attempt was not successful.
One of:
EXPIRED , NOT_NEW_CUSTOMER , ALREADY_USED , ABUSER , SYSTEM_FAILURE , or MAX_ALLOWED_TIMES .
|
|
failureSource
optional
|
|
string |
The source of why the voucher failed.
One of:
RAVELIN , or CLIENT .
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
|
device
optional
|
|
object |
The device used by the customer to trigger this update.
Show definition
|
|
Name |
|
Type |
Description |
Example |
deviceId
required
|
|
string |
The ID of the device used by the customer to trigger this update.
|
"65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"
|
ipAddress
important
|
|
string |
The IP address of the device connecting to your services. Used in fraud and account-takeover detection.
When extracting this IP address, consider X-Forwarded-For .
|
"81.152.92.84"
|
language
optional
|
|
string |
|
"en-US"
|
userAgent
important
|
|
string |
The browser user-agent string, if the device represents a web browser - window.navigator.userAgent .
|
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36"
|
model
important
|
|
string |
|
"Pixel XL"
|
os
important
|
|
string |
The operating system that the device is running.
|
"android"
|
type
optional
|
|
string |
One of:
computer , phone , or tablet .
|
"phone"
|
manufacturer
optional
|
|
string |
|
"google"
|
location
optional
|
|
object |
The geolocated position of the device.
Show definition
|
|
Name |
|
Type |
Description |
Example |
country
important
|
|
string |
|
"GBR"
|
postalCode
important
|
|
string |
The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.
|
"E1 1AA"
|
latitude
important
|
|
number |
The latitude of the location.
|
51.503252
|
longitude
important
|
|
number |
The longitude of the location.
|
-0.127899
|
addresseeName
optional
|
|
string |
The name of the person that will accept delivery of goods to this address.
|
"John Smith"
|
street1
optional
|
|
string |
The street address of the location.
|
"123 fake st."
|
street2
optional
|
|
string |
The street address of the location.
|
"floor 4, flat 48"
|
neighbourhood
optional
|
|
string |
The neighbourhood of the location.
|
"Hackney"
|
zone
optional
|
|
string |
The zone of the location.
|
"1"
|
city
optional
|
|
string |
|
"London"
|
region
optional
|
|
string |
The state/county of the location.
|
"California"
|
poBoxNumber
optional
|
|
string |
The PO box number related to the location.
|
"1234"
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
geohash
deprecated
|
|
string |
The geohash of the location.
|
|
|
custom
optional
|
|
object |
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
|
|
browser
deprecated
|
|
string |
The name of the web browser being used, if applicable. Prefer userAgent .
|
|
javascriptEnabled
deprecated
|
|
boolean |
Whether Javascript is enabled on the web browser.
|
|
cookiesEnabled
deprecated
|
|
boolean |
Whether cookies are enabled on the web browser.
|
|
screenResolution
deprecated
|
|
string |
The resolution of the screen on the device in the format XxY
|
|
|
deviceId
optional
|
|
string |
The ID of the device used by the customer to trigger this update.
|
"65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"
|
nationalIdentifications
optional
|
|
array |
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
|
|
Name |
|
Type |
Description |
Example |
driversLicense
optional
|
|
object |
A driving license permitting the holder to operate one or more types
of motorized vehicle.
Show definition
|
|
Name |
|
Type |
Description |
Example |
idNumber
required
|
|
string |
The number unique to this piece of identification within the
jurisdiction country/state.
For privacy reasons, Ravelin recommends obfuscating the real number by
peppering and hashing it, using consistent one-way hashing function such
as SHA256.
|
"10261985"
|
jurisdictionCountry
required
|
|
string |
|
"USA"
|
jurisdictionState
optional
|
|
string |
The controlling state within the controlling country for this form of
identification. Not just the licence holder's home state. Omit where
the identification is controlled by a country-level authority.
|
"CA"
|
name
optional
|
|
string |
The name of the identification holder.
|
"Marty McFly"
|
|
passport
optional
|
|
object |
A passport certifying the identity and nationality of its holder
primarily for the purpose of international travel.
Show definition
|
|
Name |
|
Type |
Description |
Example |
idNumber
required
|
|
string |
The number unique to this piece of identification within the
jurisdiction country/state.
For privacy reasons, Ravelin recommends obfuscating the real number by
peppering and hashing it, using consistent one-way hashing function such
as SHA256.
|
"NAD12345BR"
|
jurisdictionCountry
required
|
|
string |
|
"BRA"
|
jurisdictionState
optional
|
|
string |
The controlling state within the controlling country for this form of
identification. Not just the licence holder's home state. Omit where
the identification is controlled by a country-level authority.
|
|
name
optional
|
|
string |
The name of the identification holder.
|
"Nadia Brito"
|
|
nationalId
optional
|
|
object |
Show definition
|
|
Name |
|
Type |
Description |
Example |
idNumber
required
|
|
string |
The number unique to this piece of identification within the
jurisdiction country/state.
For privacy reasons, Ravelin recommends obfuscating the real number by
peppering and hashing it, using consistent one-way hashing function such
as SHA256.
|
"NAD12345BR"
|
jurisdictionCountry
required
|
|
string |
|
"BRA"
|
jurisdictionState
optional
|
|
string |
The controlling state within the controlling country for this form of
identification. Not just the licence holder's home state. Omit where
the identification is controlled by a country-level authority.
|
|
name
optional
|
|
string |
The name of the identification holder.
|
"Nadia Brito"
|
|
|