Refund

To request a recommendation at this endpoint use the Refund Request checkpoint.

POST api.ravelin.com/v2/refund

The Refund API endpoint allows you to request a recommendation from Ravelin on whether you should refund a customer.

See our Refund Abuse Integration Guide for how to use the Refund API endpoint to prevent refund abuse.

timestamp integer

required

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

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

customer object

required

The customer requesting a refunds.

Show definition

customerId string

required

The unique identifier of the customer. If your system allows anonymous checkout then we recommend making this the customer's email address.

registrationTime integer

important

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

email string

important

The email address of the customer.

emailVerifiedTime integer

optional

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

name string

important

The full name of the customer. If you have the name split into parts, consider familyName and givenName instead.

familyName string

important

The surname/last name of the customer. If you do not have the name split into parts, consider name instead.

givenName string

important

The first/given names of the customer. If you do not have the name split into parts, consider name instead.

telephone string

important

The telephone number of the customer. Best in E.164 format with an international dialing code.

telephoneVerifiedTime integer

optional

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

telephoneCountry string

optional

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.

passwordBcrypted string

optional

The bcypted form of the password for this customer. By its nature, the bcrypt operation is slow. Consider using passwordHashed if this is too slow for you.

passwordHashed string

optional

The SHA256 form of the password for this customer. This must be base64 encoded.

password string

optional

The plaintext password for the customer. We never store the raw password but for security we recommend using one of the hashing options instead of the plaintext option.

passwordChanged boolean

optional

Set to true on events where the password has been changed, false or omit otherwise.

tags object

optional

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 object

optional

Show definition

custom object

optional

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 string

deprecated

The username the customer would log in with.

gender string

deprecated

The gender of the customer.

balance object

deprecated

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 boolean

deprecated

Whether the customer is banned in your systems.

country string

deprecated

The home country for this customer. Doesn't change when the customer is briefly abroad.

market string

deprecated

The logical region in which this customer exists.

Pattern: ^[0-9a-z-]*$

marketCity string

deprecated

The logical city in which this customer exists.

Pattern: ^[0-9a-z-]*$

refund object

required

The refund describing the goods or services the customer wants to, or has attempted to return.

Show definition

refundId string

required

A unique identifier for this refund. Note: one order can have more than one refundId if the refund is processed per individual item and not per the entire order.

status string

required

The status of the refund.

OPEN - A refund object has the OPEN status until it is processed by the merchant
DECLINED - A refund object has the DECLINED status when the merchant has rejected the refund. See: declineReason
COMPLETED - A refund object has the COMPLETED stage when merchant has accepted the refund claim and the funds will be returned to the buyer

One of: OPEN, DECLINED, or COMPLETED.

refundRequestTime integer

important

Time at which the customer requested the refund.

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

refundIssuedTime integer

important

Time at which the refund was issued to the customer.

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

initiatedBy string

optional

The actor who initiated the refund claim.

CUSTOMER - The customer initiated the refund request
MERCHANT - The merchant initiated the refund request
SELLER - The seller initiated the refund process
AGENT - A customer support agent initiated the refund requested
AUTOMATED - The refund was initiated via an automated process

One of: CUSTOMER, MERCHANT, SELLER, AGENT, or AUTOMATED.

declineReason string

important

Description of why the refund has been declined.

RAVELIN - Ravelin issued a PREVENT recommendation that blocked the customer from completing their refund.
MERCHANT_REJECTED - The merchant rejected the refund claim. e.g. the purchase was fraudulent, the customer has a history of wardrobing, the customer sent the wrong item or no item to the merchant.Updated description.
TRANSACTION_PROCESSING_ERROR - There was a problem processing the refund transaction.
OTHER_FRAUD_TOOL - A previous or existing refund prevention rule configured in your system might block the refund.
DUPLICATE_CLAIM - A refund claim already exists for the transaction.
DISPUTE_RECEIVED - The customer has submitted a dispute request with their bank for the same transaction.

