The cl-paymill Reference Manual

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 4.0 beta 2 "William Riker" on Mon Aug 15 03:54:19 2022 GMT+0.

Table of Contents


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.



2 Systems

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


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

2.1 cl-paymill

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

Author

Peter Wood, email: pete_wood at runbox.com

License

BSD, 2 clause.

Version

0.0.1

Dependencies
  • drakma (system).
  • st-json (system).
  • cl+ssl (system).
Source

cl-paymill.asd.

Child Components

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   [Contents][Index]

3.1.1 cl-paymill/cl-paymill.asd

Source

cl-paymill.asd.

Parent Component

cl-paymill (system).

ASDF Systems

cl-paymill.


3.1.2 cl-paymill/package.lisp

Source

cl-paymill.asd.

Parent Component

cl-paymill (system).

Packages

paymill.


3.1.3 cl-paymill/build.lisp

Dependency

package.lisp (file).

Source

cl-paymill.asd.

Parent Component

cl-paymill (system).

Public Interface
Internals

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

3.1.4 cl-paymill/paymill.lisp

Dependency

build.lisp (file).

Source

cl-paymill.asd.

Parent Component

cl-paymill (system).

Public Interface

initialize-paymill (macro).


4 Packages

Packages are listed by definition order.


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

4.1 paymill

Source

package.lisp.

Nickname

pml

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


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.


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.2 Ordinary functions

Function: signal-paymill-error (status reply)
Package

paymill.

Source

build.lisp.


5.1.3 Conditions

Condition: paymill-bad-request
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-error
Package

paymill.

Source

build.lisp.

Direct superclasses

simple-error.

Direct subclasses
Direct methods
Direct slots
Slot: reply
Initargs

:reply

Readers

reply.

Writers

This slot is read-only.

Slot: status
Initargs

:status

Readers

status.

Writers

This slot is read-only.

Condition: paymill-general-error
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-not-found
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-precondition-failed
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-server-error
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-transaction-error
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.

Condition: paymill-unauthorized
Package

paymill.

Source

build.lisp.

Direct superclasses

paymill-error.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *cookie-jar*
Package

paymill.

Source

build.lisp.

Special Variable: *paymill-host*
Package

paymill.

Source

build.lisp.

Special Variable: *pm-reply*
Package

paymill.

Source

build.lisp.


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.

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.


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

5.2.3 Ordinary functions

Function: clear-cookie-jar ()
Package

paymill.

Source

build.lisp.

Function: in-pairs (lst)
Package

paymill.

Source

build.lisp.

Function: normalize-interval (interval)
Package

paymill.

Source

build.lisp.

Function: normalize-slot (sl)
Package

paymill.

Source

build.lisp.

Function: pm-quri (resource query)

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

Package

paymill.

Source

build.lisp.

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.

Function: resource-from-keyword (keyword)
Package

paymill.

Source

build.lisp.

Function: slots (slotspecs)
Package

paymill.

Source

build.lisp.

Function: webhook-slots (slotspecs)
Package

paymill.

Source

build.lisp.

Function: x-www-form-encode-pairs (slotsp data)
Package

paymill.

Source

build.lisp.


5.2.4 Generic functions

Generic Reader: reply (condition)
Package

paymill.

Methods
Reader Method: reply ((condition paymill-error))
Source

build.lisp.

Target Slot

reply.

Generic Reader: status (condition)
Package

paymill.

Methods
Reader Method: status ((condition paymill-error))
Source

build.lisp.

Target Slot

status.


Appendix A Indexes


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

A.1 Concepts


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: Private ordinary functions

D
define-resource-access: Private macros

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

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

I
in-pairs: Private ordinary functions
initialize-paymill: Public macros

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

N
normalize-interval: Private ordinary functions
normalize-slot: Private ordinary functions

P
pm-quri: Private ordinary functions
pm-uri: Private ordinary functions

R
reply: Private generic functions
reply: Private generic functions
resource-from-keyword: Private ordinary functions

S
signal-paymill-error: Public ordinary functions
slots: Private ordinary functions
status: Private generic functions
status: Private generic functions

W
webhook-slots: Private ordinary functions
with-pm-request: Private macros

X
x-www-form-encode-pairs: Private ordinary functions

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