API documentations

Deprecated API reference

Heads up! Api versions listed in this page are deprecated, for new integrations please use the new api reference
Heads up! All the interfaces use UTF-8 encoding.

Payment data is sent through a form using POST-method. See the example form below.

action url https://www.paybyway.com/e-payments/pay

Parameters

# Name Required Form Details
1 MERCHANT_ID True Number The sub-merchant ID which is associated with the used private key. The sub-merchant ID is listed in the sub-merchants page in the merchant UI.
2 AMOUNT True Number Amount is in cents e.g. 1€ = 100. Minimum value accepted is 1, 0,01€.
3 CURRENCY True String Only EUR is allowed.
4 ORDER_NUMBER True String The order number shall be unique for every payment and contain only numbers and letters (a-z).
5 LANG True String Language used in during the payment process, allowed values are FI, EN, SV or RU
6 EMAIL False Email This field is optional and can be left out or empty. Optionally provided customer's e-mail address for payment receipt.
7 RETURN_ADDRESS True String User is forwarded to this page after a successful payment. Must be a valid URL e.g. https://test.com?payment=ok
8 CANCEL_ADDRESS True String User is forwarded to this page after a failed payment. Must be a valid URL e.g. https://test.com?payment=failed
9 SELECTED False String

This field is optional and can be left out or empty. Optionally preselected payment methods which will be available for customer.

You can limit the set of available payment methods to allow usage of only defined banks, credit invoice systems or card payments.

If you are not going to add any limitations, just do not use this field or leave it blank.

All payment types should be joined with commas (,) character.

If only one specific payment method is selected, the customer will be directed to the payment providers payment page without displaying Paybyway payment method selection page. Exceptions to this are "BANKS" and "CREDITINVOICES", which are shorthand for displaying payment methods belonging to that category.

The following values are accepted:
  • BANKS - enables all accessible bank payments
  • CREDITCARDS - enables all accessible card payments
  • CREDITINVOICES - enables all accessible credit invoice payments
  • NORDEA, HANDELSBANKEN, OSUUSPANKKI, DANSKEBANK, SPANKKI, SAASTOPANKKI, PAIKALLISOSUUSPANKKI, AKTIA, ALANDSBANKEN, OMASAASTOPANKKI
  • EVERYDAY, JOUSTORAHA - Everyday allows payments between 5.01€ and 2000€, Jousto between 20€ and 2000€
  • EUROLOAN - Euroloan allows payments that are minimum of 10€
  • LASKUYRITYKSELLE - Laskuyritykselle.fi

Example:
NORDEA,HANDELSBANKEN,CREDITCARDS,CREDITINVOICES

10 AUTHCODE True String MAC code for the payment. It is calculated using md5 from the values of the following fields:
  • Sub-merchant private key
  • MERCHANT_ID
  • AMOUNT
  • CURRENCY
  • ORDER_NUMBER
  • LANG
  • RETURN_ADDRESS
  • CANCEL_ADDRESS
  • SELECTED optional
  • EMAIL optional

Fields are joined with '|' character and they, if present, are appended in the specified order. Missing fields are not used in the calculation (no empty fields nor their '|' characters). See the following example where there are missing (SELECTED) and existing (EMAIL) optional fields.

Example:
private_key|67|150|EUR|992|FI|https://test.com/ok|https://test.com/failed|test@maksukaista.fi

Result after MD5-conversion and uppercasing:
C4B3F4F143A0837557BBD349296688C5

Heads up! Authcode must always be in UPPERCASE.

Example form

	

POST-method is used for response data. See the example below.

Return parameters

The following fields are returned to the given return URL after a payment has been made.
# Name Form Details
1 RETURN_CODE Number Return value containing the numeric code for a payment result. 0 means successful, other values are error codes. See the table below.
2 ORDER_NUMBER String Order number from the original payment request.
3 INCIDENT_ID String OPTIONAL: Set only when an error has happened in processing a payment.
4 SETTLED Number

OPTIONAL: Only set when the transaction was successful (RETURN_CODE = 0). Defines whether the transaction was settled (billed from the credit card) or was the card only authorized.

  • 0: Authorized
  • 1: Settled

User can choose whether the transaction should be settled during the initial inputting of credit card details by enabling auto-settlement option from Merchant UI. If auto-settlement is disabled, settlement can be done either manually from Merchant UI or by using the settlement API call. Note that the settlement process is not used in bank payments (bank payments are always settled automatically).

