# Java SDK
## Introduction
The Deposits Java SDK (Software Development Kit) is a software package you can download and add to your existing code facilitating the integration by having pre-defined classes and functions you can call to integrate the [Deposits Endpoints](https://docs.pandablue.com/api-documentation/deposits-api/endpoints).
Review and download the source code from GitHub by clicking on the button below[](https://github.com/directa24/cashin-java-sdk/)
## Installation
### Requirements
* Java 1.8 or later
### Gradle Users
Add this dependency to your project's build file:
{% code title="Java Gradle Dependency" %}
```java
implementation "com.directa24:cashin-java-sdk:1.0.13"
```
{% endcode %}
### Maven Users
Add this dependency to your project's POM:
{% code title="Java Maven dependency" %}
```markup
com.directa24
cashin-java-sdk
1.0.13
```
{% endcode %}
####
### Dependencies
The library uses [Project Lombok](https://projectlombok.org/). While it is not a requirement, you might want to install a [plugin](https://projectlombok.org/setup/overview) for your favorite IDE to facilitate development.
[JUnit 4](https://junit.org/junit4/) and [Wiremock](http://wiremock.org/) library are needed to run the bundled tests.
## Usage
Begin by initializing your credentials
### **Deposit Credentials**
```java
String depositKeySbx = "fUEhPEKrUt";
String secretKeySbx = "wSHTfsMMdNskTppilncuZPEklgLmdUAOg";
Directa24 directa24Sandbox = new Directa24.Sandbox(depositKeySbx, secretKeySbx);
```
### **Read-Only Credentials**
```java
String readOnlyKeySbx = "EKiFOWiHnI";
Directa24 directa24Sandbox = new Directa24.Sandbox(readOnlyKeySbx);
```
{% hint style="success" %}
Make sure you have whitelisted your servers IPs on our Merchant Panel by going to Settings -> API Access.
{% endhint %}
[Click here](https://docs.pandablue.com/api-documentation/deposits-api/technical-and-security-aspects#api-keys) for more information about the API Keys.
Once the credentials and the IPs have been properly set-up, you are ready to start using the classes the SDK provides. Each Class can be used to execute the functionalities of its respective [Deposit Endpoint.](https://docs.pandablue.com/api-documentation/deposits-api/endpoints)
Make sure you take a look at the [Deposit Endpoints here](https://docs.pandablue.com/api-documentation/deposits-api/endpoints) to review how the integration of each of them works, the validations and the responses formats.
{% hint style="success" %}
As soon as you are ready with the integration and you have the production credentials, replace the credentials for the production ones.
{% endhint %}
## Classes
{% hint style="success" %}
heck the respective [Endpoint Page ](https://docs.pandablue.com/api-documentation/deposits-api/endpoints)to see the format of the responses, fields requirements and validations.
{% endhint %}
### Create Deposit
Every time you need to create a deposit, you will need to invoke the `CreateDepositRequest` Class with all the objects containing the information required to be sent. The amount of information required depends on the flow you have chosen, either the [Hosted Checkout Experience](https://docs.pandablue.com/api-documentation/deposits-api#hosted-checkout-experience) or the [ONE SHOT Experience.](https://docs.pandablue.com/api-documentation/deposits-api#oneshot-experience)
```java
public class CreateDepositExample {
public static void main(String[] args) {
Address address = Address.builder()
.street("Rua Dr. Franco Ribeiro, 52")
.city("Rio Branco")
.state("AC")
.zipCode("11600-234")
.build();
Payer payer = Payer
.builder()
.id("4-9934519")
.address(address)
.document("21329039050")
.documentType("CPF")
.email("juanCarlos@hotmail.com")
.firstName("Ricardo")
.lastName("Carlos")
.phone("+59899000878")
.build();
BankAccount bankAccount = BankAccount
.builder()
.bankCode("01")
.accountNumber("3242342")
.accountType("SAVING")
.beneficiary("Ricardo Carlos")
.branch("12")
.build();
CreateDepositRequest createDepositRequest = CreateDepositRequest
.builder()
.invoiceId("108")
.amount(new BigDecimal(100))
.country("BR")
.currency("BRL")
.payer(payer)
.paymentMethod("BB")
.paymentType("BANK_TRANSFER")
.bankAccount(bankAccount)
.earlyRelease(false)
.feeOnPayer(false)
.surchargeOnPayer(false)
.bonusAmount(BigDecimal.ONE)
.bonusRelative(false)
.strikethroughPrice(BigDecimal.ONE)
.description("Test")
.clientIp("186.51.171.84")
.language("es")
.deviceId("00000000-00000000-01234567-89ABCDEF")
.backUrl("https://yoursite.com/deposit/108/cancel")
.successUrl("https://yoursite.com/deposit/108/confirm")
.errorUrl("https://yoursite.com/deposit/108/error")
.notificationUrl("https://yoursite.com/ipn")
.logo("https://yoursite.com/logo.png")
.test(true)
.mobile(false)
.idempotency("")
.build();
try {
CreateDepositResponse createDepositResponse = directa24Sandbox.client.createDeposit(createDepositRequest);
// Handle response
} catch (Directa24Exception e) {
// Handle errors
}
}
}
```
{% hint style="info" %}
CreateDepositRequest.amount and CreateDepositRequest.country are the only mandatory fields for a successful request. The rest of the fields needs to be sent depending on the flow you have chosen as those will be collected by us if not sent.
{% endhint %}
###
### Deposit Status
As soon as the deposit is created and you have received the notification in your `notification_url`, you will want to invoke the `DepositStatusRequest` Class to retrieve the [status](https://docs.pandablue.com/api-documentation/deposits-api/api-codes#deposits-status-codes) of the deposit.
Click here to see the [deposits status flow.](https://docs.pandablue.com/api-documentation/deposits-api/endpoints/refund-status-endpoint#status-flow)
```java
public class DepositStatusExample {
public static void main(String[] args) {
DepositStatusRequest depositStatusRequest = DepositStatusRequest
.builder()
.id(300000001)
.build();
try {
DepositStatusResponse depositStatusResponse = directa24Sandbox.client.depositStatus(depositStatusRequest);
// Handle response
} catch (Directa24Exception e) {
// Handle errors
}
}
}
```
{% hint style="success" %}
Make sure you are adding the deposit\_id received on your notification\_url in the field DepositStatusRequest.id.
{% endhint %}
### Payment Methods
For the best user experience, we recommend integrating our [Payment Methods Endpoint](https://docs.pandablue.com/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to automatically retrieve the [list](https://docs.pandablue.com/api-documentation/deposits-api/payment-methods) of payment methods name, logos, types and more that your account has available.
In order to do that, invoke the `PaymentMethodRequest` Class containing the [Country's ISO code](https://docs.pandablue.com/specifications/countries-specifications#countries-and-currencies) of the country you need the payment methods from in the field `PaymentMethodRequest.country`
```java
public class PaymentMethodsExample {
public static void main(String[] args) {
PaymentMethodRequest paymentMethodRequest = PaymentMethodRequest
.builder()
.country("BR")
.build();
try {
List paymentMethodResponse = directa24Sandbox.client.paymentMethods(paymentMethodRequest);
// Handle response
} catch (Directa24Exception e) {
// Handle errors
}
}
}
```
### Exchange Rates
If you need to know the Exchange Rate of a given currency, you can do so by invoking `ExchangeRateRequest` with the [Country's ISO code](https://docs.pandablue.com/specifications/countries-specifications#countries-and-currencies) of the origin and the amount you want to convert to USD.
```java
public class ExchangeRateExample {
public static void main(String[] args) {
ExchangeRateRequest exchangeRatesRequest = ExchangeRateRequest
.builder()
.country("BR")
.amount(BigDecimal.TEN)
.build();
try {
ExchangeRateResponse exchangeRateResponse = directa24Test.client.exchangeRates(exchangeRateRequest);
// Handle response
} catch (Directa24Exception e) {
// Handle errors
}
}
}
```
### Create Refund
In order to create a refund, you need to send the deposit\_id, merchant\_invoice\_id, and the bank\_account object (only for non-cc payments, otherwise, it is optional).
```java
public class CreateRefundTest extends AbstractDirecta24Test {
@Before
public void createMocks() {
stubFor(post(urlMatching("/v3/refunds"))
.withHeader("X-Login", equalTo(DEPOSIT_KEY))
.withHeader("Content-Type", equalTo("application/json"))
.willReturn(aResponse().withStatus(200).withHeader("Content-Type", "application/json").withBody("{\"refund_id\": 1000043\n}")));
}
@Test
public void createRefundTest() throws Directa24Exception {
Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY);
BankAccount bankAccount = BankAccount
.builder()
.bankCode("01")
.accountNumber("3242342")
.accountType("SAVING")
.beneficiary("Ricardo Carlos")
.branch("12")
.build();
CreateRefundRequest createRefundRequest = CreateRefundRequest
.builder()
.depositId(9999)
.invoiceId("1234")
.amount(new BigDecimal(100))
.bankAccount(bankAccount)
.comments("Test")
.notificationUrl("https://yoursite.com/ipn")
.idempotency("")
.build();
CreateRefundResponse createRefundResponse = directa24Test.client.createRefund(createRefundRequest);
assertTrue(createRefundResponse != null && createRefundResponse.getRefundId() != null);
verify(postRequestedFor(urlEqualTo("/v3/refunds")).withHeader("Content-Type", equalTo("application/json")));
}
}
```
### Refund Status
```java
public class RefundStatusTest extends AbstractDirecta24Test {
@Before
public void createMocks() {
stubFor(get(urlMatching("/v3/refunds/123456"))
.withHeader("X-Login", equalTo(DEPOSIT_KEY))
.withHeader("Content-Type", equalTo("application/json"))
.willReturn(aResponse()
.withStatus(200)
.withHeader("Content-Type", "application/json")
.withBody(
"{\"deposit_id\": 300537729,\"merchant_invoice_id\": \"postmanTest971574817\",\"status\": \"PENDING\",\"amount\": 1000.00}")));
stubFor(get(urlMatching("/v3/refunds/999999"))
.withHeader("X-Login", equalTo(DEPOSIT_KEY))
.withHeader("Content-Type", equalTo("application/json"))
.willReturn(aResponse().withStatus(404).withHeader("Content-Type", "application/json")));
}
@Test
public void refundStatusTest() throws Directa24Exception {
Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY);
RefundStatusRequest refundStatusRequest = RefundStatusRequest.builder() //
.id(123456) //
.build();
RefundStatusResponse refundStatusResponse = directa24Test.client.refundStatus(refundStatusRequest);
assertTrue(refundStatusResponse != null);
assertEquals(refundStatusResponse.getStatus(), "PENDING");
verify(getRequestedFor(urlEqualTo("/v3/refunds/" + 123456)).withHeader("Content-Type", equalTo("application/json")));
}
@Test
public void refundNotFoundTest() {
Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY);
RefundStatusRequest refundStatusRequest = RefundStatusRequest.builder() //
.id(999999) //
.build();
RefundStatusResponse refundStatusResponse = null;
try {
refundStatusResponse = directa24Test.client.refundStatus(refundStatusRequest);
fail("Refund doesn't exists");
} catch (Directa24Exception e) {
}
assertTrue(refundStatusResponse == null);
}
```