Index
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'
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>
https://mvnrepository.com/artifact/br.com.moip/sdk-java
This step by step will exemplify the integration flow with simple usage examples.
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.
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);
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).
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);
We have some environments that you can send your requests.
The test environment. You can use this to simulate all of your business scenarios.
Setup.Environment.SANDBOX
"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.
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
So, your setup must be something like this:
import br.com.moip.models.Setup;
Setup setup = new Setup().setAuthentication(auth).setEnvironment(Setup.Environment.SANDBOX);
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.
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.
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.
If you want to see other functional examples, check the Wiki.
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)
}
To stay up to date about the Moip Products, check the documentation.
Read more about the Moip APIs in API reference.
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.
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. 🚀