Requesting Recommendations

On this page:

In this section, you’ll find information on how to send payout data to Ravelin to obtain recommendations. Using these recommendations, you can decide whether to allow or block a payout to its recipient.

How to request recommendations

To request a recommendation before paying out to a recipient, send a request to our Payout endpoint using the Payout checkpoint.

To use the Payout checkpoint, add score=payout as a query parameter to the URL.

The payout object should contain details about the payout attempt.

We strongly recommend sending all fields in the Payout endpoint API reference that are marked as important. The more fields you can populate, the better our recommendation will be.

Payout Request Example

An example request for a payout is shown below:

POST https://api.ravelin.com/v2/payout HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "payout": {
    "payoutId": "payout_123",
    "status": "CREATED",
    "earnings": {
      "currency": "GBP",
      "totalGrossAmount": 5100,
      "baseAmount": 1000,
      "compensationAmount": 200,
      "bonusAmount": 900,
      "withheldTaxAmount": 100,
      "onPlatformRevenue": 2000,
      "totalNetAmount": 5000,
      "feeAmount": 1000
    },
    "revenueSource": {
      "ads": 500,
      "referral": 500,
      "promo": 600,
      "subscriptions": 100,
      "purchase": 200,
      "others": 100
    },
    "periodStart": 1667260800000,
    "periodEnd": 1669852800000,
    "creationTime": 1512828988826,
    "payoutTime": 1512828988826,
    "schedule": "MONTHLY",
    "initiatedBy": "SUPPLIER",
    "notificationEmail": "jsmith123@example.com"
  },
  "supplier": {
    "supplierId": "abc-123-ZYZ",
    "groupId": "abc-123",
    "groupName": "Burger Chain",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "GBR",
    "type": "driver",
    "level": "gold",
    "employmentType": "selfEmployed",
    "transportType": "car",
    "category": "private-hire",
    "identityVerified": false,
    "tags": {
      "foo": true,
      "bar": false
    }
  },
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "scheme": "visa",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "nameOnCard": "John Smith",
    "corporateCard": true,
    "virtualCard": true,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826,
    "compromised": true,
    "compromisedReason": "stolen",
    "eWallet": "applepay"
  }
}

Payout Response Example:

An example response for a payout is shown below:

{
  "status": 200,
  "timestamp": 1694596480,
  "data": {
    "supplierId": "abc-123-ZYZ",
    "payoutId": "payout_123",
    "action": "ALLOW",
    "source": "RAVELIN"
  }
}

How to handle recommendations

The data.action field in the response contains our recommendation, you should use this to determine how you handle the payout attempt. The table below explains the possible actions.

Action	What it means
`ALLOW`	We think the payout is for a genuine recipient. Allow the payout to proceed.
`PREVENT`	We suspect the payout is fraudulent. Prevent the payout

You can also configure additional custom actions which suit your business needs. Please speak to our integration team to set these up.

Next steps

Update us with the payout outcome

Test your integration

Feedback

Was this page helpful?