5 AUTHCODE String MAC-code for the response. Calculated using md5 and changing all letters to upper case and following form:
  • Sub-merchant private key
  • RETURN_CODE
  • ORDER_NUMBER
  • SETTLED if set
  • INCIDENT_ID if set

Fields are joined with '|' character.
if INCIDENT_ID or SETTLED is set, it is added to end.

Example:
Private key "private_key", return code 3, order number 15433, and incident id 43ff1:

The fields are joined with '|' characted and AUTHCODE is calculated from the following string:
private_key|3|15433|43ff1

Result after md5-conversion and uppercasing:
7BCA0C7C6BBF73CFA8BF74DEEBD77A7D

Return codes

Return code Explanation
0 Payment completed successfully.
1 Payment failed. Customer did not successfully finish the payment.
2 Duplicate order number. You have reused an order number. Make sure that your order numbers are unique, and are not reused in any case.
3 User disabled. Either your Paybyway account has been temporarily disabled for security reasons, or your sub-merchant is disabled. Visit merchant UI to verify that the sub-merchant is active and that your Paybyway account has not been disabled. If account is disabled, contact support for assistance.
4 Transaction status could not be updated after customer returned from the web page of a bank. Please use the merchant UI to resolve the payment status.
10 Maintenance break. The transaction is not created and the user has been notified and transferred back to the cancel address.

Payment response example in PHP

$private_key = "private_key";

$return_code = $_POST['RETURN_CODE'];
$order_number = $_POST['ORDER_NUMBER'];
$incident_id = isset($_POST['INCIDENT_ID']) ? $_POST['INCIDENT_ID'] : null;
$settled = isset($_POST['SETTLED']) ? $_POST['SETTLED'] : null;
$authcode = $_POST['AUTHCODE'];

$authcode_confirm = $private_key . '|' . $return_code . '|' . $order_number;

if(isset($return_code) && $return_code == 0)
{
	$authcode_confirm .= '|' . $settled;
}
else if(isset($incident_id))
{
	$authcode_confirm .= '|' . $incident_id;
}

$authcode_confirm = strtoupper(md5($authcode_confirm));

if($authcode_confirm == $authcode)
{
	if($order = getOrberByOrderNumber($order_number))
	{
		if(isset($return_code) && $return_code == 0)
		{
			$order->success();
		}
	}
}

Settlement request is done between backend servers through SSL encrypted connection. Settlement request can be sent up to 10 times for each order.

api endpoint https://www.paybyway.com/pbwapi/settle

Parameters

# Name Required Form Details
1 MERCHANT_ID True Number The sub-merchant ID which is associated with the used private key. The sub-merchant ID is listed in the sub-merchants page in the merchant UI.
2 ORDER_NUMBER True String Order number of the payment to be settled.
3 AUTHCODE True String Unique private key of the merchant. There is no need to calculate mac since this query is done between backend servers through SSL encrypted connection.

Curl example in PHP

function settle($url, $ctype, $posts)
{
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_URL, $url);
	curl_setopt($ch, CURLOPT_POST, 1); //method == post
	curl_setopt($ch, CURLOPT_HEADER, 0); //do not return headers
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); //do not print the response right away
	curl_setopt($ch, CURLOPT_HTTPHEADER, array($ctype));
	curl_setopt($ch, CURLOPT_POSTFIELDS, $posts);
	$curl_response = curl_exec ($ch);
	curl_close ($ch);
	return $curl_response;
}

$url = 'https://www.paybyway.com/pbwapi/settle';
$ctype = 'application/json';
$posts = array(
	'MERCHANT_ID' => 1,
	'AUTHCODE' => 'private_key',
	'ORDER_NUMBER' => 'abc123'
);
$settlement = json_decode(settle($url, $ctype, $posts));

if($settlement->RETURN_CODE == 0)
	echo "Settlement successful!";

Response is delivered as a JSON object.

Return parameters

The following fields are returned after the settlement has been done.
# Name Form Details
1 RETURN_CODE Number Return value containing the numeric code for the settlement result. 0 means successful, other values are error codes. See the table below.

Return codes

Return code Explanation
0 Settlement completed successfully.
1 Request failed. Authcode and merchant_id did not match with given order_number, or settlement has been requested more than 10 times for the same transaction.
2 Payment cannot be settled. Either the payment has already been settled or the payment gateway refused to settle payment for given transaction.
3 Invalid request. The settlement request did not contain all the needed fields.