Developers

We are available in several ways, every time you need us.

Payment URL Call Simulation

In order to simulate the HTTP POST to the payment URL:
  • Open a Rest Client (Postman, Chrome plugin, Mozilla plugin etc)
  • HTTP Method: POST
  • Headers: Content-type: application/json; charset=utf-8
  • Copy-paste the response of PayByBank API in add order call (an ORDER object σε JSON, please check example below) and change the status from PENDING to PAID (or COMPLETED).
Request Body:

{

“id”: 14559842,

“merchantOrderId”: “thisismytest2”,

“merchantCustomerAssociateId”: “”,

“merchant”: {

“id”: 61,

“name”: “Test Test”,

“apiKey”: “XXXXXXXXXXXXXXXXXXXXX”,

“confirmationURL”: null,

“paymentURL”: “http://test/paymentUrl.jsp“,

“is_active”: 1,

“ins_usr_id”: 0,

“insertDatetime”: 1466061915787,

“updt_usr_id”: 101287,

“updateDatetime”: 1509023570810

},

“amount”: 100,

“omtTransactionBank”: {

“txn_id”: 14559842,

“referReason”: null,

“bankPaymentCode”: “0012101793321”,

“bankName”: null,

“bankAccount”: null,

“bankAccountHolder”: null,

“merchantOrderStatus”: “PAID“,

“merchantPaymentLog”: null

},

“insertDatetime”: 1512719700160,

“updateDatetime”: 1512719700160

}

PayByBank Process Flow

Description of flow:
  • Each time the Merchant is about to place an Order (initial status is PENDING), a call to the path below is required:

/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}&amount={amount}

Details of the call above are found in the API interface (section: APIS/Order Services For merchants).

Without the Check Amount Validation

If in the above call, if the amount parameter is not sent, then a request for a Payment Code without amount validation is recorded in active state and a payment code is retrieved. For this payment code, PayByBank can accept an unlimited number of payments without amount check. In this case for each payment received, PayByBank records an ORDER in PAID status. In case a Merchant does not wish to keep receiving payments for a payment code, then he can deactivate the Payment Code request with the cancel call.

  • When PayByBank is informed by the Bank that the customer has performed the payment for the Order, the system attempts to send a POST HTTP Request(Content-Type: application/json)  to the paymentURL of Merchant.

The body of the above request will contain an Order object along with the details of the Order (the Order object is described in detail in the API interface, section OBJECTS/Order). Valid statuses for a paid Order: (PAID or COMPLETED).

  1. a) Payment Codes with amount validation: If the merchant is notified(*) Order status is changed from PAID to COMPLETED.
  2. b) Payment Codes without amount validation: An ORDER is recorded in PAID status with the amount that was defined in the payment.

*Note:

Order status is changed from PAID to COMPLETED in the following 2 cases:

  • If PayByBank API receives a successful response in the POST call made to the Payment URL. As successful response we only accept a plain string OK
  • If all the retries to notify the Merchant are completed (10 retries, one every 3 minutes) and the Merchant does not receive the notification. In this case the Merchant will have to invoke the GetStatus call ( Categories and Calls) so that they retrieve the final status of the order.
Merchant PaymentURL:

You have to contact us in order to declare the paymentUrl on your account.

Integration Process

In order to be able to integrate your eshop with PayByBank payment method in production environment, you should proceed with all the necessary check points on its implementation by following the steps below:
Step 1:
  • Proceed with the required calls through PayByBank PlayGround.
Step 2:

Certification of your implementation on the specific Payment URL your developer has provided. The process is described in detail in Certification Process (anchor to cerification process)

Step 3:

Once the connection is successfully completed then you will need to update the IPs from which the calls will be made (and where the notification will come from) and confirm that the productive URL is the same (and on the same server) as the test url .

* If case the payment url of the production is different from the test then the certification should be repeated (step 2 above). Optionally, you can set a predefined life time for all your orders.

To proceed with this, you will need to inform us of the life time you wish via email otherwise the system default value (720 hours / 30 days) will be used.

Step 4:

