NX Technologies - bezahl.de (0.7.1)

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).

1. User A user can be invited, then register and use the service free of charge. All users are identified by their e-mail 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.

1. Every organization (without a contract) has the ability to create only two orders and invite one additional user.
2. If you’re using the staging environment and it is down more than 10 minutes, please inform us, that you need this environment.
3. If you miss an API endpoint, we may not have documented the endpoint yet. Just ask us and we are happy to help you.
4. 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

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

• Frontend: https://dashboard.bezahl.de
• API: https://api.bezahl.de/nxt/v1/[path]

• Frontend: https://partner.staging.bezahl.de
• API: https://partnerapi.staging.bezahl.de/nxt/v1/[path] (Hostname for staging may change in future)
• Last change: 09.07.2019*

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

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]'
   

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.

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 email.

   POST [API]/order/:orderid/recipient
   {
     "recipient" : {
       "email": "mail@example.com"
     }
   }
   
   //response
   { ... }
   

3. Payer will receive the payment request via email (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",
     ...
   }
   

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.staging.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.

Create and track status of an order.

Maintain an organization.