NX Technologies - bezahl.de (0.7.1)

Download OpenAPI specification:Download

Description

This document describes the handling of the API and the basic concepts of sending payment requests and how to get updates when a buyer paid the payments.

The API is a JSON REST API which reports every information in real-time. There are no batch processes involved (an additional webhook will be released soon).

Basic principles

  1. User An user can signup and use the service for free. All users are identified via the email address.

  2. Organizations To send a payment request an user has to create an organization, which holds the information about organization address, target iban, allowed payment methods. An organization can have multiple users with different roles.

  3. Orders and Payments The payment request is called by order within the API. Every order belongs to an organization and a creator user. When a payer makes a payment, the order will be updated with the information regarding the payment status.

Limitations

  1. Every organization (without a contract) has the ability to create only two orders and invite one additional user.

    1. If you’re using the staging environment and it is down more than 10 minutes, please inform us, that you need this environment.

    2. If you miss an API endpoint, we may not have documented the endpoint yet. Just ask us and we are happy to help you.

    3. If you use our bezahl.de partner environment, you can enter one of the following IBANs in the organization settings.

      ● DE16111111112222222222 ● DE66111111113333333333 ● DE19111111114444444444 ● DE69111111115555555555 ● DE22111111116666666666 ● DE72111111117777777777 ● DE25111111118888888888 ● DE75111111119999999999

Environments

We provide different systems for you to access the bezahl.de API.

TEST Environment

Authentication

For the authentication with our system we provide a token which can be generated at [host]/clients.

NX-Token

Then the user receives a token which should be provided for each call as NX-Token header.

  1. Now you can access the API in the name of the user with the HTTP Header NX-Token.
     curl -X GET \
       https://partnerapi.staging.bezahl.de/nxt/v1/user \
       -H 'Content-Type: application/json' \
       -H 'NX-Token: [token]'

generate NX-Token

  1. Login into your account on your preferred environment. Switch to "Your Profile" and click on the button: "Token overview".

  2. Here you can create an API-Token with your preferred expiration time and the description.

  3. After creation you can copy the shown key in the http request header.

Workflow Overview

shows the process workflow

  1. You create a new payment request (order).

     POST [API]/order/plan
     {
       "orgId": "abcdef", // organization id
       "order": {
       "name": "Zahlung #123", // public name
       "assets": [
         {
           "label": "Kaufpreis", // cost position name
           "amount": 2000000 // cost position price
           }
         ]
       } 
     }
    
     // response
     {
       "id": "BJ8ivGHSKq", // order reference
       ...
     }
  2. (Optional) You send the order via e-mail.

     POST [API]/order/:orderid/recipient
     {
       "recipient" : {
         "email": "mail@example.com"
       }
     }
    
     //response
     { ... }
  3. Payer will receive the payment request via e-mail (from bezahl.de if setup in step 2) or directly from the seller.

  4. Payer will choose one of the payment methods and will start the payment process.

  5. Every status update is requestable via API.

     GET [API]/order/:orderid
    
     //response
     {
       "status": "open",
       ...
     }

Questions

If you have any questions, do not hesitate to contact us at dev@nx-technologies.com or our customer service at https://bezahl.de/contact.

Q: I get an error with no response or server error? A: Please check on your request if the url, method and data which you send is correct. For testing purpose use https://partnerapi.bezahl.de/ and for the live system https://api.bezahl.de/ as base url. If the problem persist feel free to contact us.

Q: I get some service error "missing orgId/name"? A: Please check the params if every required param is in the request body or in the request url.

Q: I get a validation error such as "please insert a valid email"? A: Please check the type of your params and if they contain the right data.

order

Create and track status of an order.

get all orders

This can only be done by the logged in user.

query Parameters
orgId
required
string

ID of the organization the orders will be listed.

bulk
string

ID of the order.

limit
number

max limit of the request

unique
string

unique value that can be used as a custom identifier for the order. This needs to be activated in the orga settings. The behaviour (eg. throw error if 2 uniques are the same) can be adjusted there aswell.

startat
number

define the start of the request

search
string

search for ordername, contactperson and metafields

status
string
Enum: "open" "confirmed"

filter by status

filter
string
Enum: "inclhidden" "onlyhidden" "hideclosed" "hidehidden" "over" "pickupWithoutPayment" "norecipient" "hasrecipient"