One of: RAVELIN, MERCHANT_REJECTED, TRANSACTION_PROCESSING_ERROR, OTHER_FRAUD_TOOL, DUPLICATE_CLAIM, or DISPUTE_RECEIVED.

type string

important

Whether the refund is for a repayment, an exchange or replacement of the original item.

REFUND - The repayment of the purchase amount paid by the customer for the goods or services.
EXCHANGE - The customer wants to change the original item to a new item, different to the original item.
REPLACEMENT - The customer wants to change the original item to an identical item.

One of: REFUND, EXCHANGE, or REPLACEMENT.

claim string

important

Whether the refund is full or partial.

FULL - Full refund of the purchase amount.
PARTIAL - Partial refund of the purchase amount.

One of: FULL, or PARTIAL.

refundReason string

important

The root cause why the customer asked for a refund. To be used only if you are not sending the refund items array.

UNWANTED_PURCHASE - The customer no longer needed the product or and accidental purchase.
ITEM_NOT_AS_EXPECTED - The product did not match the description or did not meet the customer's expectations, for example food was cold, not matching product description.
DAMAGED_DURING_DELIVERY - The product was delivered in a damaged or defective condition.
DELAYED_DELIVERY - The product arrived too late.
ITEM_NOT_RECEIVED - The product was not delivered to the customer.
MERCHANT_INCORRECT_ITEM - The merchant shipped the wrong product, size or colour.
CUSTOMER_INCORRECT_ITEM - The customer selected the wrong product, size or colour.
DEFECTIVE_ITEM - The product has a defect or doesn't work properly.
UNAUTHORISED_PURCHASE - The product was purchase without the card holder's permission.
OUT_OF_STOCK - The product is out of stock.
OTHER - When none of the above reasons apply.

One of: UNWANTED_PURCHASE, ITEM_NOT_AS_EXPECTED, DAMAGED_DURING_DELIVERY, DELAYED_DELIVERY, ITEM_NOT_RECEIVED, MERCHANT_INCORRECT_ITEM, CUSTOMER_INCORRECT_ITEM, DEFECTIVE_ITEM, UNAUTHORISED_PURCHASE, OUT_OF_STOCK, or OTHER.

policy string

optional

The agreement between customers and seller regarding refunds.

DISCRETIONARY - The merchant has sole discretion in determining the outcome of the refund claim.
TERMS_AND_CONDITIONS - The terms and conditions included in the refund policy.
GRACE_PERIOD - To be used when the merchant has a grace period in which a customer is allowed to get a refund if they have made a mistake when purchasing.
OTHER - When none of the above reasons apply.

One of: DISCRETIONARY, TERMS_AND_CONDITIONS, GRACE_PERIOD, or OTHER.

amount integer

important

The total amount for this refund in the currency's basic units.

currency string

important

The currency of the price for this order as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

nonRefundableAmount integer

optional

The total amount for this refund in the currency's basic units. e.g. delivery fee, admin fee, return fee , tips or any amount that should be deducted from the refund amount due to the item no longer qualifying for a special offer/ promotion applied on the original order.

issuedTo string

optional

The payment method where the refund amount is processed.

ORIGINAL_PAYMENT_METHOD - The payment method used to fund the original order purchase.
NEW_PAYMENT_METHOD - The new payment method the customer registers to their account to receive the refund amount.
GIFT_CARD - A prepaid debit card that the customer can use to buy other goods.
ACCOUNT_CREDIT - Credit on the customers account that they can use with the merchant.
CASH - A cash-based payment method

One of: ORIGINAL_PAYMENT_METHOD, NEW_PAYMENT_METHOD, GIFT_CARD, ACCOUNT_CREDIT, or CASH.

note string

optional

Descriptive text relating to the refund request.

refundRequestChannel string

optional

The channel used to submit the refund request. How was the refund request submitted:

