🆕 Java SDK for Moip API v2 server-side integration.
Clone or download
somentelucas [RELEASE] v1.1.0 (#18)
* adds basic settings and basic auth

* adds OAuth authentication

* adds Moip API error models

* adds Moip API exceptions

* adds request properties

* adds Setup class

* adds GsonFactory

* adds missing request properties

* doc

* preparing methods to receive responses

* feat(customer): adds customer endpoint

* fix(customer): apply fixes to customer creation

* feat(customer): adds get customer

* feat(order): adds create order endpoint

* feat(order): adds get order

* feat(payment): adds payment endpoint

* feat(customer): adds funding instruments endpoint and list customers

* adds resource to cast objects to map and adds validation to Response method

* feat(order): adds list orders

* feat(order): adds list order payments

* feat(payment): adds capture and cancel pre-authorized

* feat(refund): adds refund endpoints

* test: add missing tests

* feat(notification): adds notification preference endpoint

* test(notification): adds missing tests

* adds resource to convert the JSON to List

* feat(webhook): adds webhook resources

* refactor: organize instances

* fix method access level

* fixed untracked files

* remove some @test annotations

* test(customer): add missing unit tests to customer

* completes customer unit tests

* test(order): adds order unit tests

* test(payment): adds payment unit tests

* test(refund): adds refund unit tests

* test(notification): adds notification unit tests

* .gitignore

* circleCI integration

* circleCI

* update circleCI test

* update gradle

* update circleci

* test circleci

* test circleci

* test circleci

* test circleci

* test circleci

* test circleci

* update circleci

* test circleci

* test circleci

* test circleci

* test circleci

* test circleci

* update circleci

* remove comment

* account

* feat(account): adds moip account endpoint

* test(account): adds tests to get account

* APIResources: fix imports

* fix typo

* Account: fix method isTaxDocument

* Account: refactor method checkExistence

* resolves codacy issue

* feat(connect): adds Moip Connect features

* feat(account): get keys

* test(connect): connect unit tests

* feat(multiorders): create, get

* test(multiorder): get tests

* fix class imports

* refactor: change resources name

* fix class imports

* refactor multiorder tests

* feat(multipayments): create, get, capture and cancel pre-authorized

* test(multipayment): add unit tests

* test(multiorder): pay multiorder

* test(multiorder): pay multiorder

* fix class imports

* fix codacy issue

* feat(bank account): adds create, get, list, delete and update

* test(bank account): add feature tests

* style: fix spacement

* feat(balances): adds get balances

* test: get balances

* feat(entries): adds get and list

* test: entries

* feat(transfers): adds create, revert, get and list

* test: transfers

* fix class imports

* feat(escrow): release

* test: escrow

* chore: bump version to v1.0.0-beta

* remove conflicts

* feat: adds PayloadFactory resources

* refactor: fix connect resources

* docs: adds README.md description

* release v1.0.0

* public class Error

* v1.0.1

* Changing to minor release instead of patch
Latest commit 5bee84f Sep 21, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci [RELEASE] v0.1.0 Jul 30, 2018
gradle/wrapper Starts project May 30, 2018
src [RELEASE] v1.1.0 (#18) Sep 21, 2018
.gitignore [RELEASE] v1.1.0 (#18) Sep 21, 2018
LICENSE
README.md
build.gradle
gradlew Starts project May 30, 2018
gradlew.bat Starts project May 30, 2018
settings.gradle

README.md

Moip Java SDK

CircleCI Codacy Badge Software License Slack

Index

Require

Java v1.8ˆ java-cup

Installing

Gradle

Maven-central

Add the fallowing dependency to build.gradle in the project:

// https://mvnrepository.com/artifact/br.com.moip/sdk-java
compile group: 'br.com.moip', name: 'sdk-java', version: 'x.y.z'

Maven

Maven-central

Add the fallowing dependency to pom.xml in the project:

<!-- https://mvnrepository.com/artifact/br.com.moip/sdk-java -->
<dependency>
    <groupId>br.com.moip</groupId>
    <artifactId>sdk-java</artifactId>
    <version>x.y.z</version>
</dependency>

Another installation methods

https://mvnrepository.com/artifact/br.com.moip/sdk-java

Simple flow

This step by step will exemplify the integration flow with simple usage examples.

1. Setup

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.

1.1 Authentication

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.

import br.com.moip.models.Setup;

Setup setup = new Setup().setAuthentication(auth).setEnvironment(ENVIRONMENT);

By BasicAuth

The following set will generate a hash Base64 with your Moip account token and key to authenticate.

import br.com.moip.auth.Authentication;
import br.com.moip.auth.BasicAuth;

String token = "01010101010101010101010101010101";
String key = "ABABABABABABABABABABABABABABABABABABABAB";

Authentication auth = new BasicAuth(token, key);

💡 If you don't know how to get your token and key, click here (you must be logged in).

By OAuth

The following set will create an OAuth authentication object.

💡 Click here to know how to get your token OAuth.

import br.com.moip.auth.Authentication;
import br.com.moip.auth.OAuth;

String oauth = "8833c9eb036543b6b0acd685a76c9ead_v2";

Authentication auth = new OAuth(oauth);

1.2 Environment

We have some environments that you can send your requests.

Sandbox

The test environment. You can use this to simulate all of your business scenarios.

Setup.Environment.SANDBOX
Production

"The environment of truth" 👀. This is the environment where the real transactions run.

Setup.Environment.PRODUCTION

💡 Before going to production, you need to request homologation of your application here.

Connect

The connect URL must be used only for operations involving another Moip accounts (request connect permission, generate the account accessToken, refresh account accessToken).

💡 If you want to know more about the Moip Connect flow, check here (PT-BR).

Sandbox

Setup.Environment.CONNECT_SANDBOX

Production

Setup.Environment.CONNECT_PRODUCTION

1.3 Finally

So, your setup must be something like this:

import br.com.moip.models.Setup;

Setup setup = new Setup().setAuthentication(auth).setEnvironment(Setup.Environment.SANDBOX);

2. Create customer

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.

import static br.com.moip.helpers.PayloadFactory.payloadFactory;
import static br.com.moip.helpers.PayloadFactory.value;

Map<String, Object> taxDocument = payloadFactory(
        value("type", "CPF"),
        value("number", "10013390023")
);

Map<String, Object> phone = payloadFactory(
        value("countryCode", "55"),
        value("areaCode", "11"),
        value("number", "22226842")
);

Map<String, Object> shippingAddress = payloadFactory(
        value("city", "Sao Paulo"),
        value("district", "Itaim BiBi"),
        value("street", "Av. Brigadeiro Faria Lima"),
        value("streetNumber", "3064"),
        value("state", "SP"),
        value("country", "BRA"),
        value("zipCode", "01451001")
);

Map<String, Object> customerRequestBody = payloadFactory(
        value("ownId", "customer_own_id"),
        value("fullname", "Test Moip da Silva"),
        value("email", "test.moip@mail.com"),
        value("birthDate", "1980-5-10"),
        value("taxDocument", taxDocument),
        value("phone", phone),
        value("shippingAddress", shippingAddress)
);

Map<String, Object> responseCreation = Moip.API.customers().create(customerRequestBody, setup);

Read more about customer on API reference.

3. Create order

Customer created! It's buy time! 🎉

import static br.com.moip.helpers.PayloadFactory.payloadFactory;
import static br.com.moip.helpers.PayloadFactory.value;

Map<String, Object> subtotals = payloadFactory(
        value("shipping", 15000)
);

Map<String, Object> amount = payloadFactory(
        value("currency", "BRL"),
        value("subtotals", subtotals)
);

Map<String, Object> product1 = payloadFactory(
        value("product", "Product 1 Description"),
        value("category", "TOYS_AND_GAMES"),
        value("quantity", 2),
        value("detail", "Anakin's Light Saber"),
        value("price", 100000000)
);

Map<String, Object> product2 = payloadFactory(
        value("product", "Product 2 Description"),
        value("category", "SCIENCE_AND_LABORATORY"),
        value("quantity", 5),
        value("detail", "Pym particles"),
        value("price", 2450000000)
);

List items = new ArrayList();
items.add(product1);
items.add(product2);

Map<String, Object> customer = payloadFactory(
        value("id", "CUS-XXOBPZ80QLYP")
);

Map<String, Object> order = payloadFactory(
        value("ownId", "order_own_id"),
        value("amount", amount),
        value("items", items),
        value("customer", customer)
);

Map<String, Object> responseCreation = Moip.API.orders().create(order, setup);

Read more about order on API reference.

4. Create Payment

Alright! Do you have all you need? So, lets pay this order. 💰

import static br.com.moip.helpers.PayloadFactory.payloadFactory;
import static br.com.moip.helpers.PayloadFactory.value;

Map<String, Object> taxDocument = payloadFactory(
        value("type", "CPF"),
        value("number", "33333333333")
);

Map<String, Object> phone = payloadFactory(
        value("countryCode", "55"),
        value("areaCode", "11"),
        value("number", "66778899")
);

Map<String, Object> holder = payloadFactory(
        value("fullname", "Portador Teste Moip"),
        value("birthdate", "1988-12-30"),
        value("taxDocument", taxDocument),
        value("phone", phone)
);

Map<String, Object> creditCard = payloadFactory(
        value("hash", "CREDIT_CARD_HASH"),
        value("store", false),
        value("holder", holder)
);

Map<String, Object> fundingInstrument = payloadFactory(
        value("method", "CREDIT_CARD"),
        value("creditCard", creditCard)
);

Map<String, Object> payment = payloadFactory(
        value("installmentCount", 1),
        value("statementDescriptor", "minhaLoja.com"),
        value("fundingInstrument", fundingInstrument)
);

Map<String, Object> newPay = Moip.API.payments().pay(payment, "order_id", setup);

Read more about payment on API reference.

Other examples

If you want to see other functional examples, check the Wiki.

Exceptions treatment

errors cause status
UnautorizedException to authentication errors == 401
ValidationException to validation errors >= 400 && <= 499 (except 401)
UnexpectedException to unexpected errors >= 500

⚠️ To catch these errors, use the bellow treatment:

import br.com.moip.exception.UnauthorizedException;
import br.com.moip.exception.UnexpectedException;
import br.com.moip.exception.ValidationException;

try {
    
    Map<String, Object> newPay = Moip.API.payments().pay(payment, "order_id", setup);
    
} catch(UnauthorizedException e) {
  // StatusCode == 401
} catch(UnexpectedException e) {
  // StatusCode >= 500
} catch(ValidationException e) {
  // StatusCode entre 400 e 499 (exceto 401)
}

Moip documentation

Docs

To stay up to date about the Moip Products, check the documentation.

References

Read more about the Moip APIs in API reference.

Getting help

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 or slack:slack:. But, if you have a question or suggestion about the SDK, feel free to open an issue or pull request.

Contributing

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 ❤️ contributions. 🚀