Finally when the above steps have been successfully completed then:

  1. You will need to replace the test domain with the productive URL in order to switch to production. Note: Only the domain (testapi.e-paylink.com) should be replaced while the rest of the URL will remain the same.
  2. You will be enabled in production after you have received the Product API Key.

PayByBank Plugin: If you have used a plug and play plugin to communicate with PayByBank then the Integration team should certify your productive payment url and then proceed to steps 4 & 5 to receive the Product API Key.

Playground

APIS:

Select the category you want and then then the specific call you will see a full description of the API calls as well as the schema of Requests/Responses

At the same time, in the “Playground” section you can to perform test calls and see the API response according to the request sent. The exact same calls will be used by the developer from the code implementation, so the Playground environment can be used as a first confirmation about the correct implementation.

OBJECTS:

In the section “Objects” you have the option to see in one place information regarding the Objects returned by the API calls.

Categories and Calls

  1. Merchant services: Select this category in order to view and use all the services for managing your PayByBank account. In this section, you can see your account information and change your API Key.

Α. Account Information retrieval

Path: /rest/api/v1/merchant/{api_key}

Β. API Key update. If this call is invoked a new API Key will be returned to you while the previous API Key will not be valid any more.

Path: /rest/api/v1/merchant/{api_key}/password

  1. Order services for merchants: Select this category in order to view and use all the services for managing and sending payment orders (Order) or Payment Code Requests.
  1. Retrieval of the Orders of a merchant with the option to choose one payment status. If the status field is not filled, then all the payment requests will be retrieved for the specific merchant. Regarding requests for fixed payments code, only the completed payments will be retrieved for the specific merchant(Completed or Paid). In case of fixed payment codes the fields merchant_order_id and merchant_customer_id will be retrieved only if they have been inserted in the initial call for the fixed payment code retrieval (Place a payment code request call)

Path: /rest/api/v1/order/merchant/{api_key}?status={status}

Β. Retrieval of the merchant Orders with the option to choose one order identification. If the identification field (merchant_order_id) is not filled then all the orders will be retrieved for the specific merchant while additionally the option to provide more than one merchant order ids is given by separating them with a comma character(“,”)(e.g  0001,0002).

Path: /rest/api/v1/order/merchant/{api_key}/{merchant_order_id}

  1. Cancellation of a PENDING Order/ Inactivation of a Payment Code request. Since the inactivation of the payment code is completed the specific Order will have a CANCELLED_BY_MERCHANT status. The call is also valid for payment codes without the amount check validation (call E), in which case the payment code is invalidated (isActivePaymentCode=0)

Path: /rest/api/v1/order/merchant/cancel/{api_key}}/{merchant_order_id}

  1. Place a payment code request

With Amount Check Validation (in pending status)

After the placement of a request the Order object you will receive will be in Pending status. After the payment of the order via the Bank (see PayByBank Process Flow)

Path: /rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}&amount={amount}

 

Without Amount Check Validation (in active state)

If no amount is registered in the request (field Amount) then a payment code request is registered without the amount check validation. With this payment code you can have multiple payments. In this case you have the option to submit or leave blank the merchant_order_id field since this payment code may be used to serve multiple orders. In case you are using one payment code per merchant then you will be able to receive notifications for each payment received by the merchant. On the contrary this fixed payment code may not be applicable for distribution over multiple merchants since you will not be able to distinguish between the payments coming from different merchants.

Path:

/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}

For each service, you will find in detail:

  1. Path: the service path you should use in order to call a service
  2. Method: the type of HTTP method used to call a service (Get, Post, Put)
  3. Path Parameters: the path parameters you should add when calling a service. These parameters are passed on the request url.
  4. Query Parameters: the query parameters you should add when calling a service. These parameters are also passed on the call url (like for example in the case of call A. where status is a query parameter: /rest/api/v1/order/merchant/0000-1111-2222-3333-4444?status=PAID)
  5. Response Object: the response object you will receive when calling a service
  6. Errors: The error responses you will possibly receive when calling a service

Supported eCommerce Plugins

Woocommerce

Supported versions 3.x

Prestashop

Supported versions 1.7.x

Cs-Cart

Supported versions 3.x – 4.x

Payment URL Call Simulation

