paymill-java
Java wrapper for PAYMILL API
Getting started
- If you are not familiar with PAYMILL, start with the documentation.
- Install the latest release.
- Check the API reference.
- Check the full JavaDoc documentation.
- Check the tests.
Installation
- Releases are available in maven central and in this repository.
<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:
- ChecksumService
- ClientService
- OfferService
- PaymentService
- PreauthorizationService
- RefundService
- SubscriptionService
- TransactionService
- WebhookService
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:
- clientService.create() - creates a client without email and description
- clientService.createWithEmail( "[email protected]" ) - creates a client with email
- clientService.createWithDescription( "CRM Id: fake_34212" ) - creates a client with description
- clientService.createWithEmailAndDescription( "[email protected]", "CRM Id: fake_34212" ) - creates a client with email and description
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( "[email protected]" ),
Client.createOrder().byCreatedAt().desc()
);
This will load only clients with email [email protected], 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:
- 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>
- 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("[email protected]")
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("[email protected]")
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:
- API v2.0 : 3.2.0 in maven central and in this repository.
Changelog
5.1.6
- fix: Smaller issues with Javadoc Comments
5.1.3
- fix: #65 pass on parameter 'description' in TransactionService.createWithPaymentAndClient, thanks to @rethab
5.1.2
- fix: #64 Unboxing null always throws NullPointerException, thanks to @vladaspasic
5.1.1
- fix: #64 Unboxing null always throws NullPointerException, thanks to @vladaspasic
5.1.0
- fix tests: Token is now generated for each request
- update: projcet dependencies
- add SEPA mandate_reference for direct debit transaction and subscription
- include internal objects ShoppingCartItem and Address
- add ChecksumService to create checksums for transactions that are started client-side, e.g. PayPal checkout.
5.0.0
- Minor, but incompatible changes in the interface
- fix: #57 removed final keywords from some classes to allow proper mocking, thanks to @dobermai
- fix: #59 added missing subscription status, thanks to @schaebo
- improved deserialization and fixed test suite to work with arbitary accounts
- improvement: #51 isolated jersey dependecy, alternative frameworks can now be used for http, thanks to @basoko
- fix: #50 fixed interval deserialization, thanks to @basoko
- improvement: #53 added missing payment object fields
- switched to jersey 2, thanks to Dmitry.
- updated webhook event types
- included internal objects
- update project dependencies
4.0.1
- improvement: #54 now is possible to end the trial
4.0.0
- Works with version 2.1 of PAYMILL's REST API.
- update project dependencies
3.2.0
- improvement: remove workaround for subscriptions without offer.
- improvement: #23 now preauthorizations can be created with description.
- fix: after update of the offer the PAYMILL API does not returns 0 days trial period any more.
- update project dependencies
3.1.2
- fix: #47 TransacionService list with filter for createdAt doesn't work.
- fix: typo in Webhook.EventType.TRANSACTION_FAILED
- improvement: missing enumeration value will not cause parsing error, but will be mapped to UNDEFINED
- update project dependencies
3.1.1
- fix in createWithOfferPaymentAndClient: now trialStart represents the timestamp in correct format.
3.1.0
- Allow update of an offer for a subscription
- update project dependencies
3.0.5
- internal improvements
- #42 add currency to fee
- update project dependencies
3.0.4
- #38 explicit dependency to jersey-core
3.0.3
- update project dependencies
- Ability to set HTTP connection timeout in milliseconds to PaymillContext constructor (infinity by default)
- #39 fix deserialization of Subscription nextCaptureAt
3.0.2
- fix: remove _id in names for reference types in filter parameters for list methods( eg. client_id to client )
3.0.1
- Add "chargeback" value to Transaction.Status enum
- Add workaround for subscription without offer. Now the lib will not throw parsing error.
3.0.0
- Improved implementation internally, now most of the configuration uses annotations and reflection.
- Package name changed from de.paymill to com.paymill.
- Removed singleton Paymill object and replaced with a PaymillContext object.
- All services are now directly accessible from PaymillContext.
- Improved list handling. Now the list method returns a PaymillList, which also contains the dataCount. All models now contain methods to create filter and sort criteria.
- Improved create methods. All create methods now work with arguments. Removed unnecessary fields in objects (e.g. token in Transaction).
- Improved get, update and remove methods. Get and remove now work with both instances and IDs. Get and Update methods now work on the same instance.
- Offer is no longer updateable for a subscription.
2.6
First maven central
License
Copyright 2013 PAYMILL GmbH.
MIT License (enclosed)