CUSTOMER_SERVICE - The customer contacted customer support via email or phone and the customer support agent initiated the refund process
IN_STORE - The customer went to the store to request a refund
IN_APP - The customer initiated the refund request via the merchants website or mobile application

One of: CUSTOMER_SERVICE, IN_STORE, or IN_APP.

items array

optional

The line items of the refund, describing what the customer is refunding. Including, but not limited to products, services, journeys, tips, taxes, and delivery fees.

Show definition

quantity integer

required

Number of copies of this item that are present in the basket (set to 0 to remove).

refundReason string

important

The root cause why the customer asked for a refund for the item.

UNWANTED_PURCHASE - The customer no longer needed the product or and accidental purchase.
ITEM_NOT_AS_EXPECTED - The product did not match the description or did not meet the customer's expectations, for example food was cold, not matching product description
DAMAGED_DURING_DELIVERY - The product was delivered in a damaged or defective condition..
DELAYED_DELIVERY - The product arrived too late.
ITEM_NOT_RECEIVED - The product was not delivered to the customer.
MERCHANT_INCORRECT_ITEM - The merchant shipped the wrong product, size or colour.
CUSTOMER_INCORRECT_ITEM - The customer selected the wrong product, size or colour.
DEFECTIVE_ITEM - The product has a defect or doesn't work properly.
UNAUTHORISED_PURCHASE - The product was purchase without the card holder permission.
OUT_OF_STOCK - The product is out of stock.
OTHER - When none of the above reasons apply.

sku string

optional

A merchant specific identifier for an item or a service.

name string

optional

The name of the product or service that is being purchased.

price integer

important

The total price for a single one of these items, in the currency's basic units.

currency string

optional

The currency of the price for this order item as an ISO 4217 currency code. Defaults to order currency.

Pattern: ^[a-zA-Z]{3}$

brand string

optional

The name of the brand that the item is from.

upc string

optional

The name of the Universal Item Code.

category string

optional

The highest level category that this item is sold in.

subcategory string

optional

A category that this item is sold in.

executionTime integer

optional

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

eventTicket object

optional

If the item being purchased is a ticket for an event, associate the ticket and event information here.

Show definition

ticket object

required

The ticket information for this event.

Show definition

event object

required

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.

Show definition

eventId string

required

A unique identifier for this event.

category string

required

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.

venue object

required

The location the event will take place.

Show definition

name string

optional

The name of the event.

description string

optional

A short description of the event.

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

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

guest object

optional

The individual who will be attending the event.

Show definition

travelTicket

optional

If the item being purchased is a ticket for travel, associate the journey information here.

Show definition

ticketId string

required

A unique identifier for the ticket

description string

optional

A human-readable text description of what the ticket provides

passenger object

optional

The person travelling with this ticket.

Show definition

routes array

optional

The list of routes that this ticket grants the holder travel on.

Show definition

direction string

optional

The direction of travel along this route, e.g. 'outward' or 'return'.

journeyId string

optional

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

legs array

optional

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

legId string

required

The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')

departurePortCode string

optional

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

departurePort object

optional

The location of the departure port for the current leg. For flights: the location of the airport.

Show definition

departureCity string

optional

The name of the city of departure for the current leg.

departureCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.

departureTime integer

optional

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

arrivalPortCode string

optional

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

arrivalPort object

optional

The location of the arrival port for the current leg. For flights: the location of the airport.

Show definition

arrivalCity string

optional

The name of the city of arrival for the current leg.

arrivalCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.

arrivalTime integer

optional

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

carrierName string

optional

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

carrierCode string

optional

A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.

transportationType string

optional

The type of transportation.

One of: plane, train, bus, or ship.

seatReservation boolean

optional

Whether there are seat reservations on this leg.

custom object

optional

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 object

optional

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 boolean

optional

If the passenger purchased travel insurance.

ticketClass string

optional

The class of travel this ticket grants access to.

One of: business, economy, first, or standard.

ticketType string

optional

The type of ticket this belongs to. This includes round trip, multi city, open return, etc