In order to simulate the HTTP POST to the payment URL:
  • Open a Rest Client (Postman, Chrome plugin, Mozilla plugin etc)
  • HTTP Method: POST
  • Headers: Content-type: application/json; charset=utf-8
  • Copy-paste the response of PayByBank API in add order call (an ORDER object σε JSON, please check example below) and change the status from PENDING to PAID (or COMPLETED).
Request Body:

{

“id”: 14559842,

“merchantOrderId”: “thisismytest2”,

“merchantCustomerAssociateId”: “”,

“merchant”: {

“id”: 61,

“name”: “Test Test”,

“apiKey”: “XXXXXXXXXXXXXXXXXXXXX”,

“confirmationURL”: null,

“paymentURL”: “http://test/paymentUrl.jsp“,

“is_active”: 1,

“ins_usr_id”: 0,

“insertDatetime”: 1466061915787,

“updt_usr_id”: 101287,

“updateDatetime”: 1509023570810

},

“amount”: 100,

“omtTransactionBank”: {

“txn_id”: 14559842,

“referReason”: null,

“bankPaymentCode”: “0012101793321”,

“bankName”: null,

“bankAccount”: null,

“bankAccountHolder”: null,

“merchantOrderStatus”: “PAID“,

“merchantPaymentLog”: null

},

“insertDatetime”: 1512719700160,

“updateDatetime”: 1512719700160

}

PayByBank Process Flow

Description of flow:
  • Each time the Merchant is about to place an Order (initial status is PENDING), a call to the path below is required:

/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}&amount={amount}

Details of the call above are found in the API interface (section: APIS/Order Services For merchants).

Without the Check Amount Validation

If in the above call, if the amount parameter is not sent, then a request for a Payment Code without amount validation is recorded in active state and a payment code is retrieved. For this payment code, PayByBank can accept an unlimited number of payments without amount check. In this case for each payment received, PayByBank records an ORDER in PAID status. In case a Merchant does not wish to keep receiving payments for a payment code, then he can deactivate the Payment Code request with the cancel call.

  • When PayByBank is informed by the Bank that the customer has performed the payment for the Order, the system attempts to send a POST HTTP Request(Content-Type: application/json)  to the paymentURL of Merchant.

The body of the above request will contain an Order object along with the details of the Order (the Order object is described in detail in the API interface, section OBJECTS/Order). Valid statuses for a paid Order: (PAID or COMPLETED).

  1. a) Payment Codes with amount validation: If the merchant is notified(*) Order status is changed from PAID to COMPLETED.
  2. b) Payment Codes without amount validation: An ORDER is recorded in PAID status with the amount that was defined in the payment.

*Note:

Order status is changed from PAID to COMPLETED in the following 2 cases:

  • If PayByBank API receives a successful response in the POST call made to the Payment URL. As successful response we only accept a plain string OK
  • If all the retries to notify the Merchant are completed (10 retries, one every 3 minutes) and the Merchant does not receive the notification. In this case the Merchant will have to invoke the GetStatus call ( Categories and Calls) so that they retrieve the final status of the order.
Merchant PaymentURL:

You have to contact us in order to declare the paymentUrl on your account.

Integration Process

In order to be able to integrate your eshop with PayByBank payment method in production environment, you should proceed with all the necessary check points on its implementation by following the steps below:
Step 1:
  • Proceed with the required calls through PayByBank PlayGround.
Step 2:

Certification of your implementation on the specific Payment URL your developer has provided. The process is described in detail in Certification Process (anchor to cerification process)

Step 3:

Once the connection is successfully completed then you will need to update the IPs from which the calls will be made (and where the notification will come from) and confirm that the productive URL is the same (and on the same server) as the test url .

* If case the payment url of the production is different from the test then the certification should be repeated (step 2 above). Optionally, you can set a predefined life time for all your orders.

To proceed with this, you will need to inform us of the life time you wish via email otherwise the system default value (720 hours / 30 days) will be used.

Step 4:

Finally when the above steps have been successfully completed then:

  1. You will need to replace the test domain with the productive URL in order to switch to production. Note: Only the domain (testapi.e-paylink.com) should be replaced while the rest of the URL will remain the same.
  2. You will be enabled in production after you have received the Product API Key.

