mirror of
https://github.com/pretix/pretix.git
synced 2025-12-06 21:42:49 +00:00
211 lines
7.8 KiB
ReStructuredText
211 lines
7.8 KiB
ReStructuredText
Bank transfer
|
|
=============
|
|
|
|
The built-in 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
|