Voucher Abuse API Reference

Overview

Currently, Ravelin only supports voucher abuse detection for referral vouchers (also known as ‘member get member’). Voucher abuse detection with Ravelin is a 3 step process:

  1. Create - When a voucher is created a call is made to Ravelin to create that voucher in the Ravelin system.

  2. Check - Before a customer attempts to redeem a voucher, a call is made to Ravelin asking if this voucher may be redeemed by this customer.

  3. Update - After the voucher redemption attempt has been made, a call is made to Ravelin to indicate this attempt occurred and the outcome of the attempt.

All events should include these fields at the top-level of every event.

Parameter Type Description
timestamp integer The unix timestamp, in milliseconds, of when the event occurred

1. Create a voucher

When a voucher is created, a call is made to the Ravelin POST /v2/voucher endpoint to create the voucher in the Ravelin system.

This call defines the properties of the voucher as follows:

Parameter Type Description
voucherCode string A unique identifier for the voucher.
referrerId string The id of the customer who created this voucher
expiry integer The unix timestamp, in seconds, after which the voucher can no longer be redeemed
value integer The value of the voucher
currency string The ISO 4217 currency code that the value is in
voucherType string The type of the voucher. Either GENERAL, REFERRAL, or REACTIVATION.
referralValue integer The amount the owner of the voucher gets when the voucher is used
creationTime integer The unix timestamp, in seconds, the voucher was created
custom object If you have any data about this customer that does not fit in one of the above fields, please specify it in the custom object

2. Check whether to allow customer to redeem voucher

Before a customer attempts to redeem a voucher, a POST request should be made to the /v2/voucher/check endpoint to ask if the voucher may be redeemed.

Ravelin returns a recommendation for whether the customer should be allowed to redeem the voucher in the response.

This recommendation is calculated by checking for the owner and users of the voucher in the customer’s network. If this total is greater than the relevant threshold Ravelin returns ABUSE, if not Ravelin returns OK.

You can either follow or ignore this recommendation.

The Request object looks like this:

Parameter Type Description
voucherCode string A unique identifier for the voucher
customerId string The id of the customer attempting to redeem this voucher
voucherType string The type of the voucher. Either GENERAL, REFERRAL, or REACTIVATION. Default is GENERAL. This is used to select depth and threshold configuration if those are not specified in this message. Contact Ravelin to set up or change configuration for a voucher type
depth integer How far Ravelin will search for the voucher from the target customer. If omitted or zero, Ravelin will use the configured value for the voucher type, or the default value (10) if there is no configuration. Maxmimum depth is 10
threshold integer Threshold for deciding upon abuse. Ravelin searches for the owner and users of the voucher from the target customer Id for the configured depth. We return ABUSE if the total found is greater than the threshold. If omitted or zero Ravelin will use the configured value for the voucher type, or the default value (2) if there is no configuration.

The Response object looks like this:

Parameter Type Description
recommendation string Ravelin’s recommendation for whether or not to allow the customer to redeem the voucher: OK ABUSE

3. Update Ravelin on voucher redemption attempt outcome

After the voucher redemption attempt is made, a call is made to the Ravelin POST /v2/paymentmethod/voucher endpoint indicating this attempt occurred and the outcome of the attempt. It is important for Ravelin to know both about successful and unsuccessful voucher redemption attempts.

The data sent looks like the following:

Parameter Type Description
paymentMethodId string A unique identifier for this customer’s use of the voucher.
voucherCode string A unique identifier for the voucher.
referrerId string The id of the customer who created this voucher
expiry integer The unix timestamp, in seconds, after which the voucher can no longer be used
value integer The value of the voucher
currency string The ISO 4217 currency code that the value is in
voucherType string The type of the voucher. Either GENERAL, REFERRAL, or REACTIVATION.
redemptionTime integer The unix timestamp, in seconds, of the redemption attempt
success boolean Bool indicating the success or failure of the redemption attempt
failureSource string The source of the failure: RAVELIN CLIENT
failureReason string Optional reason why the attempt was not successful EXPIRED NOT_NEW_CUSTOMER ALREADY_USED ABUSER SYSTEM_FAILURE
custom object If you have any data about this customer that does not fit in one of the above fields, please specify it in the custom object