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 voucher: REFERRAL REACTIVATION GENERAL
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 call is made to the Ravelin POST /v2/voucher/check endpoint to ask if the voucher may be redeemed by this customer. Ravelin returns a recommendation for whether the customer should be allowed to redeem the voucher in the response. The client can accept or reject 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
timestamp integer The unix timestamp, in seconds, of the time now

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 voucher: REFERRAL REACTIVATION GENERAL
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

Scenarios

Scenario Action
You've already redeemed that code Ravelin returns 'ABUSE' when check via POST v2/voucher/check
If the count of voucher owners + voucher users > 2 in the network of the customer in the call to /v2/voucher/check Ravelin returns ‘ABUSE’
Another account which looks like yours has already redeemed that voucher (right now based on matching phone numbers and/or credit card fingerprints) Ravelin returns 'ABUSE' when check via POST v2/voucher/check
This device you're using has already redeemed this voucher Ravelin returns 'ABUSE' when check via POST v2/voucher/check