DirectPay API

Introduction

Welcome to the PayJinn DirectPay API documentation. This API allows you to integrate PayJinn DirectPay infrastructure to your application. (i.e: Your e-commerce site, seller to supplier money transfer program, etc.) Same API can also be used for generating External Payment sessions for client's who are registered for PayJinn's multi payment solution.

PayJinn DirectPay Flow

DirectPay Flow Diagram

INFO:
  • @C: Customer’s browser
  • @S: Supplier’s host system
  • @PJ: PayJinn system

Step 1 (@C):
Customer (End User, Seller) selects PayJinn DirectPay as the payment method from his/her browser.

Step 2: (@S)
Payment method selection is sent to Supplier’s host system. At this step supplier host software should call NewPayment API. Following inputs are used for API call:

  • PayJinn API Client Id
  • PayJinn API Key
  • Transaction amount.
  • Supplier’s Base Account IBAN. (Can be left empty if supplier wants to use the default base account to receive payment.)
  • Supplier Order Code
  • Supplier Notification URL. (System will redirect to this URL if transaction fails.)
  • Supplier Success URL. (System will redirect to this URL if transaction succeeds.)

Step 3: (@PJ)
NewPayment API request is processed at PayJinn System. After successful authorization, response message containing new PayJinn Transaction Id and Payment Session URL is sent back to Supplier’s host.

Step 4: (@S)
Supplier host sends a redirect to Payment Session URL message to customer’s browser.

NOTE:
After the payment session is created, you should always redirect your payer (end user, customer) directly to the PayJinn's payment form to ensure the base URL (https://www.payjinn.com) and the PayJinn SSL certificate are visible to payer. Note that framed solutions (i.e: <iframe>) which are hiding URL and SSL certificate from payer are not allowed due to legal reasons.

Step 5 (@C):
Customer’s browser will request the Payment Session URL from PayJinn system.

Step 6 (@PJ):
PayJinn system responds back to customer’s browser with session page.

Step 7-8 (@C-@PJ):
Customer completes payment by entering his online banking details at related PayJinn DirectPay steps.

  • Direct Pay Step 1: Customer enters his/her BLZ information.
    View of the DirectPay session step 1.

  • Direct Pay Step 2: Customer enters his/her online banking number and pin (FinTS/HBCI) information.
    View of the DirectPay session step 2.

  • Direct Pay Step 3: Customer enters his/her TAN (FinTS/HBCI).
    View of the DirectPay session step 3.

Step 9 (@C):
Outcome of steps 7 and 8 can be one of following:

  • Case 1: Customers bank (BLZ) not supported.
  • Case 2: Customer provided online banking number or pin is incorrect.
  • Case 3: Customer provided TAN is incorrect.
  • Case 4: System Error occured. (This can be PayJinn or customer’s bank related.)
  • Case 5: Customer cancelled transaction
  • Case 6: Transaction accepted.

For the cases 1 to 5, PayJinn system will send a redirect to supplier’s notification URL message to customer’s browser. Payijnn will add transaction id, supplier order code and transaction result to the end of adress as URL encoded parameters. Following parameters are used:

  • CPayjinnTransactionId=<TransactionId>
  • OrderCode=<SupplierOrderCode>
    (Only added if supplier sent an order code during NewPayment API call.)
  • PayjinnStatus=Abgebrochen or PayjinnStatus=Error
  • Example:
    www.supplier.com/OnNotify?PayjinnTransactionId=60000000216-806901087161&OrderCode=TDWX1234&PayjinnStatus=Abgebrochen
    www.supplier.com/OnNotify?PayjinnTransactionId=60000000216-806901087161&OrderCode=TDWX1234&PayjinnStatus=Error

For the case 6, PayJinn system will send a redirect to supplier’s success URL message to customer’s browser. Payijnn will add transaction id, supplier order code and transaction result to the end of adress like notification URL redirects. Following parameters are used:

  • PayjinnTransactionId=<TransactionId>
  • OrderCode=<SupplierOrderCode>
    (Only added if supplier sent an order code during NewPayment API call.)
  • PayjinnStatus=OK
  • PayjinnHash=XXXX
  • Example:
    www.supplier.com/OnSuccess?PayjinnTransactionId=60000000216-806901087161&OrderCode=TDWX1234&PayjinnStatus=OK&PayJinnHash=XXXX

Step 10 (@S):
If redirected to success page supplier’s host system should validate the response hash first. (See X. Response Hash Validation) If the hash validation fails, customer should be redirected to an appropriate error page. Afterwards "Query Payment Details API" should be called to get the final transaction details. (i.e: Transaction begin and end times, payee (customer) details, status, etc)

Step 11 (@PJ):
PayJinn system responds back to "Query Payment Details API" request with transaction details.

Step 12 (@S):
Supplier system makes a final check on transaction state, updates its own transaction record using the API response and returns the appropriate web page data to the customer.

Step 13 (@C):
Customer sees final transaction result at his/her browser.

SECURITY REMARK:
Response hash validation and calling "Query Payment Details API" to cross check final transaction state plays an important role on authentication of PayJinn's response. Not doing so will make fraudsters very happy!!!
TRY IT NOW:
You can start a test payment session using this link to get a better idea of PayJinn DirectPay flow.

Clearing Step (Optional - @PJ):
If you grant PayJinn to access your bank account(s) for clearing purposes, then our system will scan transactions at your bank account(s) few times a day to check if payments for your DirectPay and/or Klarna Sofort transactions are received. Result of this process can be seen via transaction reports from dashboard. Additionally, if you specify "wsClientOnPaymentReceivedURL" when creating a transaction via "NewPayment" API, we will also notify your system automatically via HTTP POST. Below parameters will added to the notification message:

  • PayjinnTransactionId=<TransactionId>
  • OrderCode=<SupplierOrderCode>
    (Only added if supplier sent an order code during NewPayment API call.)
  • PayjinnStatus=OK
  • PaymentReceivedDate=YYYYMMDD
  • PayjinnHash=XXXX
  • Example:
    www.supplier.com/OnPaymentReceived?PayjinnTransactionId=60000000216-806901087161&OrderCode=TDWX1234&PayjinnStatus=OK&PayJinnHash=XXXX&PaymentReceivedDate=20200812

Bank Account Management

Before accepting payments you have to define you base bank accounts to which DirectPay end users (customers) will be giving money transfer orders using their online banking information. You can define base accounts using Manage Direct Pay Base Accounts form under API Operations menu at the dashboard.

You can have more than one bank account and initiate payment sessions for which ever account you want. This way you can use your API credentials at different locations or accept payments to different bank accounts for different product categories.

Demo Account

Below client id and api key can be used for development and testing purposes.
  • Client Id: TEST0001
  • API Key: 12345678
Please use the following demo data during your DirectPay session.
  • BLZ: 00000000
  • ID: 12345678
  • PIN: 1234
  • TAN: 123456

Provided that the request data formats are valid, API calls using this demo account will always be approved by the system and synthetic data or results will be returned back to client.

Response Hash Validation

Response Hash is calculated using below algorithm:

Hashed_APIKey = BinaryToHexString(SHA512(ClearAPIKey + ClientId))
ResponseHash = BinaryToHexString(SHA512(ClientId + Hashed_APIKey + SessionCode + ClientOrderCode + PayJinnStatus))

Hash calculation and validation source codes can be found in sample client libraries.

API Specifications

Payjinn Payment Gateway API specifications can be accessed from below URLs:

https://api.payjinn.com/gateway/apiDocs
https://api.payjinn.com/gateway/swagger