Skip to content

Commit ea25fbb

Browse files
author
Mark Fowler
committed
Merge pull request #1 from maxmind/greg/docs
Add documentation
2 parents 6f68884 + a6b10a5 commit ea25fbb

42 files changed

Lines changed: 1141 additions & 331 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 140 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,38 +2,125 @@
22

33
This is an early pre-release version. Don't use it.
44

5+
## Description ##
6+
7+
This package provides an API for the [MaxMind minFraud Score and Insights
8+
web services](http://dev.maxmind.com/minfraud-score-and-insights-api-documentation).
9+
10+
## Installation ##
11+
12+
We recommend installing this package with [Maven](http://maven.apache.org/).
13+
To do this, add the dependency to your pom.xml:
14+
15+
```xml
16+
<dependency>
17+
<groupId>com.maxmind.minfraud</groupId>
18+
<artifactId>minfraud</artifactId>
19+
<version>0.0.1</version>
20+
</dependency>
21+
```
22+
23+
## Usage ##
24+
25+
To use this API, first create a new `WebServiceClient` object. The constructor
26+
takes your MaxMind user ID, license key, and an optional options array as
27+
arguments. For example:
28+
29+
```java
30+
WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890").build();
31+
```
32+
33+
Then create a new `Transaction` object. This represents the transaction that
34+
you are sending to minFraud. The class is instantiated using an inner builder
35+
class, `Transaction.Builder`. Each builder method takes a corresponding
36+
request model object. Each of these objects is similarly built up with
37+
corresponding builder classes. For example:
38+
39+
```java
40+
Transaction transaction = new Transaction.Builder(
41+
new Device.Builder(InetAddress.getByName("1.1.1.1")).build()
42+
).email(
43+
new Email.Builder()
44+
.address("fraud@ster.com")
45+
.build()
46+
).build();
47+
```
48+
49+
After creating the transaction object, send a Score request by calling the
50+
`score` method:
51+
52+
```java
53+
Score score = client.score(transaction);
54+
```
55+
56+
or an Insights request by calling `insights` method:
57+
58+
```java
59+
Insights score = client.insights(transaction);
60+
```
61+
62+
If the request succeeds, a model object will be returned for the endpoint.
63+
If the request fails, an exception will be thrown.
64+
65+
See the API documentation for more details.
66+
67+
### Exceptions ###
68+
69+
Runtime exceptions:
70+
71+
* `IllegalArgumentException` - This will be thrown when an illegal argument
72+
is passed to a builder method. For instance, a country code that is not
73+
two capital letters.
74+
75+
Checked exceptions:
76+
77+
* `AuthenticationException` - This will be thrown by `score(transaction)` or
78+
`insights(transaction)` on `WebServiceClient` when the server is unable to
79+
authenticate the request, e.g., if the license key or user ID is invalid.
80+
* `InsufficientFundsException` - This will be thrown by `score(transaction)` or
81+
`insights(transaction)` on `WebServiceClient` when your account is out of funds.
82+
* `InvalidRequestException` - This will be thrown by `score(transaction)` or
83+
`insights(transaction)` on `WebServiceClient` when the server rejects the
84+
request for another reason such as invalid JSON in the POST.
85+
* `MinFraudException` - This will be thrown by `score(transaction)` or
86+
`insights(transaction)` on `WebServiceClient` when the server returns an
87+
unexpected response. This also serves as the base class for the above
88+
checked exceptions.
89+
* `HttpException` -This will be thrown by `score(transaction)` or
90+
`insights(transaction)` on `WebServiceClient` when an unexpected HTTP error
91+
occurs such as an internal server error or other unexpected status code.
592

693
## Example
794

895
```java
996

10-
InsightsRequest request = new InsightsRequest.Builder(
97+
Transaction request = new Transaction.Builder(
1198
new Device.Builder(InetAddress.getByName("1.1.1.1"))
1299
.acceptLanguage("en-US")
13100
.userAgent("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36")
14101
.build()
15102
).account(
16103
new Account.Builder()
17-
.userId("fdasf")
18-
.username("fdasfaf")
104+
.userId("usr-123")
105+
.username("fraudster9")
19106
.build()
20107
).billing(
21108
new Billing.Builder()
22-
.address("11 fdasf ave.")
109+
.address("11 Wall St.")
23110
.address2("Apt 1")
24-
.city("City")
25-
.company("company")
26-
.firstName("Frst")
27-
.lastName("Lst")
111+
.city("New Haven")
112+
.company("Company, Inc")
113+
.firstName("Mike")
114+
.lastName("Smith")
28115
.phoneCountryCode("1")
29116
.phoneNumber("321-321-3211")
30-
.postal("23132")
31-
.region("OR")
117+
.postal("06510")
118+
.region("CT")
32119
.build()
33120
).creditCard(
34121
new CreditCard.Builder()
35122
.avsResult('N')
36-
.bankName("BanK name")
123+
.bankName("BanK of New Haven")
37124
.bankPhoneCountryCode("1")
38125
.bankPhoneNumber("313-231-3213")
39126
.cvvResult('Y')
@@ -42,80 +129,90 @@ InsightsRequest request = new InsightsRequest.Builder(
42129
.build()
43130
).email(
44131
new Email.Builder()
45-
.address("fasdf@fasf.com")
46-
.domain("fadsfd.com")
132+
.address("fraud@ster.com")
133+
.domain("ster.com")
47134
.build()
48135
).event(
49136
new Event.Builder()
50137
.shopId("2432")
51138
.time(new Date())
52-
.transactionId("Fdasf")
139+
.transactionId("tr1242")
53140
.type(Event.Type.ACCOUNT_CREATION)
54141
.build()
55142
).order(
56143
new Order.Builder()
57-
.affiliateId("fasdf")
144+
.affiliateId("af5")
58145
.amount(new BigDecimal(Double.toString(1.1)))
59146
.currency("USD")
60-
.discountCode("fdasf")
61-
.referrerUri("http://www.bldfa.com/fad")
62-
.subaffiliateId("fsaf")
147+
.discountCode("10OFF")
148+
.referrerUri("http://www.google.com/")
149+
.subaffiliateId("saf9")
63150
.build()
64151
).payment(
65152
new Payment.Builder()
66-
.declineCode("dfsa")
153+
.declineCode("invalid")
67154
.processor(Payment.Processor.ADYEN)
68-
.wasAuthorized(true)
155+
.wasAuthorized(false)
69156
.build()
70157
).shipping(
71158
new Shipping.Builder()
72-
.region("fa")
73-
.postal("31331")
159+
.region("MN")
160+
.postal("55455")
74161
.phoneNumber("313-545-3113")
75162
.phoneCountryCode("1")
76163
.deliverySpeed(Shipping.DeliverySpeed.EXPEDITED)
77-
.address("32 fdas st.")
164+
.address("32 Washington Ave.")
78165
.address2("18")
79-
.city("Fdaf")
80-
.company("fdasf")
81-
.firstName("Ffads")
82-
.lastName("Fdaf")
166+
.city("Minneapolis")
167+
.company("MinnCo")
168+
.firstName("John")
169+
.lastName("Doe")
83170
.build()
84171
).addShoppingCartItem(
85172
new ShoppingCartItem.Builder()
86-
.category("fdas")
87-
.itemId("Fdas")
173+
.category("TOYS")
174+
.itemId("t-132")
88175
.price(1.1)
89176
.quantity(100)
90177
.build()
91178
).addShoppingCartItem(
92179
new ShoppingCartItem.Builder()
93-
.category("hfd")
94-
.itemId("fde")
180+
.category("COSMETICS")
181+
.itemId("c-12312")
95182
.price(3.)
96183
.quantity(1)
97184
.build()
98185
).build();
99186

100-
WebServiceClient client = new WebServiceClient.Builder(6, "1234567890").build();
187+
WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890").build();
101188

102189

103190
System.out.println(client.insights(request));
104191
```
105192

106-
## Copyright and License
193+
## Support ##
194+
195+
Please report all issues with this code using the
196+
[GitHub issue tracker](https://github.com/maxmind/minfraud-api-java/issues).
197+
198+
If you are having an issue with the minFraud service that is not specific
199+
to the client API, please see
200+
[our support page](http://www.maxmind.com/en/support).
201+
202+
## Requirements ##
203+
204+
This code requires Java 7.
205+
206+
## Contributing ##
207+
208+
Patches and pull requests are encouraged. Please include unit tests whenever possible.
107209

108-
This software is Copyright © 2015- by MaxMind, Inc.
210+
## Versioning ##
109211

110-
This is free software, licensed under the Apache License, Version 2.0 (the "License");
111-
you may not use this software except in compliance with the License.
212+
This API uses [Semantic Versioning](http://semver.org/).
112213

113-
You may obtain a copy of the License at
214+
## Copyright and License ##
114215

115-
http://www.apache.org/licenses/LICENSE-2.0
216+
This software is Copyright (c) 2015 by MaxMind, Inc.
116217

117-
Unless required by applicable law or agreed to in writing, software
118-
distributed under the License is distributed on an "AS IS" BASIS,
119-
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
120-
See the License for the specific language governing permissions and
121-
limitations under the License.
218+
This is free software, licensed under the Apache License, Version 2.0.

‎pom.xml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@
2121
<name>MaxMind, Inc.</name>
2222
<url>http://www.maxmind.com/</url>
2323
</organization>
24+
<properties>
25+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
26+
</properties>
2427
<dependencies>
2528
<dependency>
2629
<groupId>com.maxmind.geoip2</groupId>
@@ -104,6 +107,13 @@
104107
</execution>
105108
</executions>
106109
</plugin>
110+
<plugin>
111+
<groupId>org.apache.maven.plugins</groupId>
112+
<artifactId>maven-javadoc-plugin</artifactId>
113+
<configuration>
114+
<show>public</show>
115+
</configuration>
116+
</plugin>
107117
<plugin>
108118
<groupId>org.apache.maven.plugins</groupId>
109119
<artifactId>maven-gpg-plugin</artifactId>
@@ -198,4 +208,4 @@
198208
</plugin>
199209
</plugins>
200210
</build>
201-
</project>
211+
</project>

0 commit comments

Comments
 (0)