possible filter words. usage: filter: "inclhidden,hasrecipient"

period
string

limit to period of time e.g. 01.01.2022,16.05.2022

contact
string

filter by contactperson

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "list": [
    ]
}

get one order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order.

query Parameters
fieldnames
Array of strings

if this is set you get only selected fields from the response. For example the name and amount; ?fieldnames=name&fieldnames=assets

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "organization": {
    },
  • "fstatus": "open",
  • "pickupdate": "2019-08-24",
  • "paymentoptions": {
    },
  • "assets": [
    ],
  • "paymentsInfo": [
    ],
  • "attachments": [
    ],
  • "recipient": [
    ],
  • "creator": {
    },
  • "contactperson": {
    },
  • "accountData": {
    },
  • "paymentdata": {
    },
  • "link": "string",
  • "tags": [
    ],
  • "metafields": [
    ],
  • "customer": {
    },
  • "vehicle": {
    },
  • "invoice": [
    ],
  • "header": {
    },
  • "location": {
    }
}

get offline pdf for the order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

query Parameters
link
boolean

if this is set to true you get a download link for the offline pdf instead of the pdf itself

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "order.update.name.success",
  • "message": "Erfolgreich gespeichert"
}

add new order with assets

This can only be done by the logged in user.

header Parameters
NX-Token
required
string
Request Body schema: application/json
orgId
required
string

ID of the organization the order will be assigned.

required
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "orgId": "string",
  • "order": {
    },
  • "assets": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "_meta": {
    }
}

upload attachment

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: multipart/form-data
attachment
string <binary>

File size has to be less than 3mb; body should be a form-data object which contains the file with the key 'attachment'

Responses

Response samples

Content type
application/json
{
  • "key": "order.attachment.success",
  • "message": "Erfolgreich gespeichert"
}

delete attachment

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
url
string
item
string

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "item": "string"
}

Response samples

Content type
application/json
{
  • "key": "order.attachment.success",
  • "message": "Erfolgreich gespeichert"
}

add recipient

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "recipient": {
    }
}

Response samples

Content type
application/json
{
  • "key": "order.recipient.add.success",
  • "message": "Erfolgreich gespeichert"
}

remove recipient

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
email
string

Email address of the buyer (recipient).

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "key": "order.recipient.delete.success",
  • "message": "Erfolgreich gespeichert"
}

update assets

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "assets": [
    ]
}

Response samples

Content type
application/json
{
  • "key": "order.update.price.success",
  • "message": "Erfolgreich gespeichert"
}

update name of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "key": "order.update.name.success",
  • "message": "Erfolgreich gespeichert"
}

update contactperson of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
contactperson
required
string

Responses

Request samples

Content type
application/json
{
  • "contactperson": "contactperson@email.com"
}

Response samples

Content type
application/json
{
  • "key": "order.update.name.success",
  • "message": "Erfolgreich gespeichert"
}

update watcher of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
watcher
required
string
orgId
required
string

Responses

Request samples

Content type
application/json
{
  • "watcher": "watcher@email.com",
  • "orgId": "string"
}

Response samples

Content type
application/json
{
  • "key": "order.update.name.success",
  • "message": "Erfolgreich gespeichert"
}

add or update duedate of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
duedate
required
string <date>

Responses

Request samples

Content type
application/json
{
  • "duedate": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "key": "order.duedate.add.success",
  • "message": "Erfolgreich gespeichert"
}

delete duedate of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "order.duedate.delete.success",
  • "message": "Erfolgreich gespeichert"
}

add or update pickupdate of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
pickupdate
string <date>

Responses

Request samples

Content type
application/json
{
  • "pickupdate": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "key": "order.update.pickupdate.success",
  • "message": "Erfolgreich gespeichert"
}

delete pickupdate of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "order.delete.pickupdate.success",
  • "message": "Erfolgreich gespeichert"
}

add or update metafields of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
required
Array of objects
override
boolean
Default: false

override existing fields with new data

Responses

Request samples

Content type
application/json
{
  • "metafields": [
    ],
  • "override": false
}

Response samples

Content type
application/json
{
  • "key": "order.update.metafields.success",
  • "message": "Erfolgreich gespeichert"
}

add or update invoicefields of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
Array of objects

Responses

Request samples

Content type
application/json
{
  • "invoice": [
    ]
}

Response samples

