Bank transfer HTTP API ====================== The banktransfer plugin provides a HTTP API that `pretix-banktool`_ uses to send bank transactions to the pretix server. This API is integrated with the regular :ref:`rest-api` and therefore follows the conventions listed there. Bank import job resource ^^^^^^^^^^^^^^^^^^^^^^^^ Resource description -------------------- The bank import job resource contains the following public fields: .. rst-class:: rest-resource-table ===================================== ========================== ======================================================= Field Type Description ===================================== ========================== ======================================================= id integer Internal job ID event string Slug of the event this job was uploaded for or ``null`` created datetime Job creation time state string Job state, one of ``pending``, ``running``, ``error`` or ``completed`` transactions list of objects Transactions included in this job (will only appear after the job has started processing). ├ state string Transaction state, one of ``imported``, ``nomatch``, ``invalid``, ``error``, ``valid``, ``discarded``, ``already`` (already paid) ├ message string Error message (if any) ├ checksum string Checksum computed from payer, reference, amount and date ├ payer string Payment source ├ external_id string Unique ID of the payment from an external source ├ reference string Payment reference ├ amount string Payment amount ├ iban string Payment IBAN ├ bic string Payment BIC ├ date string Payment date (in **user-inputted** format) ├ order string Associated order code (or ``null``) └ comment string Internal comment ===================================== ========================== ======================================================= Note that the ``payer`` and ``reference`` fields are set to empty as soon as the payment is matched to an order or discarded to avoid storing sensitive data when not necessary. The ``checksum`` persists to implement deduplication. Endpoints --------- .. http:get:: /api/v1/organizers/(organizer)/bankimportjobs/ Returns a list of all bank import jobs within a given organizer the authenticated user/token has access to. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/bankimportjobs/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "state": "completed", "created": "2017-06-27T08:00:29Z", "event": "sampleconf", "transactions": [ { "amount": "57.00", "comment": "", "date": "26.06.2017", "payer": "John Doe", "order": null, "external_id": null, "iban": "", "bic": "", "checksum": "5de03a601644dfa63420dacfd285565f8375a8f2", "reference": "GUTSCHRIFT\r\nSAMPLECONF-NAB12 EREF: SAMPLECONF-NAB12\r\nIBAN: DE1234556…", "state": "nomatch", "message": "" } ] } ] } :query page: The page number in case of a multi-page result set, default is 1 :query event: Return only jobs for the event with the given slug :query state: Return only jobs with the given state :param organizer: The ``slug`` field of a valid organizer :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer does not exist **or** you have no permission to view it. .. http:get:: /api/v1/organizers/(organizer)/bankimportjobs/(id)/ Returns information on one job, identified by its ID. **Example request**: .. sourcecode:: http GET /api/v1/organizers/bigevents/bankimportjobs/1/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "id": 1, "state": "completed", "created": "2017-06-27T08:00:29Z", "event": "sampleconf", "transactions": [ { "amount": "57.00", "comment": "", "date": "26.06.2017", "payer": "John Doe", "iban": "", "bic": "", "order": null, "external_id": null, "checksum": "5de03a601644dfa63420dacfd285565f8375a8f2", "reference": "GUTSCHRIFT\r\nSAMPLECONF-NAB12 EREF: SAMPLECONF-NAB12\r\nIBAN: DE1234556…", "state": "nomatch", "message": "" } ] } :param organizer: The ``slug`` field of the organizer to fetch :statuscode 200: no error :statuscode 401: Authentication failure :statuscode 403: The requested organizer/event does not exist **or** you have no permission to view it. .. http:post:: /api/v1/organizers/(organizer)/bankimportjobs/ Upload a new job and execute it. **Example request**: .. sourcecode:: http POST /api/v1/organizers/bigevents/bankimportjobs/ HTTP/1.1 Host: pretix.eu Accept: application/json, text/javascript Content-Type: application/json { "event": "sampleconf", "transactions": [ { "payer": "Foo", "reference": "SAMPLECONF-173AS", "amount": "23.00", "date": "2017-06-26" } ] } **Example response**: .. sourcecode:: http HTTP/1.1 201 Created Vary: Accept Content-Type: text/javascript { "id": 1, "state": "pending", "created": "2017-06-27T08:00:29Z", "event": "sampleconf", "transactions": [] } .. note:: Depending on the server configuration, the job might be executed immediately, leading to a longer API response time but a response with state ``completed`` or ``error``, or the job might be put into a background queue, leading to an immediate response of state ``pending`` with an empty list of transactions. :param organizer: The ``slug`` field of a valid organizer :statuscode 201: no error :statuscode 400: Invalid input :statuscode 401: Authentication failure :statuscode 403: The requested organizer does not exist **or** you have no permission to perform this action. .. _pretix-banktool: https://github.com/pretix/pretix-banktool