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 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=20181218

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.

Base URL

All PayJinn DirectPay API URLs have the following base:

https://www.payjinn.com/api/HostedPayments

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

Generate a DirectPay and/or an External Payment Session

This API is used to create a new DirectPay session. DirectPay will allow your clients to make SEPA money transfer to your bank account. Same API can also be used for generating External Payment session for client's who are registered for PayJinn's multi payment solution.

Accepts:

HTTP POST

API URL:

https://www.payjinn.com/api/HostedPayments/NewPayment

Inputs:

Field Name

Type

Length

Info

wsClientId

String

8

Mandatory

wsClientOrderCode

String

Max 128

Optional

wsTransferAmount

Decimal

-

Mandatory

Default currency is EURO.

Use 2 decimal places (i.e: 1.25)

wsCurrency

String

3

Optional

EUR: EURO

wsClientNotificationURL

String

Max 256

Optional but recommended

wsClientSuccessURL

String

Max 256

Optional but recommended

wsClientOnPaymentReceivedURL

String

Max 256

Optional

Only available for DirectPay and Klarna Sofort

wsBaseAccountIBAN

String

Max 22

Optional

wsLanguageCode

String

5

Optional

de_DE: German (Default Value)

en_US: American English

wsPaymentCode

String

25

Optional

Used for generating an External Payment session with a particular payment method.

Possible values are as follows:

  • VISA
  • MASTERCARD
  • MAESTRO
  • AMEX
  • IDEAL
  • PAYPAL
  • SOFORT
  • GIROPAY
  • SEPADIRECTDEBIT
  • PAYJINN

Contact PayJinn Support if you want to accept other payment methods through us.

wsTransactionCode

Integer

0

Optional

0: Sales

1: Preauthorization


REMARK 1:

If wsTransactionCode is not set, 0: Sales will be used as default value.

REMARK 2:

wsTransactionCode = 1 can only be used for following wsPaymentCodes.

  • VISA
  • MASTERCARD
  • MAESTRO
  • AMEX

 

Outputs:

Field Name

Type

Length

Info

paymentURL

String

Max 256

Mandatory

transactionId

String

24

Mandatory

a.k.a: SessionCode


Examples:

Query Payment Details

This API can be used to query details of a particular DirectPay and/or External Payment session.

Accepts:

HTTP GET

API URL:

https://www.payjinn.com/api/HostedPayments/{ClientId}/{TransactionId}

Example URL:

https://www.payjinn.com/api/HostedPayments/KND00001/60000000216-806901087161

Outputs:

Field Name

Type

Length

Info

wsSessionCode

String

24

Mandatory

wsClientId

String

8

Mandatory

wsSessionType

String

16

Mandatory

wsProviderCode

String

16

Mandatory

wsPaymentCode

String

16

Mandatory

wsBeginDate

String

8

Mandatory

YYYYMMDD

wsBeginTime

String

6

Mandatory

HHMMSS

wsEndDate

String

8

Mandatory

YYYYMMDD

wsEndTime

String

6

Mandatory

HHMMSS

wsClientOrderCode

String

Max 128

Mandatory

wsTransferAmount

String

Max 50

Mandatory

i.e: 999.70 EUR

wsBaseAccountHolderName

String

Max 128

Mandatory

wsBaseCountryCode

String

2

Mandatory

wsBaseBLZ

String

8

Mandatory

wsBaseBIC

String

11

Mandatory

wsBaseIBAN

String

Max 22

Mandatory

wsSenderAccountHolderName

String

Max 128

Mandatory

wsSenderCountryCode

String

2

Mandatory

wsSenderBLZ

String

8

Mandatory

wsSenderBIC

String

11

Mandatory

wsSenderIBAN

String

Max 22

Mandatory

wsTransactionState

Boolean

-

Mandatory

i.e: true / false

wsTranResult

String

Max 128

Mandatory

wsProviderCode

String

Max 16

Mandatory

wsPaymentCode

String

Max 16

Mandatory

wsTranResultInfo

String

Max 512

Mandatory

wsPostAuthDate

String

8

Mandatory

YYYYMMDD

wsPostAuthTime

String

6

Mandatory

HHMMSS

wsVoidDate

String

8

Mandatory

YYYYMMDD

wsVoidTime

String

6

Mandatory

HHMMSS

wsLastRefundDate

String

8

Mandatory

