The cl-paymill Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-paymill Reference Manual

This is the cl-paymill Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:55:01 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

PLEASE NOTE THE FOLLOWING IN ADDITION TO THE USUAL DISCLAIMERS THAT
ACCOMPANY FREE SOFTWARE: THE RELEASE OF THIS LIBRARY IN NO WAY IMPLIES
AN ENDORSMENT OF THE PAYMILL PAYMENT SERVICE. BE CAREFUL OUT THERE.

CL-PAYMILL provides an interface to the Paymill payment service API.
You should definitely read their documentation in order to use their
service.  Ie, do NOT just rely on what is written here.  You use this
interface entirely at your own risk, as stated in the licence.  Not
everything in here is robustly tested.

INSTALLING:

cl-paymill requires drakma, st-json and cl+ssl (required for paymill
access).  However, if you use quicklisp, these are automatically
installed for you.

Put cl-paymill in a place where quicklisp
(http://www.quicklisp.org/beta/) can find it, by default
~/quicklisp/local-projects/ Then do:

(ql:quickload :cl-paymill)
(pml:initialize-paymill "your private test key from paymill")

And the package "PAYMILL" (nickname PML) is installed and ready to use.  

USAGE:

PML:INITIALIZE-PAYMILL (KEY)

KEY is a string which is your paymill key, or a symbol with its
symbol-value setf to your key string. This macro defines the access
functions using the provided key. If you called it with a
symbol, you can unbind the symbol afterwards, if you want.  Until you
call this macro with a key, the access functions will not be defined.
If you give it an invalid key all usage will result in access
unathorized errors. Use your test-key, unless you want to get billed
by Paymill.

First some examples, then an explanation: 

To create a new client, without an email or description:
(pml:clients :new)

To create a new client, with an email:
(pml:clients :new :data '(:email "joey@fubar.org"))

To update an existing client's email and description:
(pml:clients :update 
         :id "client_xyz12345" 
         :data '(:email "joe@foo.org" :description "a lousy client"))

You get the client ID as a return value from (pml:clients :new).  See below.


All access has this general form:

PML:RESOURCE (ACCESS-TYPE &KEY [ID] [DATA])

Where RESOURCE is a generic function, ACCESS-TYPE is a keyword,
optional ID is a string, and optional DATA is for all resources
*except WEBHOOKS* (see below), a list (SLOT1 VALUE1 SLOT2 VALUE2 ...)
where SLOTN can be a string or a keyword and VALUEN is a string.  If
SLOTN is a keyword, it is converted to a lowercase string before
sending the request to paymill.  ACCESS-TYPE determines how the
resource should be accessed.  Most resources have ACCESS-TYPES :new,
:retrieve, :list, and :delete.

The possible values for SLOTN depend on the resource which is being
accessed. As you have seen in the examples, CLIENTS have settable
slots "email" and "description". See the Paymill API docs for other
possible values of SLOTN.

For WEBHOOKS, DATA is a list which looks like '(:EMAIL 
((:EVENT1 :STATUS1) (:EVENT2 :STATUS) ...)) OR '(:URL 
((:EVENT1 :STATUS1) (:EVENT2 :STATUS) ...)). All keywords are
converted to downcased strings, and can be replaced by strings in
calls to the resource. See the Paymill API docs for WEBHOOKS for
possible events and statuses.

The return value(s) also depend on ACCESS-TYPE. Accessing a resource
with 

:NEW returns the id of the created object as a first value, and
the actual object (well, actually an st-json representation of it) as
the second value.

:LIST returns a (gasp) list of st-json representations of
the objects of that type.  

:DELETE returns the object (an st-json rep ...) in the "data" slot
which Paymill returns from the request.  In most cases this is :NULL.
Deleting a CLIENT or a SUBSCRIPTION returns the deleted object.

:RETRIEVE returns the object

:REFUND takes a transaction id and refunds the client the given
amount. It should return the transaction but I can't remember if it
does so - read the Paymill API.  I am not using refunds, so ...

Errors:

If any call to paymill fails to result in a reply with status code
200, an error is signalled. Here are the conditions, exported from
PAYMILL package, together with their status code:

 PAYMILL-BAD-REQUEST 400
 PAYMILL-UNAUTHORIZED 401
 PAYMILL-TRANSACTION-ERROR 403
 PAYMILL-NOT-FOUND 404
 PAYMILL-PRECONDITION-FAILED 412
 PAYMILL-SERVER-ERROR 500 <= status-code <= 505
 PAYMILL-GENERAL-ERROR  other-status-code ~= 200

The error will be signalled from the macro which wraps the actual
request, so don't think you can install an error handler by a :before
method.  Sorry.

The following resources are currently accessible, all exported from
the PAYMILL package:

CLIENTS, TRANSACTIONS, REFUNDS, PAYMENTS, SUBSCRIPTIONS, OFFERS,
WEBHOOKS

Note:

You need to look at st-json as well, but it's nice and simple, and
easy to use.  You might want to build the interface up towards your
app.  For example: define (new-client &optional ...), (new-payment
...) etc.  Thats what I do.  The webhooks interface is new, but tests
suggest it is working.



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-paymill

Author

Peter Wood, email: pete_wood at runbox.com

License

BSD, 2 clause.

Description

CL-PAYMILL is a common lisp interface to the Paymill payment service API. See https://www.paymill.com/

Version

0.0.1

Dependencies
Source

cl-paymill.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-paymill.asd

Location

cl-paymill.asd

Systems

cl-paymill (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-paymill/package.lisp

Parent

cl-paymill (system)

Location

package.lisp

Packages

paymill


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-paymill/build.lisp

Dependency

package.lisp (file)

Parent

cl-paymill (system)

Location

build.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-paymill/paymill.lisp

Dependency

build.lisp (file)

Parent

cl-paymill (system)

Location

paymill.lisp

Exported Definitions

initialize-paymill (macro)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 paymill

Source

package.lisp (file)

Nickname

pml

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: initialize-paymill KEY

Until you call this macro, the access functions are not defined. You should call it with a key designating your private test- or live- key. If you use a live key, you get charged by Paymill.

Package

paymill

Source

paymill.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: signal-paymill-error STATUS REPLY
Package

paymill

Source

build.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: paymill-bad-request ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-error ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

simple-error (condition)

Direct subclasses
Direct methods
Direct slots
Slot: reply
Initargs

:reply

Readers

reply (generic function)

Slot: status
Initargs

:status

Readers

status (generic function)

Condition: paymill-general-error ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-not-found ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-precondition-failed ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-server-error ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-transaction-error ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)

Condition: paymill-unauthorized ()
Package

paymill

Source

build.lisp (file)

Direct superclasses

paymill-error (condition)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *cookie-jar*
Package

paymill

Source

build.lisp (file)

Special Variable: *paymill-host*
Package

paymill

Source

build.lisp (file)

Special Variable: *pm-reply*
Package

paymill

Source

build.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: define-resource-access RESOURCE INSTR-LIST KEY

This macro defines a uniform way of defining access to Paymill API resources. See README for usage.

Package

paymill

Source

build.lisp (file)

Macro: with-pm-request REQUEST-FORM &body BODY

Does error checking of the reply from Paymill resulting from REQUEST-FORM. If there are no errors, it binds (per-thread, locally) the variable *PM-REPLY* to the data associated with Paymill’s reply for use in BODY, otherwise it signals ’an appropriate error’.

Package

paymill

Source

build.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: clear-cookie-jar ()
Package

paymill

Source

build.lisp (file)

Function: in-pairs LST
Package

paymill

Source

build.lisp (file)

Function: normalize-interval INTERVAL
Package

paymill

Source

build.lisp (file)

Function: normalize-slot SL
Package

paymill

Source

build.lisp (file)

Function: pm-quri RESOURCE QUERY

Like PM-URI, but for designating QUERY (string) parameters when RESOURCE is the target.

Package

paymill

Source

build.lisp (file)

Function: pm-uri RESOURCE &optional TARGET

RESOURCE is a keyword specifying a paymill api interface. TARGET is an optional generalized boolean (must be a string if it is given) which is used to determine if path should end in /TARGET.

Package

paymill

Source

build.lisp (file)

Function: resource-from-keyword KEYWORD
Package

paymill

Source

build.lisp (file)

Function: slots SLOTSPECS
Package

paymill

Source

build.lisp (file)

Function: webhook-slots SLOTSPECS
Package

paymill

Source

build.lisp (file)

Function: x-www-form-encode-pairs SLOTSP DATA
Package

paymill

Source

build.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Generic functions

Generic Function: reply CONDITION
Package

paymill

Methods
Method: reply (CONDITION paymill-error)
Source

build.lisp (file)

Generic Function: status CONDITION
Package

paymill

Methods
Method: status (CONDITION paymill-error)
Source

build.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-paymill.asd: The cl-paymill<dot>asd file
cl-paymill/build.lisp: The cl-paymill/build<dot>lisp file
cl-paymill/package.lisp: The cl-paymill/package<dot>lisp file
cl-paymill/paymill.lisp: The cl-paymill/paymill<dot>lisp file

F
File, Lisp, cl-paymill.asd: The cl-paymill<dot>asd file
File, Lisp, cl-paymill/build.lisp: The cl-paymill/build<dot>lisp file
File, Lisp, cl-paymill/package.lisp: The cl-paymill/package<dot>lisp file
File, Lisp, cl-paymill/paymill.lisp: The cl-paymill/paymill<dot>lisp file

L
Lisp File, cl-paymill.asd: The cl-paymill<dot>asd file
Lisp File, cl-paymill/build.lisp: The cl-paymill/build<dot>lisp file
Lisp File, cl-paymill/package.lisp: The cl-paymill/package<dot>lisp file
Lisp File, cl-paymill/paymill.lisp: The cl-paymill/paymill<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   D   F   G   I   M   N   P   R   S   W   X  
Index Entry  Section

C
clear-cookie-jar: Internal functions

D
define-resource-access: Internal macros

F
Function, clear-cookie-jar: Internal functions
Function, in-pairs: Internal functions
Function, normalize-interval: Internal functions
Function, normalize-slot: Internal functions
Function, pm-quri: Internal functions
Function, pm-uri: Internal functions
Function, resource-from-keyword: Internal functions
Function, signal-paymill-error: Exported functions
Function, slots: Internal functions
Function, webhook-slots: Internal functions
Function, x-www-form-encode-pairs: Internal functions

G
Generic Function, reply: Internal generic functions
Generic Function, status: Internal generic functions

I
in-pairs: Internal functions
initialize-paymill: Exported macros

M
Macro, define-resource-access: Internal macros
Macro, initialize-paymill: Exported macros
Macro, with-pm-request: Internal macros
Method, reply: Internal generic functions
Method, status: Internal generic functions

N
normalize-interval: Internal functions
normalize-slot: Internal functions

P
pm-quri: Internal functions
pm-uri: Internal functions

R
reply: Internal generic functions
reply: Internal generic functions
resource-from-keyword: Internal functions

S
signal-paymill-error: Exported functions
slots: Internal functions
status: Internal generic functions
status: Internal generic functions

W
webhook-slots: Internal functions
with-pm-request: Internal macros

X
x-www-form-encode-pairs: Internal functions

Jump to:   C   D   F   G   I   M   N   P   R   S   W   X  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
R   S  
Index Entry  Section

*
*cookie-jar*: Internal special variables
*paymill-host*: Internal special variables
*pm-reply*: Internal special variables

R
reply: Exported conditions

S
Slot, reply: Exported conditions
Slot, status: Exported conditions
Special Variable, *cookie-jar*: Internal special variables
Special Variable, *paymill-host*: Internal special variables
Special Variable, *pm-reply*: Internal special variables
status: Exported conditions

Jump to:   *  
R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-paymill: The cl-paymill system
Condition, paymill-bad-request: Exported conditions
Condition, paymill-error: Exported conditions
Condition, paymill-general-error: Exported conditions
Condition, paymill-not-found: Exported conditions
Condition, paymill-precondition-failed: Exported conditions
Condition, paymill-server-error: Exported conditions
Condition, paymill-transaction-error: Exported conditions
Condition, paymill-unauthorized: Exported conditions

P
Package, paymill: The paymill package
paymill: The paymill package
paymill-bad-request: Exported conditions
paymill-error: Exported conditions
paymill-general-error: Exported conditions
paymill-not-found: Exported conditions
paymill-precondition-failed: Exported conditions
paymill-server-error: Exported conditions
paymill-transaction-error: Exported conditions
paymill-unauthorized: Exported conditions

S
System, cl-paymill: The cl-paymill system

Jump to:   C   P   S