|
1 | | -# moip-sdk-java |
| 1 | +<img src="https://gist.githubusercontent.com/joaolucasl/00f53024cecf16410d5c3212aae92c17/raw/1789a2131ee389aeb44e3a9d5333f59cfeebc089/moip-icon.png" align="right" /> |
2 | 2 |
|
3 | | -<img src="https://user-images.githubusercontent.com/32847427/42348249-1e007adc-807f-11e8-975f-5075ec3b13ab.png" align="left" /> |
| 3 | +# Moip Java SDK |
| 4 | + |
| 5 | +[](https://circleci.com/gh/moip/moip-sdk-java/tree/master) |
| 6 | +[](https://www.codacy.com/app/rodrigo-saito/moip-sdk-java) |
| 7 | +[](https://github.com/moip/moip-sdk-java/blob/master/LICENSE) |
| 8 | +[](https://slackin-cqtchmfquq.now.sh/) |
| 9 | + |
| 10 | +<details> |
| 11 | + <summary>Index</summary> |
| 12 | + |
| 13 | +* [Simple flow](#simple-flow) |
| 14 | + * [Setup](#setup) |
| 15 | + * [Authentication](#authentication) |
| 16 | + * [Environment](#environment) |
| 17 | + * [Finally](#finally) |
| 18 | + * [Create customer](#create-customer) |
| 19 | + * [Create order](#create-order) |
| 20 | + * [Create Payment](#create-payment) |
| 21 | + * [Other examples](#other-examples) |
| 22 | +* [Exceptions treatment](#exceptions-treatment) |
| 23 | +* [Moip documentation](#moip-documentation) |
| 24 | +* [Getting help](#getting-help) |
| 25 | +* [Contributing](#contributing) |
| 26 | + |
| 27 | +</details> |
| 28 | + |
| 29 | +## Require |
| 30 | + |
| 31 | +Java `v1.8ˆ`  |
| 32 | + |
| 33 | +## Installing |
| 34 | + |
| 35 | +### Gradle |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +Add the fallowing dependency to `build.gradle` in the project: |
| 40 | + |
| 41 | +```gradle |
| 42 | +// https://mvnrepository.com/artifact/br.com.moip/sdk-java |
| 43 | +compile group: 'br.com.moip', name: 'sdk-java', version: 'x.y.z' |
| 44 | +``` |
| 45 | + |
| 46 | +### Maven |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +Add the fallowing dependency to `pom.xml` in the project: |
| 51 | + |
| 52 | +```xml |
| 53 | +<!-- https://mvnrepository.com/artifact/br.com.moip/sdk-java --> |
| 54 | +<dependency> |
| 55 | + <groupId>br.com.moip</groupId> |
| 56 | + <artifactId>sdk-java</artifactId> |
| 57 | + <version>x.y.z</version> |
| 58 | +</dependency> |
| 59 | +``` |
| 60 | + |
| 61 | +### Another installation methods |
| 62 | +https://mvnrepository.com/artifact/br.com.moip/sdk-java |
| 63 | + |
| 64 | +## Simple flow |
| 65 | + |
| 66 | +This step by step will exemplify the integration flow with simple usage examples. |
| 67 | + |
| 68 | +### 1. Setup |
| 69 | +Before making requests to Moip API its necessary create the **Setup** object, defining the environment, the connect timeout, the read timeout and the authentication that will be used. |
| 70 | + |
| 71 | +#### 1.1 Authentication |
| 72 | +There are two ways to authenticate the request, some endpoints require a "highest authorization level", it will depend on the endpoint and type of request. |
| 73 | +```java |
| 74 | +import br.com.moip.models.Setup; |
| 75 | + |
| 76 | +Setup setup = new Setup().setAuthentication(auth).setEnvironment(ENVIRONMENT); |
| 77 | +``` |
| 78 | + |
| 79 | +#### By BasicAuth |
| 80 | +The following set will generate a hash `Base64` with your Moip account **token** and **key** to authenticate. |
| 81 | +```java |
| 82 | +import br.com.moip.auth.Authentication; |
| 83 | +import br.com.moip.auth.BasicAuth; |
| 84 | + |
| 85 | +String token = "01010101010101010101010101010101"; |
| 86 | +String key = "ABABABABABABABABABABABABABABABABABABABAB"; |
| 87 | + |
| 88 | +Authentication auth = new BasicAuth(token, key); |
| 89 | +``` |
| 90 | + |
| 91 | +> :bulb: If you don't know how to get your **token** and **key**, click [here](https://conta-sandbox.moip.com.br/configurations/api_credentials) (you must be logged in). |
| 92 | +
|
| 93 | +#### By OAuth |
| 94 | +The following set will create an OAuth authentication object. |
| 95 | + |
| 96 | +> :bulb: Click [here](https://dev.moip.com.br/v2.0/reference#autenticacao-mp) to know how to get your token OAuth. |
| 97 | +
|
| 98 | +```java |
| 99 | +import br.com.moip.auth.Authentication; |
| 100 | +import br.com.moip.auth.OAuth; |
| 101 | + |
| 102 | +String oauth = "8833c9eb036543b6b0acd685a76c9ead_v2"; |
| 103 | + |
| 104 | +Authentication auth = new OAuth(oauth); |
| 105 | +``` |
| 106 | + |
| 107 | +#### 1.2 Environment |
| 108 | +We have some environments that you can send your requests. |
| 109 | + |
| 110 | +##### Sandbox |
| 111 | +The test environment. You can use this to simulate all of your business scenarios. |
| 112 | + |
| 113 | +``` |
| 114 | +Setup.Environment.SANDBOX |
| 115 | +``` |
| 116 | + |
| 117 | +##### Production |
| 118 | +**_"The environment of truth"_** :eyes:. This is the environment where the real transactions run. |
| 119 | + |
| 120 | +``` |
| 121 | +Setup.Environment.PRODUCTION |
| 122 | +``` |
| 123 | + |
| 124 | +> :bulb: Before going to production, you need to request homologation of your application [here](https://dev.moip.com.br/page/homologacao-api-v2). |
| 125 | +
|
| 126 | +##### Connect |
| 127 | +The connect URL must be used only for operations involving another Moip accounts (_request connect permission, generate the account accessToken, refresh account accessToken_). |
| 128 | + |
| 129 | +> :bulb: If you want to know more about the Moip Connect flow, check [here](https://dev.moip.com.br/docs/app-1) (PT-BR). |
| 130 | +
|
| 131 | +**Sandbox** |
| 132 | +``` |
| 133 | +Setup.Environment.CONNECT_SANDBOX |
| 134 | +``` |
| 135 | + |
| 136 | +**Production** |
| 137 | +``` |
| 138 | +Setup.Environment.CONNECT_PRODUCTION |
| 139 | +``` |
| 140 | + |
| 141 | +#### 1.3 Finally |
| 142 | +So, your setup must be something like this: |
| 143 | +```java |
| 144 | +import br.com.moip.models.Setup; |
| 145 | + |
| 146 | +Setup setup = new Setup().setAuthentication(auth).setEnvironment(Setup.Environment.SANDBOX); |
| 147 | +``` |
| 148 | + |
| 149 | +### 2. Create customer |
| 150 | +With the setup created, you can make requests to Moip API. To start the basic e-commerce flow you need to create a customer. After all, it's whom will order your products or services. |
| 151 | + |
| 152 | +```java |
| 153 | +import static br.com.moip.helpers.PayloadFactory.payloadFactory; |
| 154 | +import static br.com.moip.helpers.PayloadFactory.value; |
| 155 | + |
| 156 | +Map<String, Object> taxDocument = payloadFactory( |
| 157 | + value("type", "CPF"), |
| 158 | + value("number", "10013390023") |
| 159 | +); |
| 160 | + |
| 161 | +Map<String, Object> phone = payloadFactory( |
| 162 | + value("countryCode", "55"), |
| 163 | + value("areaCode", "11"), |
| 164 | + value("number", "22226842") |
| 165 | +); |
| 166 | + |
| 167 | +Map<String, Object> shippingAddress = payloadFactory( |
| 168 | + value("city", "Sao Paulo"), |
| 169 | + value("district", "Itaim BiBi"), |
| 170 | + value("street", "Av. Brigadeiro Faria Lima"), |
| 171 | + value("streetNumber", "3064"), |
| 172 | + value("state", "SP"), |
| 173 | + value("country", "BRA"), |
| 174 | + value("zipCode", "01451001") |
| 175 | +); |
| 176 | + |
| 177 | +Map<String, Object> customerRequestBody = payloadFactory( |
| 178 | + value("ownId", "customer_own_id"), |
| 179 | + value("fullname", "Test Moip da Silva"), |
| 180 | + value("email", "test.moip@mail.com"), |
| 181 | + value("birthDate", "1980-5-10"), |
| 182 | + value("taxDocument", taxDocument), |
| 183 | + value("phone", phone), |
| 184 | + value("shippingAddress", shippingAddress) |
| 185 | +); |
| 186 | + |
| 187 | +Map<String, Object> responseCreation = Moip.API.customers().create(customerRequestBody, setup); |
| 188 | +``` |
| 189 | + |
| 190 | +> Read more about customer on [API reference](https://dev.moip.com.br/v2.0/reference#clientes-ec). |
| 191 | +
|
| 192 | +### 3. Create order |
| 193 | +Customer created! It's buy time! :tada: |
| 194 | + |
| 195 | +```java |
| 196 | +import static br.com.moip.helpers.PayloadFactory.payloadFactory; |
| 197 | +import static br.com.moip.helpers.PayloadFactory.value; |
| 198 | + |
| 199 | +Map<String, Object> subtotals = payloadFactory( |
| 200 | + value("shipping", 15000) |
| 201 | +); |
| 202 | + |
| 203 | +Map<String, Object> amount = payloadFactory( |
| 204 | + value("currency", "BRL"), |
| 205 | + value("subtotals", subtotals) |
| 206 | +); |
| 207 | + |
| 208 | +Map<String, Object> product1 = payloadFactory( |
| 209 | + value("product", "Product 1 Description"), |
| 210 | + value("category", "TOYS_AND_GAMES"), |
| 211 | + value("quantity", 2), |
| 212 | + value("detail", "Anakin's Light Saber"), |
| 213 | + value("price", 100000000) |
| 214 | +); |
| 215 | + |
| 216 | +Map<String, Object> product2 = payloadFactory( |
| 217 | + value("product", "Product 2 Description"), |
| 218 | + value("category", "SCIENCE_AND_LABORATORY"), |
| 219 | + value("quantity", 5), |
| 220 | + value("detail", "Pym particles"), |
| 221 | + value("price", 2450000000) |
| 222 | +); |
| 223 | + |
| 224 | +List items = new ArrayList(); |
| 225 | +items.add(product1); |
| 226 | +items.add(product2); |
| 227 | + |
| 228 | +Map<String, Object> customer = payloadFactory( |
| 229 | + value("id", "CUS-XXOBPZ80QLYP") |
| 230 | +); |
| 231 | + |
| 232 | +Map<String, Object> order = payloadFactory( |
| 233 | + value("ownId", "order_own_id"), |
| 234 | + value("amount", amount), |
| 235 | + value("items", items), |
| 236 | + value("customer", customer) |
| 237 | +); |
| 238 | + |
| 239 | +Map<String, Object> responseCreation = Moip.API.orders().create(order, setup); |
| 240 | +``` |
| 241 | + |
| 242 | +> Read more about order on [API reference](https://dev.moip.com.br/v2.0/reference#pedidos-ec). |
| 243 | +
|
| 244 | +### 4. Create Payment |
| 245 | +Alright! Do you have all you need? So, lets pay this order. :moneybag: |
| 246 | + |
| 247 | +```java |
| 248 | +import static br.com.moip.helpers.PayloadFactory.payloadFactory; |
| 249 | +import static br.com.moip.helpers.PayloadFactory.value; |
| 250 | + |
| 251 | +Map<String, Object> taxDocument = payloadFactory( |
| 252 | + value("type", "CPF"), |
| 253 | + value("number", "33333333333") |
| 254 | +); |
| 255 | + |
| 256 | +Map<String, Object> phone = payloadFactory( |
| 257 | + value("countryCode", "55"), |
| 258 | + value("areaCode", "11"), |
| 259 | + value("number", "66778899") |
| 260 | +); |
| 261 | + |
| 262 | +Map<String, Object> holder = payloadFactory( |
| 263 | + value("fullname", "Portador Teste Moip"), |
| 264 | + value("birthdate", "1988-12-30"), |
| 265 | + value("taxDocument", taxDocument), |
| 266 | + value("phone", phone) |
| 267 | +); |
| 268 | + |
| 269 | +Map<String, Object> creditCard = payloadFactory( |
| 270 | + value("hash", "CREDIT_CARD_HASH"), |
| 271 | + value("store", false), |
| 272 | + value("holder", holder) |
| 273 | +); |
| 274 | + |
| 275 | +Map<String, Object> fundingInstrument = payloadFactory( |
| 276 | + value("method", "CREDIT_CARD"), |
| 277 | + value("creditCard", creditCard) |
| 278 | +); |
| 279 | + |
| 280 | +Map<String, Object> payment = payloadFactory( |
| 281 | + value("installmentCount", 1), |
| 282 | + value("statementDescriptor", "minhaLoja.com"), |
| 283 | + value("fundingInstrument", fundingInstrument) |
| 284 | +); |
| 285 | + |
| 286 | +Map<String, Object> newPay = Moip.API.payments().pay(payment, "order_id", setup); |
| 287 | +``` |
| 288 | + |
| 289 | +> Read more about payment on [API reference](https://dev.moip.com.br/v2.0/reference#pagamentos-ec). |
| 290 | +
|
| 291 | +### Other examples |
| 292 | +If you want to see other functional examples, check the [Wiki](https://github.com/moip/moip-sdk-java/wiki). |
| 293 | + |
| 294 | +## Exceptions treatment |
| 295 | +| errors | cause | status | |
| 296 | +| :---: | :---: | :---: | |
| 297 | +| UnautorizedException | to authentication errors | == 401 | |
| 298 | +| ValidationException | to validation errors | >= 400 && <= 499 (except 401) | |
| 299 | +| UnexpectedException | to unexpected errors | >= 500 | |
| 300 | + |
| 301 | +> :warning: To catch these errors, use the bellow treatment: |
| 302 | +
|
| 303 | +```java |
| 304 | +import br.com.moip.exception.UnauthorizedException; |
| 305 | +import br.com.moip.exception.UnexpectedException; |
| 306 | +import br.com.moip.exception.ValidationException; |
| 307 | + |
| 308 | +try { |
| 309 | + |
| 310 | + Map<String, Object> newPay = Moip.API.payments().pay(payment, "order_id", setup); |
| 311 | + |
| 312 | +} catch(UnauthorizedException e) { |
| 313 | + // StatusCode == 401 |
| 314 | +} catch(UnexpectedException e) { |
| 315 | + // StatusCode >= 500 |
| 316 | +} catch(ValidationException e) { |
| 317 | + // StatusCode entre 400 e 499 (exceto 401) |
| 318 | +} |
| 319 | +``` |
| 320 | + |
| 321 | +## Moip documentation |
| 322 | + |
| 323 | +### Docs |
| 324 | +To stay up to date about the **Moip Products**, check the [documentation](https://dev.moip.com.br/v2.0/docs). |
| 325 | + |
| 326 | +### References |
| 327 | +Read more about the **Moip APIs** in [API reference](https://dev.moip.com.br/v2.0/reference). |
| 328 | + |
| 329 | +## Getting help |
| 330 | +We offer many ways to contact us, so if you have a question, do not hesitate, talk to us whatever you need. For questions about API or business rules, contact us by [support](https://dev.moip.com.br/v2.0/) or [slack](https://slackin-cqtchmfquq.now.sh/):slack:. But, if you have a question or suggestion about the SDK, feel free to open an **issue** or **pull request**. |
| 331 | + |
| 332 | +## Contributing |
| 333 | +Do you have an enhancement suggest or found something to fix? Go ahead, help us and let your mark on Moip, open **pull requests** and **issues** against this project. If you want to do it, please read the `CONTRIBUTING.md` to be sure everyone follows the same structure and planning of the project. Remember, we :heart: contributions. :rocket: |
0 commit comments