Content type
application/json
{
  • "key": "order.update.invoicefields.success",
  • "message": "Erfolgreich gespeichert"
}

add or update customerfields of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "key": "order.update.customerfields.success",
  • "message": "Erfolgreich gespeichert"
}

add or update vehiclefields of order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "vehicle": {
    }
}

Response samples

Content type
application/json
{
  • "key": "order.update.vehiclefields.success",
  • "message": "Erfolgreich gespeichert"
}

archive or archive and close order

This can only be done by the logged in user.

path Parameters
id
required
string

ID of the single order

header Parameters
NX-Token
required
string
Request Body schema: application/json
closed
boolean

Responses

Request samples

Content type
application/json
{
  • "closed": true
}

Response samples

Content type
application/json
{
  • "key": "order.hide.success",
  • "message": "Erfolgreich gespeichert"
}

organization

Maintain an organization.

get list of organization

This can only be done by the logged in user.

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get one organization

This can only be done by the logged in user.

path Parameters
orgId
required
string

ID of the organization.

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "key": "string",
  • "name": "string",
  • "nick": "string",
  • "picture": "string",
  • "contact": {
    },
  • "users": [
    ],
  • "bankaccounts": [
    ],
  • "paymentoptions": {
    },
  • "tags": [
    ],
  • "location": [
    ]
}

get orders that changed since

This can only be done by the logged in user.

path Parameters
orgId
required
string

ID of the organization.

query Parameters
since
required
string <date>
Example: since=2022-04-01T00:00:00.000Z

Date as UTC timestamp.

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
[
  • "string"
]

create one organization

This can only be done by the logged in user.

header Parameters
NX-Token
required
string
Request Body schema: application/json
name
required
string

Name of the organization. In most cases, the full company name. Also shown to buyer.

nick
string

Displayed organization name to differentiate, for example, between different locations or branch offices.

object

Contact details of the organization.

object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "nick": "string",
  • "contact": {
    },
  • "paymentoptions": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "_meta": {
    },
  • "key": "organization.add.success",
  • "message": "Erfolgreich gespeichert"
}

add location to orga

Save multiple locations to a single organization.

path Parameters
orgId
required
string

ID of the organization.

header Parameters
NX-Token
required
string
Request Body schema: application/json
id
required
string

This is the orgID

name
required
string
rout
string
street
string
streetnumber
string
city
string
vendorid
string

This property will be matched with the location when creating an order

commerceType
string
Enum: "commerce" "service"
iban
required
string <iban>

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "rout": "string",
  • "street": "string",
  • "streetnumber": "string",
  • "city": "string",
  • "vendorid": "string",
  • "commerceType": "commerce",
  • "iban": "string"
}

Response samples

Content type
application/json
{
  • "key": "organization.location.success",
  • "message": "Erfolgreich gespeichert",
  • "version": 4
}

get payment report

This can only be done by the logged in user.

path Parameters
orgId
required
string

ID of the organization.

header Parameters
NX-Token
required
string
Request Body schema: application/json
from
string <date>

Date as UTC timestamp. Start date of interval for payment report.

to
string <date>

Date as UTC timestamp. End date of interval for payment report.

Responses

Request samples

Content type
application/json
{
  • "from": "2019-08-24",
  • "to": "2019-08-24"
}

Response samples

Content type
application/json
[
  • {
    }
]

upload file for system unknown payments

This can only be done by the logged in user.

path Parameters
orgId
required
string

ID of the organization.

header Parameters
NX-Token
required
string
Request Body schema: multipart/form-data
attachment
string <binary>

File size has to be less than 5mb; body should be a form-data object which contains the file with the key 'attachment'. The file should be a csv or tsv and required the columns uniqueBookingId, label, amount, orderId, invoiceNo.

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "new": 0,
  • "skip": 1,
  • "key": "bookings.import.success",
  • "message": "Erfolgreich gespeichert",
  • "responseversion": 4
}

upload json for system unknown payments

This can only be done by the logged in user.

path Parameters
orgId
required
string

ID of the organization.

header Parameters
NX-Token
required
string
Request Body schema: application/json
required
Array of objects

Each Object represent a payment to import

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "count": 2,
  • "new": 2,
  • "skip": 0,
  • "key": "bookings.file.success",
  • "message": "Erfolgreich gespeichert",
  • "responseversion": 4
}

