Refund API Reference

POST /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": 1512828988826,
    "customer": {
        "customerId":"abc-123-ZYZ"
    },
    "order": {
      "orderId": "abcde12345-ZXY"
    },
    "refund":{
        "refundId": "abc-123-GDFS",
        "refundRequestTime": 1636629706000,
        "status": "OPEN",
        "initiatedBy": "CUSTOMER",
        "type": "REFUND",
        "claim": "FULL",
        "policy": "TERMS_AND_CONDITIONS",
        "amount": 1000,
        "currency": "GBP",
        "nonRefundableAmount": 250,
        "issuedTo": "ORIGINAL_PAYMENT_METHOD",
        "items": [
          {
            "name": "Midi Dress",
            "quantity": 1,
            "price": 1000,
            "currency": "GBP",
            "sku": "1234AAB",
            "category": "Clothing",
            "subcategory": "Dresses",
            "brand": "Trendy Threads",
            "refundReason": "ITEM_NOT_RECEIVED"
          }
        ]
      },
    "device": {
      "deviceId": "df020f51-5ebb-4901-82cf-96299225754b"
    }
  }
Name Type Description Example
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
customer
required
object

The customer requesting a refunds.

Hide 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
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-]*$
refund
required
object

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

Hide definition
Name Type Description Example
refundId
required
string

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.

"abc-123-ZYZ"
status
required
string

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
important
integer

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

1512828988826
refundIssuedTime
important
integer

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

1512828988826
initiatedBy
optional
string

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
important
string

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
important
string

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
important
string

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
important
string

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
optional
string

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
important
integer

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

10000
currency
important
string

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

Pattern: ^[a-zA-Z]{3}$
"GBP"
nonRefundableAmount
optional
integer

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.

10000
issuedTo
optional
string

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
optional
string

Descriptive text relating to the refund request.

refundRequestChannel
optional
string

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
optional
array

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
order
required
object

The order describing the goods or services the customer wants to, or has attempted to buy. (See orders.)

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

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
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
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
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
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
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-_]*$
paymentMethods
important
array

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

transactions
important
array

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

Show definition
device
optional
object

The device used by the customer to trigger this update.

Show definition