validUntilTime integer

optional

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

fulfilmentMethod string

optional

The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc

loyaltyCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

discountCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

accommodation object

optional

If the item being purchased represents accommodation being booked, associate the trip information here.

Show definition

refundable boolean

required

Whether this booking is refundable or not.

payOnArrival boolean

required

Whether the payment is taken at the hotel during check-in.

guest object

optional

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

freeCancellationUntilTime integer

optional

Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.

paymentDueBeforeTime integer

optional

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

hotel object

optional

Information on the hotel that the room is located in.

Show definition

room object

optional

Information on room being booked.

Show definition

custom object

optional

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.

order object

required

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

Show definition

orderId string

required

A unique identifier for this order.

creationTime integer

important

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

app object

important

The mobile or web app that this order was submitted on. Used for segmenting business analytics and creating app-specific risk profiles.

Show definition

status

important

The stage of order in the purchase and delivery flow. Used in reporting.

One of the following:

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

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

Failed: Something went wrong, and the order can no longer be fulfilled.

Show definition

Cancelled: The order has been cancelled.

Show definition

Fulfilled: The goods have been provided to the customer and payment has been successfully taken.

Show definition

Refunded: The order has been refunded.

Show definition

price integer

important

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.

currency string

important

The currency of the price for this order as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

country string

important

The country the order should be attributed to for reporting and risk bucketing. Should reflect the country segmentation that you use for your reporting internally, whether that's by billing or shipping address, for example.

market string

important

The country-group market the customer belongs to. E.g. 'southamerica', 'europe', 'emea'. Used for reporting and risk bucketing.

Pattern: ^[0-9a-z-]*$

marketCity string

important

The city that the customer belongs to. Used for reporting and risk bucketing.

Pattern: ^[0-9a-z-]*$

category string

optional

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.

to object

important

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

from object

optional

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

items array

important

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

quantity integer

required

Number of copies of this item that are present in the basket (set to 0 to remove).

sku string

optional

A merchant specific identifier for an item or a service.

name string

optional

The name of the product or service that is being purchased.

price integer

important

The total price for a single one of these items, in the currency's basic units.

currency string

optional

The currency of the price for this order item as an ISO 4217 currency code. Defaults to order currency.

Pattern: ^[a-zA-Z]{3}$

brand string

optional

The name of the brand that the item is from.

upc string

optional

The name of the Universal Item Code.

category string

optional

The highest level category that this item is sold in.

subcategory string

optional

A category that this item is sold in.

executionTime integer

optional

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

eventTicket object

optional

If the item being purchased is a ticket for an event, associate the ticket and event information here.

Show definition

ticket object

required

The ticket information for this event.

Show definition

event object

required

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.

Show definition

eventId string

required

A unique identifier for this event.

category string

required

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.

venue object

required

The location the event will take place.

Show definition

name string

optional

The name of the event.

description string

optional

A short description of the event.

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

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

guest object

optional

The individual who will be attending the event.

Show definition

travelTicket

optional

If the item being purchased is a ticket for travel, associate the journey information here.

Show definition

ticketId string

required

A unique identifier for the ticket

description string

optional

A human-readable text description of what the ticket provides

passenger object

optional

The person travelling with this ticket.

Show definition

routes array

optional

The list of routes that this ticket grants the holder travel on.

Show definition

direction string

optional

The direction of travel along this route, e.g. 'outward' or 'return'.

journeyId string

optional

legs array

optional

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

legId string

required

The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')

departurePortCode string

optional

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

departurePort object

optional

The location of the departure port for the current leg. For flights: the location of the airport.

Show definition

departureCity string

optional

The name of the city of departure for the current leg.

departureCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.

departureTime integer

optional

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

arrivalPortCode string

optional

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

arrivalPort object

optional

The location of the arrival port for the current leg. For flights: the location of the airport.

Show definition

arrivalCity string

optional

The name of the city of arrival for the current leg.

arrivalCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.

arrivalTime integer

optional

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

carrierName string

optional

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

carrierCode string

optional

A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.

transportationType string

optional

The type of transportation.

One of: plane, train, bus, or ship.

seatReservation boolean

optional

Whether there are seat reservations on this leg.

custom object

optional

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 object

optional

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 boolean

optional

If the passenger purchased travel insurance.

ticketClass string

optional

The class of travel this ticket grants access to.

One of: business, economy, first, or standard.

ticketType string

optional

The type of ticket this belongs to. This includes round trip, multi city, open return, etc

validUntilTime integer

optional

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

fulfilmentMethod string

optional

The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc

loyaltyCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

discountCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

accommodation object

optional

If the item being purchased represents accommodation being booked, associate the trip information here.

Show definition

refundable boolean

required

Whether this booking is refundable or not.

payOnArrival boolean

required

Whether the payment is taken at the hotel during check-in.

guest object

optional

Show definition

freeCancellationUntilTime integer

optional

Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.

paymentDueBeforeTime integer

optional

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

hotel object

optional

Information on the hotel that the room is located in.

Show definition

room object

optional

Information on room being booked.

Show definition

custom object

optional

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 string

optional

Descriptive text relating to the contents or nature of the order being completed.

email string

optional

Contact e-mail for this order.

telephone string

optional

Contact phone number for this order. Best in E.164 format with an international dialing code.

telephoneCountry string

optional

Contact phone number's country

sellerId string

deprecated

The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. The restaurant, driver ID, etc.

custom object

optional

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 integer

deprecated

Deprecated in favour of items.executionTime. Execution or pick-up time of the order.

suppliers array

optional

Suppliers (e.g. restaurants, couriers or drivers) involved in this order.

Show definition

eventType string

optional

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

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

paymentMethods array

important

One or more payment methods where the refund is being issued to.

transactions array

important

One or more attempts for the payment method to be refunded for an order.

Show definition

transactionId string

important

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.

time integer

important

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

amount integer

important

The amount to be charged to the payment method, in the currency's basic units.

currency string

optional

The currency of the amount of this transaction, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

type string

important

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, see Associating refunds with 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.

paymentMethodId string

important

The ID of the payment method to be charged in this transaction.

gateway string

important

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

gatewayReference string

important

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.

success boolean

important

Whether the transaction successfully completed with no error.

3ds object

optional

Details on how 3D Secure (3DS) was used to authenticate the transaction.

Show definition

attempted boolean

optional

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.

challenged boolean

optional

Set to true if a step-up authentication was initiated, for example, the customer 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 customer, then this field should be set to false.

In 3DS2, if a customer achieves a frictionless authentication this should also be set to false.

success boolean

optional

Set to true if the customer 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 customer 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.

startTime integer

optional

The time at which the customer was directed to 3DS.

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

endTime integer

optional

The time at which the customer returned from 3DS.

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

timedOut boolean

optional

Whether the customer is believed to have abandoned 3DS.

version string

optional

The version of 3DS which was used to authenticate the customer. Either 1.0.2 or 2.1.0

liabilityShifted boolean

optional

Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer. (See Liability Shift.)

authenticationValue string

deprecated

This field is deprecated, we do not use it in the Ravelin platform.

eci string

optional

The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.

transStatus string

optional

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 customer was challenged.

transStatusReason string

optional

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)

messageType string

optional

Identifies the type of message from which the transStatus value was received. (3DS 2 only)

iReqCode string

optional

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)

declineCode string

important

the decline code from the payment gateway, if applicable.

authCode string

optional

A code returned from the payment gateway after an attempt to charge, if applicable.

avsResultCode object

optional

The result of AVS checks. You must have at least one of street or postal code.

Any of the following:

Show definition

cvvResultCode string

optional

The result of CVV verification from the issuer, compatible with common PSP codes.

mcc string

optional

The Merchant Category Code associated with the transaction.

mid string

optional

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.

