API Foundations

Introduction

Welcome to the PayJinn API Foundation documentation. All of the PayJinn APIs are developed to provide easy integration for our customers. Topics like registration, authentication, security, data formats and error handling are covered in this section.

Registration

In order to use this any of our APIs, you must first register a new PayJinn user either as a Partner/Developer (Entwickler) or Supplier (Haendler, Verkaeufer).

After successfull registration, please login to system and go to dashboard. From dashboard go to API Operations menu. First of all we have to acquire some basic information about you or your company. This information will go through an API client approval process during which our business team may get in touch with you if needed. In parallel to this process, we will send you an information email about your PayJinn Client Id and API key. Your API credentials will become operational after your API client is approved.

You can always renew your API Key periodically or in case of compromise. In order to do so please find Renew API Key form under API Operations menu at the dashboard.

Data Formats

We are using HTTP header "Content-Type” and “Accept” fields for content negotiation. API clients should set them according to their abilities and preferences. “Application/json” is used as fallback for the default response representation.

Authentication

HTTP requests to the our APIs are protected with HTTP Basic authentication (RFC 2617). In order to connect you have to provide your PayJinn Client Id and API Key at each request. At the request header, concatenate your client id as user name and your API key as password, separated by ":" and encode the result using Base64. After successful authentication, the server will confirm your API call with HTTP 200 OK.

REMARK: Our API is served only over HTTPS in order to ensure data security. Unencrypted HTTP protocol is not supported.
DEMO ACCOUNT: Below client id and api key can be used for development and testing purposes.
  • Client Id: TEST0001
  • API Key: 12345678

Error handling

PayJinn APIs return the appropriate HTTP return codes in order to signal an error condition. The following list contains the constants and corresponding values for the HTTP status codes returned by our APIs:

1xx: Information

Message

Description

100 Continue

The server has received the request headers, and the client should proceed to send the request body

101 Switching Protocols

The requester has asked the server to switch protocols

103 Checkpoint

Used in the resumable requests proposal to resume aborted PUT or POST requests

 

2xx: Successful

Message

Description

200 OK

The request is OK (this is the standard response for successful HTTP requests)

201 Created

The request has been fulfilled, and a new resource is created

202 Accepted

The request has been accepted for processing, but the processing has not been completed

203 Non-Authoritative Information

The request has been successfully processed, but is returning information that may be from another source

204 No Content

The request has been successfully processed, but is not returning any content

205 Reset Content

The request has been successfully processed, but is not returning any content, and requires that the requester reset the document view

206 Partial Content

The server is delivering only part of the resource due to a range header sent by the client

 

3xx: Redirection

Message

Description

300 Multiple Choices

A link list. The user can select a link and go to that location. Maximum five addresses

301 Moved Permanently

The requested page has moved to a new URL

302 Found

The requested page has moved temporarily to a new URL

303 See Other

The requested page can be found under a different URL

304 Not Modified

Indicates the requested page has not been modified since last requested

306 Switch Proxy

No longer used

307 Temporary Redirect

The requested page has moved temporarily to a new URL

308 Resume Incomplete

Used in the resumable requests proposal to resume aborted PUT or POST requests

 

4xx: Client Error

Message

Description

400 Bad Request

The request cannot be fulfilled due to bad syntax

401 Unauthorized

The request was a legal request, but the server is refusing to respond to it. For use when authentication is possible but has failed or not yet been provided

402 Payment Required

Reserved for future use

403 Forbidden

The request was a legal request, but the server is refusing to respond to it

404 Not Found

The requested page could not be found but may be available again in the future

405 Method Not Allowed

A request was made of a page using a request method not supported by that page

406 Not Acceptable

The server can only generate a response that is not accepted by the client

407 Proxy Authentication Required

The client must first authenticate itself with the proxy

408 Request Timeout

The server timed out waiting for the request

409 Conflict

The request could not be completed because of a conflict in the request

410 Gone

The requested page is no longer available

411 Length Required

The "Content-Length" is not defined. The server will not accept the request without it

412 Precondition Failed

The precondition given in the request evaluated to false by the server

413 Request Entity Too Large

The server will not accept the request, because the request entity is too large

414 Request-URI Too Long

The server will not accept the request, because the URL is too long. Occurs when you convert a POST request to a GET request with a long query information

415 Unsupported Media Type

The server will not accept the request, because the media type is not supported

416 Requested Range Not Satisfiable

The client has asked for a portion of the file, but the server cannot supply that portion

417 Expectation Failed

The server cannot meet the requirements of the Expect request-header field

 

5xx: Server Error

Message

Description

500 Internal Server Error

A generic error message, given when no more specific message is suitable

501 Not Implemented

The server either does not recognize the request method, or it lacks the ability to fulfill the request

502 Bad Gateway

The server was acting as a gateway or proxy and received an invalid response from the upstream server

503 Service Unavailable

The server is currently unavailable (overloaded or down)

504 Gateway Timeout

The server was acting as a gateway or proxy and did not receive a timely response from the upstream server

505 HTTP Version Not Supported

The server does not support the HTTP protocol version used in the request

511 Network Authentication Required

The client needs to authenticate to gain network access