PayByBank Plugin: If you have used a plug and play plugin to communicate with PayByBank then the Integration team should certify your productive payment url and then proceed to steps 4 & 5 to receive the Product API Key.

Playground

APIS:

Select the category you want and then then the specific call you will see a full description of the API calls as well as the schema of Requests/Responses

At the same time, in the “Playground” section you can to perform test calls and see the API response according to the request sent. The exact same calls will be used by the developer from the code implementation, so the Playground environment can be used as a first confirmation about the correct implementation.

OBJECTS:

In the section “Objects” you have the option to see in one place information regarding the Objects returned by the API calls.

Categories and Calls

  1. Merchant services: Select this category in order to view and use all the services for managing your PayByBank account. In this section, you can see your account information and change your API Key.

Α. Account Information retrieval

Path: /rest/api/v1/merchant/{api_key}

Β. API Key update. If this call is invoked a new API Key will be returned to you while the previous API Key will not be valid any more.

Path: /rest/api/v1/merchant/{api_key}/password

  1. Order services for merchants: Select this category in order to view and use all the services for managing and sending payment orders (Order) or Payment Code Requests.
  1. Retrieval of the Orders of a merchant with the option to choose one payment status. If the status field is not filled, then all the payment requests will be retrieved for the specific merchant. Regarding requests for fixed payments code, only the completed payments will be retrieved for the specific merchant(Completed or Paid). In case of fixed payment codes the fields merchant_order_id and merchant_customer_id will be retrieved only if they have been inserted in the initial call for the fixed payment code retrieval (Place a payment code request call)

Path: /rest/api/v1/order/merchant/{api_key}?status={status}

Β. Retrieval of the merchant Orders with the option to choose one order identification. If the identification field (merchant_order_id) is not filled then all the orders will be retrieved for the specific merchant while additionally the option to provide more than one merchant order ids is given by separating them with a comma character(“,”)(e.g  0001,0002).

Path: /rest/api/v1/order/merchant/{api_key}/{merchant_order_id}

  1. Cancellation of a PENDING Order/ Inactivation of a Payment Code request. Since the inactivation of the payment code is completed the specific Order will have a CANCELLED_BY_MERCHANT status. The call is also valid for payment codes without the amount check validation (call E), in which case the payment code is invalidated (isActivePaymentCode=0)

Path: /rest/api/v1/order/merchant/cancel/{api_key}}/{merchant_order_id}

  1. Place a payment code request

With Amount Check Validation (in pending status)

After the placement of a request the Order object you will receive will be in Pending status. After the payment of the order via the Bank (see PayByBank Process Flow)

Path: /rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}&amount={amount}

 

Without Amount Check Validation (in active state)

If no amount is registered in the request (field Amount) then a payment code request is registered without the amount check validation. With this payment code you can have multiple payments. In this case you have the option to submit or leave blank the merchant_order_id field since this payment code may be used to serve multiple orders. In case you are using one payment code per merchant then you will be able to receive notifications for each payment received by the merchant. On the contrary this fixed payment code may not be applicable for distribution over multiple merchants since you will not be able to distinguish between the payments coming from different merchants.

Path:

/rest/api/v1/order/merchant/{api_key}?merchant_order_id={merchant_order_id}&merchant_customer_id={merchant_customer_id}

For each service, you will find in detail:

  1. Path: the service path you should use in order to call a service
  2. Method: the type of HTTP method used to call a service (Get, Post, Put)
  3. Path Parameters: the path parameters you should add when calling a service. These parameters are passed on the request url.
  4. Query Parameters: the query parameters you should add when calling a service. These parameters are also passed on the call url (like for example in the case of call A. where status is a query parameter: /rest/api/v1/order/merchant/0000-1111-2222-3333-4444?status=PAID)
  5. Response Object: the response object you will receive when calling a service
  6. Errors: The error responses you will possibly receive when calling a service

Supported eCommerce Plugins

Woocommerce

Supported versions 3.x

Prestashop

Supported versions 1.7.x

Cs-Cart

Supported versions 3.x – 4.x