acquirerId string

optional

The acquirer is a financial institution with whom the merchant has a bank account.

acquirerBin string

optional

The BIN (Bank Identification Number) of the acquirer.

acquirerCountryCode string

optional

The three letter country code of the country in which your acquirer will settle the payment.

custom object

optional

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 boolean

deprecated

Whether this transaction is associated with a chargeback.

email string

deprecated

The e-mail that the customer wants to be notified about this transaction on.

debit integer

deprecated

Deprecated in favour of amount. The debit amount of the transaction in the lowest denomination of the currency.

credit integer

deprecated

Deprected in favour of amount. The credit amount of the transaction in the lowest denomination of the currency.

device object

optional

The device used by the customer to trigger this update.

Show definition

deviceId string

required

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

ipAddress string

important

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.

language string

optional

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

userAgent string

important

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent.

model string

important

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

os string

important

The operating system that the device is running.

type string

optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string

optional

The maker of the device.

location object

optional

The geolocated position of the device.

Show definition

custom object

optional

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 string

deprecated

The name of the web browser being used, if applicable. Prefer userAgent.

javascriptEnabled boolean

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean

deprecated

Whether cookies are enabled on the web browser.

screenResolution string

deprecated

The resolution of the screen on the device in the format XxY

POST /v2/refund HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM"
  },
  "refund": {
    "refundId": "abc-123-ZYZ",
    "status": "OPEN",
    "refundRequestTime": 1512828988826,
    "refundIssuedTime": 1512828988826,
    "amount": 10000,
    "currency": "GBP",
    "nonRefundableAmount": 10000,
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ]
  },
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "category": "delivery",
    "to": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "from": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ],
    "email": "jsmith@example.com",
    "telephone": "+441234558887",
    "telephoneCountry": "GBR",
    "sellerId": "abcde12345-ZXY",
    "executionTime": 1512828988826,
    "suppliers": [
      {
        "supplierId": "abc-123-ZYZ",
        "status": {
          "stage": "fulfilled",
          "timestamp": 1512828988826,
          "reason": "Could not find passenger"
        },
        "fee": 250,
        "debt": 1000,
        "tip": 200,
        "currency": "GBP",
        "type": "courier"
      }
    ]
  },
  "paymentMethods": [
    {
      "methodType": "card",
      "paymentMethodId": "pm-abc123",
      "scheme": "visa",
      "instrumentId": "fp_abc123",
      "cardBin": "535522",
      "cardLastFour": "0001",
      "expiryMonth": 7,
      "expiryYear": 2020,
      "eWallet": "applepay",
      "nameOnCard": "John Smith",
      "billingAddress": {
        "country": "GBR",
        "postalCode": "E1 1AA",
        "latitude": 51.503252,
        "longitude": -0.127899,
        "addresseeName": "John Smith",
        "street1": "123 fake st.",
        "street2": "floor 4, flat 48",
        "neighbourhood": "Hackney",
        "zone": "1",
        "city": "London",
        "region": "California",
        "poBoxNumber": "1234"
      },
      "corporateCard": true,
      "virtualCard": true,
      "successfulRegistration": true,
      "registrationTime": 1512828988826,
      "lastVerified": 1512828988826,
      "compromised": true,
      "compromisedReason": "stolen",
      "billingFamilyName": "Smith",
      "billingGivenName": "John"
    }
  ],
  "transactions": [
    {
      "transactionId": "123-abc-XYZ",
      "time": 1480340580291,
      "amount": 10000,
      "currency": "GBP",
      "type": "refund",
      "paymentMethodId": "pm-abc123",
      "gateway": "example-gateway",
      "gatewayReference": "123-abc-XYZ",
      "success": true,
      "mcc": "0742",
      "mid": "mid-1",
      "acquirerId": "adyen",
      "acquirerBin": "123456",
      "acquirerCountryCode": "GBR"
    }
  ],
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "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": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Feedback

Was this page helpful?