YYYYMMDD

wsLastRefundTime

String

6

Mandatory

HHMMSS

wsRefundCount

Integer

-

Mandatory

wsRefundSum

String

Max 50

Mandatory

i.e: 10.50 EUR

wsOrgSessionCode

String

Max 24

Mandatory

wsPaymentReceived

Boolean

-

Mandatory

i.e: true/false

wsPaymentReceiveDate

String

8

Mandatory

YYYYMMDD

wsPaymentReceiveTime

String

6

Mandatory

HHMMSS


Examples:

Transaction Advice

This API is used for canceling a transaction or to finalize a pending preauthorization.

Accepts:

HTTP POST

API URL:

https://www.payjinn.com/api/HostedPayments/Advice

Inputs:

Field Name

Type

Length

Info

wsClientId

String

8

Mandatory

wsTransferAmount

Decimal

-

Mandatory

Default currency is EURO.

Use 2 decimal places (i.e: 1.25)

wsCurrency

String

3

Optional

EUR: EURO

wsSessionCode

String

Max 24

Mandatory

wsTransactionCode

Integer

-

Optional

0: Sales

1: Preauthorization

 

Outputs:

Field Name

Type

Length

Info

wsSessionCode

String

Max 24

Mandatory

Echoed

wsResult

Boolean

-

Mandatory

i.e: true / false

wsMessage

String

Max 256

Mandatory

wsTransactionCode

Integer

-

Mandatory

Echoed

Refund

This API is used to refund an existing transaction. Partial or full refund is available. For partial amounts multiple refund requests can be sent for a single sales transaction.

Accepts:

HTTP POST

API URL:

https://www.payjinn.com/api/HostedPayments/Refund

Inputs:

Field Name

Type

Length

Info

wsClientId

String

8

Mandatory

wsRefundAmount

Decimal

-

Mandatory

Default currency is EURO.

Use 2 decimal places (i.e: 1.25)

wsCurrency

String

3

Optional

EUR: EURO

wsOrgSessionCode

String

Max 24

Mandatory

 

Outputs:

Field Name

Type

Length

Info

wsSessionCode

String

Max 24

Mandatory

Individual session code of the refund record at the PayJinn system.

wsOrgSessionCode

String

Max 24

Mandatory

Echoed

wsRefundAmount

Decimal

-

Mandatory

Echoed

wsCurrency

String

3

Mandatory

Echoed

wsResult

Boolean

-

Mandatory

i.e: true / false

wsMessage

String

Max 256

Mandatory

Payment Options Request

This API can be used to fetch avaiable payment options and commissions for a particular amount.

Accepts:

HTTP POST

API URL:

https://www.payjinn.com/api/HostedPayments/PaymentOptions

Inputs:

Field Name

Type

Length

Info

poClientId

String

8

Mandatory

poAmount

Decimal

-

Mandatory

Default currency is EURO.

Use 2 decimal places (i.e: 1.25)

poCurrency

String

3

Optional

EUR: EURO

poCountryCode

String

2

Optional.

DE: Germany

poCity

String

Max 128

Optional

poAgencyCode

String

Max 128

Mandatory

 

Outputs:

Field Name

Type

Length

Info

options

Array of Payment Option

Any

Mandatory


Payment Option Format:

Field Name

Type

Length

Info

poPaymentCode

String

Max 16

Mandatory

i.e: PAYJINN, MASTERCARD, etc

poPaymentName

String

Max 25

Mandatory

i.e: PAYJINN, MASTERCARD, etc

poCurrency

String

3

Mandatory

EUR: EURO

poOriginalAmount

Decimal

-

Mandatory

i.e: 1000.00

poCommissionAmount

Decimal

-

Mandatory

i.e: 10.00

poTotalAmount

Decimal

-

Mandatory

i.e: 1020.00

poCommissionRate

Decimal

-

Mandatory

i.e: 1.00

poFixedCommissionAmount

Decimal

-

Mandatory

i.e: 10.00


Examples:

Sample Client Libraries

This document describes the PayJinn DirectPay API on the HTTP protocol level. If you would simply like to integrate PayJinn DirectPay infrastructure in to your application, we provide sample API clients for .Net and Java environments. Full source codes of these libraries and demo applications can be downloaded from our GitHub repositories.

If you need additional support during integration process, please do not hesitate to contact us from support <at> payjinn.com email address.

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.