Operator APIs | Data Ingestion
Data Ingestion API Authentication
Data Ingestion is a product that allows NetRefer clients to use REST principles to ingest data into the PMP.
It is possible to ingest data in real-time sending a single event or in batch.
To access the APIs, clients should have an appropriate account registered with NetRefer.
This account provides access to specific NetRefer products, which in our case is API.
Also, clients must provide a Subscription Key allowing access to Data Ingestion APIs.
The authentication flow is depicted conceptually in the diagram below.
Using Active Directory to request a JWT
OAuth 2.0 is used to get access to the Data Ingestion API.
To authenticate within NetRefer and to call the Data Ingestion API, developers must request JWT, providing the following parameters:
Grant type: password
Client ID: will be provided to the client while onboarding to Data Ingestion. Example of id is: 5a324196-7727-45fd-8ac3-1436cd541d76
Access Token URL: https://login.microsoftonline.com/0e0b50ac-5253-4347-b528-251b2f17cfc6/oauth2/v2.0/token
Client Secret: will be provided to the client while onboarding to Data Ingestion
Username: will be provided to the client while onboarding to Data Ingestion
Password: will be provided to the client while onboarding to Data Ingestion
Scope: api://5a324196-7727-45fd-8ac3-1436cd541d76/Events.Injestion
Once all the requirements are met, execute an HTTP POST call to "Access Token URL" to get the JWT.
In the API request, you have to add an "Authorization" header with the value:
Bearer JWT-value-from-NetRefer-Data Ingestion
An example of a request using different languages can be found on the APIs page of this portal.
Authorization to use Data Ingestion product
To authenticate access to the Data Ingestion product, HTTP requests must include an additional header:
Ocp-Apim-Subscription-Key: will be provided to the client during onboarding to Data Ingestion. Example: baea25a9f0fe4687845575c07e539a9e9
A full example of the Data Ingestion API call is illustrated in the diagram below.
Data Ingestion API usage
All Data Ingestion APIs are exposed as REST endpoints.
Request and response models
Request data models are presented and described via the OpenAPI specification.
These specifications can be downloaded from the portal and the developers can build their own code proxies.
In the Developer Portal, you can also find an example of request\response objects and their schema:
Response Status Codes
Web API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:
Capacities
The Data Ingestion API accepts a payload of up to 900kb using approximately 2500 events in each payload.
Activity and Deposit events can be corrected with the Data Ingestion API. All other events can not be corrected.
Glossary
An 'Adjustment' refers to an Activity or a Deposit complete reversal.
A 'Correction' refers to an event that alters the values of an Activity event.
A 'Deposit Correction' refers to an event that alters the values of a deposit.
Activity Event Case Scenarios
The Activity Event accepts 3 attributes that identify the purpose of the activity Event. The 3 activity states are 'a bet is placed', 'a bonus is redeemed' and a 'bet is closed'. The below table shows how to send the data to identify each activity type.
Scenario
Wager
Bonus
Gross Gaming Revenue
A bet is placed
>0
0
0
A bonus is redeemed
0
>0
0
A bet is closed
0
>=0
<0, >0
A bet is placed refers to the activity a player does in the beginning of a game, bet etc where a player would use part of their credit to wager on a game/bet.
A bonus is redeemed refers to the activity a player does in the beginning of a game, bet etc where a player would use part of their bonus credit to wager on a game/bet.
A bet is closed refers to the final state of a game/bet. This is where the winnings or losses of a player is recorded. A player can at this stage earn some Bonus credit, generate a positive GGR, or generate a negative GGR.
Kindly note that our platform is not intended to be used as a player wallet and neither is it a financial system. Data and Monitory values recorded in our platform are intended to be used for Marketing performance purposes.
Different Operators have different operational needs the below are some case scenarios that Operators might encounter whilst doing an integration.
Player makes Wagers with their own credit and with some Bonus and generates a GGR
Transaction
Wager
Bonus
Gross Gaming Revenue
A bet is placed
50
0
0
A bonus is redeemed
0
10
0
A bet is closed
0
0
30
Player makes a wager with their own credit generates some GGR but also gains some Bonus credit
Transaction
Wager
Bonus
Gross Gaming Revenue
A bet is placed
50
0
0
A bet is closed
0
20
30
Data Ingestion Data Model and Error Codes
Learn more about common Data Ingestion Developer error codes and how to resolve them.
Error codes describe events’ validation statuses of the DATA INGESTION API.
If you don't find an error code listed here, please refer to the API-specific error codes in their respective documentation pages.
All events are sent in batches but processed individually. If all events are valid, then 200 will be returned. If some of the events are not valid, then 207 will be returned. If all the events are not valid, then 400 will be returned.
Additional validation for all event types:
multiple events with the same EventID must not be processed
JSON with unproper multiple structures must not be processed
What to do if Data Ingestion is having issues?
Data Ingestion is designed on the most cutting-edge technology stack and platform.
The API is constantly available, allowing for real-time data input.
If the API is unavailable for any reason, or if the status codes received are one of the following, Data Ingestion customers should follow these guidelines:
Contact your consultant and/or NetRefer Support if you have 401, 403, 404, or 500 (if it appears for a long period of time).
We recommend using the retry strategy to trigger your endpoints until they succeed in providing real-time data intake (and to be proactive with 500 error code processing). There may be a one-, three-, five-, or ten-minute time gap between calls, or any other interval the customer chooses.
Deposit Method
Withdrawal Method
ID
UN
CHEQUE
CLICK BUY
CREDEB
CREDEB MARKETING
CREDEB POKER
ENVOY
Skrill
NETTELLER
PAYPAL
PAYAL FEE
TRANSFER
UNKNOWN
WEB MONEY
Bank Transfer
Ukash
InstaDebit
Debit/Credit Card
Voucher
Tigo Pesa
Vodacom M-Pesa
PaySafeCard
Rapid Transfer
Postepay
Trustly
Revolut
ClickandBuy
ecoPayz
Entropay
Yandexmoney
Moneta
Sofort
CryptoCurrencies
MUCHBETTER
eZeeWallet
AstroPay
Apple Pay
Google Pay
NetBanking
Paytm
PhonePe
UPI
Boku
Multibanco
Giropay
Qiwi Wallet
SafeCharge
HiPay
CartaSi
Interac
Euteller
MB WAY
Zimpler
PugglePay
Klarna
Neosurf
POLi
Ozow
SiD
Peach Payments
OTT Voucher
zapper
1ForYou
airtel
HalCash
P24
Halopesa
EzyPesa
Selcom Paypoint
iDEAL
Mifinity
Siru Mobile
Bizum
INOVAPAY
Pay4Fun
CashtoCode
Banco Posta
Flexepin
WeChat Pay
Alipay
Jeton
Dash
Bambora
Other
UN
CHEQUE
CLICK BUY
CREDEB
CREDEB MARKETING
CREDEB POKER
ENVOY
Skrill
NETTELLER
PAYPAL
PAYAL FEE
TRANSFER
UNKNOWN
WEB MONEY
Bank Transfer
Ukash
InstaDebit
Debit/Credit Card
Voucher
Tigo Pesa
Vodacom M-Pesa
PaySafeCard
Rapid Transfer
Postepay
Trustly
Revolut
ClickandBuy
ecoPayz
Entropay
Yandexmoney
Moneta
Sofort
CryptoCurrencies
MUCHBETTER
eZeeWallet
AstroPay
Apple Pay
Google Pay
NetBanking
Paytm
PhonePe
UPI
Boku
Multibanco
Giropay
Qiwi Wallet
SafeCharge
HiPay
CartaSi
Interac
Euteller
MB WAY
Zimpler
PugglePay
Klarna
Neosurf
POLi
Ozow
SiD
Peach Payments
OTT Voucher
zapper
1ForYou
airtel
HalCash
P24
Halopesa
EzyPesa
Selcom Paypoint
iDEAL
Mifinity
Siru Mobile
Bizum
INOVAPAY
Pay4Fun
CashtoCode
Banco Posta
Flexepin
WeChat Pay
Alipay
Jeton
Dash
Bambora
Other
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
Deposit/Withdrawal Methods
The following is a list of pre-defined deposit and withdrawal methods:
FAQs
What is an Adjustment Event?
An Adjustment Event can be one of two types:
Chargeback: This process involves reversing a transaction and returning funds to a customer's account, typically due to a dispute or fraudulent activity.
BetVoid: This feature allows operators to void bets that have been placed by customers.
Additional Information:
Transaction ID: The Transaction ID must refer to a previous activity event.
Amount Field: There is no "amount" field for Adjustments because these events will remove the value entirely and will not change the previously populated value.
Case scenarios:
The operator notices that they have sent us duplicate deposits, they send an adjustment event for each Deposit they would like to chargeback.
The operator notices that they have sent us bets related to a fraudulent account and would like to void those bets.
What is a Correction Event?
A Correction Event is used when a previous event was sent with an incorrect value. To correct this, you need to provide the following information:
Transaction ID: The Transaction ID of the event that needs correction.
Attribute: The specific attribute within the event that needs to be corrected.
New Amount: The new amount that should replace the incorrect value.
Make sure to submit the specific transaction ID being "edited" for accurate processing.
What is the Deposit Fee?
The Deposit Fee is not a mandatory field that only accepts positive values. It represents the fee associated with each deposit. If your system does not capture deposit fees, you can set this value to '0' or not send the attribute at all.
What values should be supplied for DepositMethodID and WithdrawalMethodID?
The values for DepositMethodID and WithdrawalMethodID depend on the specific payment methods being used. It is important to use the correct values for these fields. You can find the corresponding list of values on the Developer Portal under: … /Operator-api/Data-Ingestion > Deposit/Withdrawal Methods
What is the logic behind the combination of Player Activity Attributes?
There are three main scenarios to consider for Player Activity Attributes:
A Bet is placed:
If the wager field has a value greater than 0, then the GGR and Bonus fields need to be 0.
This represents that the Bet/Wager amount has been placed by the player and the Game/Round/Action is either not yet started or is in progress.
A Bet is closed:
The Wager attribute needs to be 0, indicating that no more new money is being bet on this game.
GGR should be populated with the value won or lost:
If GGR is negative, it indicates the Operator lost and the player won, meaning the Affiliate should not be rewarded.
If GGR is positive, it indicates the Operator won and the player lost, meaning the Affiliate should be rewarded.
The Bonus field can be greater than or equal to 0, depending on whether a bonus was won when closing the bet. This depends on the Operator’s bonus policy.
A Bonus is redeemed:
The Wager field should be 0 as it is not the player's money being used.
Enter the bonus amount in the Bonus field, and set the GGR to 0 as no bet is being closed.
Important Note:
There cannot be an event with all three fields (Wager, GGR, and Bonus) set to 0, as this will produce an error.
