search

paymill / paymill-java

Java wrapper for Paymill API
http://paymill.github.io
MIT License
26 stars 22 forks source link

readme

PAYMILL icon

paymill-java

Java wrapper for PAYMILL API

Build Status

Getting started

Installation

<dependency>
  <groupId>com.paymill</groupId>
  <artifactId>paymill-java</artifactId>
  <version>5.1.6</version>
</dependency>

What's new

We have released version 5, which follows version 2.1 of the PAYMILL's REST API. This version is not backwards compatible with version 4, altough changes are minor. We also added some examples , how to use an alternative http client and how to deal with incoming webhooks.

Usage

Initialize the library by providing your api key:

  PaymillContext paymillContext = new PaymillContext( "<YOUR PRIVATE API KEY>" );

PaymillContecxt loads the context of PAYMILL for a single account, by providing a merchants private key. It creates 8 services, which represents the PAYMILL API:

These services should not be created directly. They have to be obtained by the context's accessors.

To run the tests:

  mvn -DapiKey=<YOUR_PRIVATE_API_KEY> test

Using services

In all cases, you'll use the predefined service classes to access the PAYMILL API.

To fetch a service instance, call service name accessor from paymillContext, like

  ClientService clientService = paymillContext.getClientService();

Every service instance provides basic methods for CRUD functionality.

Creating objects

Every service provides instance factory methods for creation. They are very different for every service, because every object can be created in a different way. The common pattern is

  xxxService.createXXX( params... );

For example: client can be created with two optional parameters: email and description. So we have four possible methods to create the client:

Retrieving objects

You can retrieve an object by using the get() method with an object id:

  Client client = clientService.get( "client_12345" );

or with the instance itself, which also refreshes it:

  clientService.get( client );

This method throws an ApiException if there is no client under the given id.

Important: If you use a nested object (e.g. paymet = transaction.getClient().getPayments().get(0) ) you should always "refresh", as the nested object will contain only the id, and all other properties will be null.

Retrieving lists

To retrieve a list you may simply use the list() method:

  PaymillList<Client> clients = clientService.list();

You may provide a filter and order to list method:

  PaymillList<Client> clients =
    clientService.list(
      Client.createFilter().byEmail( "john.rambo@paymill.com" ),
      Client.createOrder().byCreatedAt().desc()
    );

This will load only clients with email john.rambo@paymill.com, order descending by creation date.

Updating objects

In order to update an object simply call a service's update() method:

  clientServive.update( client );

The update method also refreshes the the given instance. For example: If you changed the value of 'createdAt' locally and pass the instance to the update() method, it will be refreshed with the data from PAYMILL. Because 'createdAt' is not updateable field your change will be lost.

Deleting objects

You may delete objects by calling the service's delete() method with an object instance or object id.

  clientService.delete( "client_12345" );

or

  clientService.delete( client );

Using an alternative http client

Since version 5.0.0 the wrapper supports alternative http clients. To use one, you need to take these two steps:

  1. Exclude the jersey dependecy from your pom like this: 
        <dependency>
        <groupId>com.paymill</groupId>
        <artifactId>paymill-java</artifactId>
        <version>latestversion</version>
        <exclusions>
            <exclusion>
                <groupId>org.glassfish.jersey.core</groupId>
                <artifactId>jersey-client</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
  2. Implement the HttpClient interface and create a PaymillContext with it.

We have an example with Jersey 1.X, the client used prior the 5.X release of the wrapper.

Spring integration

This example is suitable if you use this wrapper for a single account.

Defines the PAYMILL context in Spring context.

<bean id="paymillContext" class="com.paymill.context.PaymillContext">
  <constructor-arg value="<YOUR PRIVATE API KEY>" />
</bean>

Defines custom Controller, which uses PAYMILL ClientService internaly. Note that the setter receives paymillContext.

<bean id="clientController" class="com.yourpackage.ClientController">
  <property name="clientService" ref="paymillContext" />
</bean>

The ClientController class itself. Note that the clientService property is set by getting the ClientService form the paymillContext.

public class ClientController {
  private ClientService clientService;

  public void setClientService( PaymillContext paymillContext ) {
    this.clientService = paymillContext.getClientService();
  }
}

Scala and Groovy integration

The wrapper can be used easily in Scala and Groovy projects. Note, that it depends on 3rd party libraries, thus usage with a dependecy managment tool like maven is recommended.

Scala example:

import com.paymill.context.PaymillContext

object HelloPaymill {
  def main(args: Array[String]) {
    val context = new PaymillContext("<YOUR PRIVATE API KEY>")
    val client = context.getClientService().createWithEmail("lovely-client@example.com")
    println(client.getId())
  }
}

Groovy example:

import com.paymill.context.PaymillContext

class HelloPaymill {

    public static void main(String[] args) {
        def context = new PaymillContext("<YOUR PRIVATE API KEY>")
        def client = context.getClientService().createWithEmail("lovely-client@example.com")
        println(client.getId())
    }
}

Dealing with webhooks

Take a look at the Webhook sample. It contains an example json deserializer, as well as hints, how to receive webhooks in your app.

Older API versions

The wrapper supports only the latest version of the PAYMILL Rest API (v2.1). Latest stable releases for older API versions:

Changelog

5.1.6

5.1.3

5.1.2

5.1.1

5.1.0

5.0.0

4.0.1

4.0.0

3.2.0

3.1.2

3.1.1

3.1.0

3.0.5

3.0.4

3.0.3

3.0.2

3.0.1

3.0.0

2.6

First maven central

License

Copyright 2013 PAYMILL GmbH.

MIT License (enclosed)