Server integration guide
To improve the accuracy of Bouncer's fraud detection, we recommend notifying bouncer for the following:
- Payment Card Tokenization
- Account Events
Your service can query Bouncer servers at any time (e.g. before allowing a purchase) for a fraud risk score for a given user.
[Required] Card tokenization and fraud score on transaction
Tokenizing a Payment Card
When the client adds a new payment method and that payment method is tokenized (e.g. through Stripe), call this endpoint from your server.
Request
Response
The request must include details about the payment instrument, including the payment method token. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/tokenize
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"user_id": String("<tokenizing_user_id>"),
6
"customer_id": String("<customer_stripe_id>"),
7
"instrument_token": String("<payment_instrument_stripe_token>"),
8
"instrument_last_four": String("<last_four_digits_of_payment_instrument>"),
9
"instrument_iin": Optional String("<first_six_digits_of_payment_instrument>"),
10
"client_ip": Optional String("<ip_address_of_client_adding_payment_instrument>")
11
}
Copied!
The response will include a score from bouncer and a recommendation to challenge or allow the transaction.
1
HTTP 200 OK
2
{
3
"result": "ok"
4
}
Copied!
Getting a fraud risk score
When you are ready to complete a transaction on the iOS or Android SDK make a server-to-server call from your servers to Bouncer to validate the transaction.
Request
Response
The request must include details about the transaction, including the payment instrument used, and the amount to be charged. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/score
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"user_id": String("<transacting_user_id>"),
6
"transaction_amount": Float(<amount_being_charged>),
7
"transaction_currency": String("<three_character_currency_code>"),
8
"customer_id": String("<customer_stripe_id>"),
9
"instrument_token": String("<payment_instrument_stripe_token>"),
10
"instrument_last_four": String("<last_four_digits_of_payment_instrument>"),
11
"instrument_iin": Optional String("<first_six_digits_of_payment_instrument>"),
12
"client_ip": Optional String("<ip_address_of_client_making_transaction>"),
13
"product_sku": Optional Array of Strings("<SKUs of the product purchased>")
14
}
Copied!
The response will include a score from bouncer and a recommendation to challenge or allow the transaction.
1
HTTP 200 OK
2
{
3
"challenge_recommended": true,
4
"fraud_risk_score": 0.4
5
}
Copied!
challenge_recommended will be a boolean indicating whether bouncer recommends challenging the transaction. fraud_risk_score will be a float between 0 and 1 (inclusive) that indicates how fraudulent Bouncer believes this transaction to be.[Optional] Server-to-server account events
These requests should be made after each of these events:
- user signup
- user login
- user update
- payment method added
Sign Up
Request
Response
The request must include details about the event, including the user ID and IP. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/events/add
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"event": "user_create",
6
"occurred_at": Long("<the time in MS since epoch when the event occurred>"),
7
"ip_address": String("<IP address of the client performing the action>"),
8
"session_id": Optional String("<the ID of the session for this user>"),
9
"user_id": String("<id of the user>"),
10
"user_name": Optional String("<username performing the event>"),
11
"phone_number": Optional String,
12
"first_name": Optional String,
13
"last_name": Optional String,
14
"full_name": Optional String,
15
"email": Optional String,
16
"shipping_address": Optional String,
17
"billing_address": Optional String
18
}
Copied!
1
HTTP 200 OK
2
{
3
"result": "ok"
4
}
Copied!
Login
Request
Response
The request must include details about the event, including the user ID and IP. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/events/add
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"event": "user_login",
6
"occurred_at": Long("<the time in MS since epoch when the event occurred>"),
7
"ip_address": String("<IP address of the client performing the action>"),
8
"session_id": Optional String("<the ID of the session for this user>"),
9
"success": Boolean("<whether or not the login attempt succeeded>"),
10
"failure_reason": String("<reason the login failed, one of the following: account_unknown, bad_credentials>"),
11
"user_id": Optional String("<id of the user>"),
12
"user_name": Optional String("<username performing the event>")
13
}
Copied!
1
HTTP 200 OK
2
{
3
"result": "ok"
4
}
Copied!
User Update
Request
Response
The request must include details about the event, including the user ID and IP. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/events/add
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"event": "user_update",
6
"occurred_at": Long("<the time in MS since epoch when the event occurred>"),
7
"ip_address": String("<IP address of the client performing the action>"),
8
"session_id": Optional String("<the ID of the session for this user>"),
9
"user_id": String("<id of the user>"),
10
"user_name": Optional String("<username performing the event>"),
11
"phone_number": Optional String,
12
"first_name": Optional String,
13
"last_name": Optional String,
14
"full_name": Optional String,
15
"email": Optional String,
16
"shipping_address": Optional String,
17
"billing_address": Optional String
18
}
Copied!
1
HTTP 200 OK
2
{
3
"result": "ok"
4
}
Copied!
Add payment method
Request
Response
The request must include details about the event, including the user ID and IP. The request must additionally be authenticated with your API key.
1
POST https://api.getbouncer.com/insight/v1/events/add
2
x-bouncer-auth: <your_api_key>
3
​
4
{
5
"event": "payment_method_add",
6
"occurred_at": Long("<the time in MS since epoch when the event occurred>"),
7
"ip_address": String("<IP address of the client performing the action>"),
8
"session_id": Optional String("<the ID of the session for this user>"),
9
"user_id": Optional String("<id of the user>"),
10
"payment_method_id": String("<customer-defined payment method ID>"),
11
"payment_method_type": String,
12
"payment_gateway": String,
13
"success": Boolean("<true if the payment method was added successfully>"),
14
"card": Optional {
15
"card_brand": Optional String,
16
"card_funding": Optional String,
17
"card_fingerprint": Optional String,
18
"card_bin": Optional String,
19
"card_last4": Optional String,
20
"card_exp_month": Optional String,
21
"card_exp_year": Optional String,
22
"card_name": Optional String,
23
"card_cvc_check": Optional String,
24
"card_zip_check": Optional String,
25
"card_address": Optional {
26
"street1": Optional String,
27
"street2": Optional String,
28
"city": Optional String,
29
"state": Optional String,
30
"zip": Optional String,
31
"country_iso": Optional String
32
}
33
},
34
"failure_type": String,
35
"decline_code": String,
36
"failure_reason": String
37
}
Copied!
1
HTTP 200 OK
2
{
3
"result": "ok"
4
}
Copied!
​