user

Information about the user.

getUser Data

This can only be done by the logged in user.

header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "SJyN6dR-7",
  • "email": "foo@bar.de",
  • "activeOrganization": "5b3379c1b81d2b5c81619f85"
}

webhook

Setup

If you want to set up a webhook for continuous updates for your orders please contact dev@nx-technologies.com so we can whitelist your URL.

Keys

Webhook Key Reason
order.created An order has been created
order.confirmed The order has been fully paid (includes gwg check if neccessarry)
order.archived The order has been archived
order.assets.updated An asset of the order has been updated
order.name.updated The name of the order has been updated
order.payment.created A Payment has been created for the order
order.payment.confirmed The Payment has been confirmed
order.payment.received The Payment has been received
order.payment.reseted The Payment has been resetted
order.payment.gwg.reseted The status for gwg has been resetted
order.payment.deleted The Payment has been deleted
order.payment.updated The Payment has been updated

Example Webhook

{
  "key": "order.name.updated",
  "text": "*order.name.updated* for *<orderName>* (5 €) new status: *open*",
  "order": {
    "id": "<orderId>",
    "name": "<orderName>",
    "figures": {
      "topaytotal": 500,
      "toconfirm": 0,
      "toreceive": 0,
      "isreceived": 0,
      "ispaid": 0,
      "topay": 500,
      "deficit": 500
    },
    "status": "open",
    "createDate": "2022-02-22T22:22:22.222Z"
  },
  "organization": {
    "id": "<organizationId>",
    "name": "<organizationName>"
  },
  "hmac":"48656c6c6f2c2063616e20796f752068656172206d653f2049742773206d652e"
}

hmac contains the HMAC computed by the secret and the webhhook response (excluding hmac) which can be verified by

strippedJSON = stripHmac(responseJSON);
hmac = createHmac('sha256', secret, strippedJSON).hex;
if (responseJSON.hmac !== hmac) throw Error('Invalid hmac');

get webhoook list

This can only be done by the logged in user.

query Parameters
orgId
required
string
header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "list": [
    ]
}

post webhoook

This can only be done by the logged in user.

header Parameters
NX-Token
required
string
Request Body schema: application/json
orgId
required
string
url
required
string
secret
string

Responses

Request samples

Content type
application/json
{
  • "orgId": "string",
  • "url": "string",
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "key": "webhook.create.success",
  • "message": "Erfolgreich gespeichert"
}

delete webhoook

This can only be done by the logged in user.

query Parameters
orgId
required
string
id
required
string
header Parameters
NX-Token
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "webhook.delete.success",
  • "message": "Erfolgreich gespeichert"
}

smartkasse

Start a transaction at a specific smartkasse

In order to initialize a transaction at a specific smartkasse a 3-step process has to be implemented. First: the /list endpoint has to be called, to get a list of all available smartkasse for the organization in question. Second: the returned list has to be used to let the user select the smartkasse where to initialize the transaction. Third: the selected smartkasse id and an order id has to be send to the /startTransaction endpoint.

The Cardreader will then prompt the Customer the amount that has to be paid.

smartkasse list

Returns a list containing all smartkasse belonging to the given orga

path Parameters
orgId
required
string

ID of the organization.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "list": [
    ]
}

smartkasse start transaction

prompts the smartkasse to start a transaction

header Parameters
NX-Token
required
string
Request Body schema: application/json
orderId
required
string

orderId from bezahl.de

smartkasse
required
string

id for the smartkassen (check smartkasse/list)

Responses

Request samples

Content type
application/json
{
  • "orderId": "string",
  • "smartkasse": "string"
}

Response samples

Content type
application/json
{
  • "_meta": {
    }
}

adyen

Information about payments from our smartkasse

processSettlementReport

Get paymentdata from adyen and process it accordingly to organization settings.

This can only be done by the logged in user.

header Parameters
NX-Token
required
string
Request Body schema: application/json
orgId
required
string

id of the organization

batch
number

batch number to pull from adyen

isJSON
boolean

response will contain the report in json, no mail is send

force
boolean

send the report by mail regardless of organization settings

Responses

Request samples

Content type
application/json
{
  • "orgId": "string",
  • "batch": 0,
  • "isJSON": true,
  • "force": true
}

Response samples

Content type
application/json
{
  • "_meta": {
    }
}