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 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:

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

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:

GET /api/v1/organizers/bigevents/bankimportjobs/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

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 Parameters:

  • page – The page number in case of a multi-page result set, default is 1

  • event – Return only jobs for the event with the given slug

  • state – Return only jobs with the given state

Parameters:

  • organizer – The slug field of a valid organizer

Status Codes:
GET /api/v1/organizers/(organizer)/bankimportjobs/(id)/

Returns information on one job, identified by its ID.

Example request:

GET /api/v1/organizers/bigevents/bankimportjobs/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

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": ""
    }
   ]
}
Parameters:

  • organizer – The slug field of the organizer to fetch

Status Codes:
POST /api/v1/organizers/(organizer)/bankimportjobs/

Upload a new job and execute it.

Example request:

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:

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.

Parameters:

  • organizer – The slug field of a valid organizer

Status Codes: