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 below:

Certification process

To activate your Merchant account in Production, we have to certify the correct functionality of the implementation made in the test environment based on the paymentURL that the Merchant(or developer) has declared.

The test is made on this specific Payment URL in order to verify that it is functional. Since the certification is made on this payment URL, then the same payment URL will have to be used in production(if this cannot be done then the same certification will have to also be performed on the production Payment URL)

You will have to necessarily implement below calls:

  1. Add order call (2.D from section Categories and Calls)
  2. Get status call (2.B from section Categories and Calls)

Additionally the following steps will have to be followed:

  1. You will send us via (integration@paybybank.gr):
    • The Payment URL which will be used by us to perform the HTTP POST notification for the payment completion.
    • A test ORDER which has been added by your Merchant account. This ORDER object can be copied from the Playground as this is returned to you after a successful placement of an Order.
  2. We will update the Order status (of the above) from PENDING to PAID so that the attempt to notify you via the HTTP Post call is initiated.
  3. The certification process is completed successfully when PayByBank received a success answer to this call(plain string OK).

Important notice:

You should always check the status of the ORDER that is sent in the HTTP POST. The same paymentURL is used to notify the Merchant in case of rejecting a payment due to payment_code_life expiration with an ORDER status READY_TO_CANCEL (or CANCELLED).

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 below:

Certification process

To activate your Merchant account in Production, we have to certify the correct functionality of the implementation made in the test environment based on the paymentURL that the Merchant(or developer) has declared.

The test is made on this specific Payment URL in order to verify that it is functional. Since the certification is made on this payment URL, then the same payment URL will have to be used in production(if this cannot be done then the same certification will have to also be performed on the production Payment URL)

You will have to necessarily implement below calls:

  1. Add order call (2.D from section Categories and Calls)
  2. Get status call (2.B from section Categories and Calls)

Additionally the following steps will have to be followed:

  1. You will send us via (integration@paybybank.gr):
    • The Payment URL which will be used by us to perform the HTTP POST notification for the payment completion.
    • A test ORDER which has been added by your Merchant account. This ORDER object can be copied from the Playground as this is returned to you after a successful placement of an Order.
  2. We will update the Order status (of the above) from PENDING to PAID so that the attempt to notify you via the HTTP Post call is initiated.
  3. The certification process is completed successfully when PayByBank received a success answer to this call(plain string OK).

Important notice:

You should always check the status of the ORDER that is sent in the HTTP POST. The same paymentURL is used to notify the Merchant in case of rejecting a payment due to payment_code_life expiration with an ORDER status READY_TO_CANCEL (or CANCELLED).

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