3. Definitions

Throughout this document, the following definitions are used:

• Acquirer – (also known as an ‘Acquiring Bank’) refers to a financial institution that processes card payments from a particular Card Scheme on behalf of a Merchant.
  

• Alternative Payment Method (APM) – refers to a collective term used to designate any type of payment method that falls outside the scope of Card Payments. This typically includes the following types of payment methods: Offline Credit Transfers, Direct Debits, E-Wallets, Vouchers, Carrier-Billing Mobile Payments, and Crypto Payments.
  

• Application Programming Interface (API) – refers to a computer interface that allows different applications to communicate with one another, access and share data.
  

• Card Scheme – (also known as ‘Card Association’) refers to a payment network linked to payment cards. Examples of Card Schemes include: Visa, Mastercard, American Express, UnionPay, etc.
  

• Integration – refers to a term used to describe the processes and activities needed to connect two separate technological systems to each other so they can communicate with one another, access and share data.
  

• Issuer – (also known as ‘Issuing Bank’) refers to a financial institution that issues Card Scheme branded payment cards such as credit cards, debit cards and prepaid cards directly to consumers.
  

• Merchant – refers to any entity (store, restaurant, etc.) that accepts payments in exchange for providing a customer with goods and/or services.
  

• Merchant Account – refers to an account with a Payment Services Provider (PSP) that enables a business to accept payments in a variety of methods from its customers. A Merchant Account is typically payment method specific (meaning that it supports particular payment types and not others).
  

• Merchant Category Code (MCC) – refers to a four-digit number listed in ISO 18245 which is used to classify a business by the type(s) of goods and/or services it provides.

4. Transaction Types

Currently, Paragon supports the following transaction types:

5. Card Payments

The following section covers the transaction types related to payments made via payment cards (debit/credit/charge).

5.1 Pre-Authorisation (PA)

Pre-Authorisation (sometimes referred to as authorisation) is a transaction type that places a ‘hold’ on a cardholder’s card balance for a specific amount in anticipation of a future sale. Merchants commonly use this transaction type (instead of the standard Sale transaction type) when there is more than several hours gap between taking the order and being able to fulfill it (due to logistical or regulatory reasons). In addition, this transaction type is also routinely used in the hospitality industry in cases a charge is not certain (e.g., as a security deposit for the room, etc.).

A successful Pre-Authorisation guarantees for the merchant access to the cardholder’s balance up to the pre-authorised amount, however the merchant must process a Capture (CP) transaction to actually ‘collect’ the funds from the cardholder. It is important to note that the Pre-Authorisation amount remains guaranteed for the merchant for a limited time. This is usually a maximum of 7 days for debit cards and 28 days for credit cards although this could change depending on the card type and issuer as well as the merchant’s MCC.

Paragon supports performing Pre-Authorisation (PA) transactions via the following workflows:

5.1.1 Payment Page Pre-Authorisation Flow

The Payment Page Pre-Authorisation Flow relies on a Paragon hosted payment page and is primarily intended for merchants who do not have their own payment page (either for PCI DSS reasons or for convenience).

5.1.1.1 Payment Page Pre-Authorisation API URL

Payment Page Pre-Authorisation Flow transactions are initiated by sending a POST request to the following URL: https://channel.paragon.online/v2/preauth-form/ENDPOINTID

5.1.1.2 Payment Page Pre-Authorisation Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

5.1.1.3 Payment Page Pre-Authorisation Response Parameters

Preauth Response Example:

type=async-response
&by-request-sn=00000000-0000-0000-0000-000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821

5.1.1.4 Payment Page Customisation (Optional)

For merchants wishing to exercise more control over how the payment looks, Paragon can support hosting a custom-made HTML payment page created by the merchant. Any merchant-created payment page would need to be approved by Fibonatix’s Risk department and contain the following input fields:

5.1.2 Server-to-Server Pre-Authorisation Flow

The Server-to-Server Pre-Authorisation Flow is primarily intended for merchants who have their own payment page which is used to send the payment data to Paragon.

5.1.2.1 Server-to-Server Pre-Authorisation API URL

Server-to-Server Pre-Authorisation Flow transactions are initiated by sending a POST request to the following URL: https://channel.paragon.online/v1/preauth/ENDPOINTID

5.1.2.2 Server-to-Server Pre-Authorisation Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

5.1.2.3 Server-to-Server Pre-Authorisation Response Parameters

5.1.2.4 Server-to-Server Pre-Authorisation 3DS Authentication Variant

For 3D Secure transactions, the merchant is required to use the Order Status API (described in section 8.2 of this document) to poll the transaction status and retrieve the HTML value provided in the HTML field. The merchant must then use the HTML value to redirect the customer to the 3D Secure authentication page.

5.2 Capture (CP)

Capture (CP) is a transaction type that forms the second step in a ‘Pre-Authorisation/Capture’ operational model (also known as a PA/CP model). With the Capture transaction, the merchant, is using the original Approval Code obtained from the Pre-Authorisation transaction to process the actual amount of the sale. A Capture transaction cannot exceed the Pre-Authorisation amount however can be for a lower amount. In addition, it is also possible to perform multiple Captures on the same Pre-Authorisation transaction as long as the total sum of the Captures doesn’t exceed the Pre-Authorisation amount. Paragon supports performing Capture (CP) type transactions manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

5.2.1 Capture API URL

Capture transactions are initiated by sending a POST request to the following URL: https://channel.paragon.online/v1/capture/ENDPOINTID

5.2.2 Capture Request Parameters

¹. If the amount parameter contains no value, the capture will be performed on the full Pre-Authorisation amount!
². Details on how to create the control parameter are outlined in section 10.1

5.2.3 Capture Response Parameters

Capture Response Example:

type=async-response
&paynet-order-id=6666821
&merchant-order-id=902B4FF5
&by-request-sn=00000000-0000-0000-0000-000002d53397

5.3 Void (VD)

A Void (VD), sometimes referred to as an ‘Authorisation Reversal’, is a transaction type designed to cancel a pre-authorisation type transaction. As such, a void transaction can only be performed when the payment transaction has only gone through the authorisation process but has not yet been captured. Since the Void transaction is a cancellation of another transaction (the pre-authorisation), from the point of view of the cardholder it is as though both never happened, and they will typically see no indication of either on their card statement. Please note that a Void is always performed for the full amount of the pre-authorisation and it is not possible to process partial and/or multiple voids! Paragon supports performing Void (VD) transactions manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

5.3.1 Void API URL

API URL Void transactions are initiated by sending a POST request to the following URL: https://channel.paragon.online/v1/void/ENDPOINTID

5.3.2 Void Request Parameters

¹. If the amount parameter contains no value, the capture will be performed on the full Pre-Authorisation amount!
². Details on how to create the control parameter are outlined in section 10.1

5.3.3 Void Response Parameters

5.4 Sale (SL)

Sale is the most commonly used transaction type and can be seen as a pre-authorisation and capture transactions merged into a single transaction type.
Paragon supports performing Sale (SL) transactions via the following API workflows:

5.4.1 Payment Page Sale Flow

The Payment Page Sale Flow relies on a Paragon hosted payment page and is primarily intended for merchants who do not have their own payment page (either for PCI DSS reasons or for convenience).

5.4.1.1 Payment Page Sale API URL

Payment Page Sale Flow transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/sale-form/ENDPOINTID

5.4.1.2 Payment Page Sale Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

5.4.1.3 Payment Page Sale Response Parameters

5.4.1.4 Payment Page Customisation (Optional)

For merchants wishing to exercise more control over how the payment looks, Paragon can support hosting a custom-made HTML payment page created by the merchant. Any merchant-created payment page would need to be approved by Fibonatix’s Risk department and contain the following input fields:

5.4.2 Server-to-Server Sale Flow

The Server-to-Server Sale Flow is primarily intended for merchants who have their own payment page which is used to send the payment data to Paragon.

5.4.2.1 Server-to-Server Sale API URL

Server-to-Server Sale Flow transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v1/payment/ENDPOINTID

5.4.2.2 Server-to-Server Sale Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

5.4.2.3 Server-to-Server Sale Response Parameters

5.4.2.4 Server-to-Server Sale 3DS Authentication Variant

For 3D Secure transactions, the merchant is required to use the Order Status API (described in section 8.2 of this document) to poll the transaction status and retrieve the HTML value provided in the HTML field. The merchant must then use the HTML value to redirect the customer to the 3D Secure authentication page.

5.5 Rebill (RB)

A Rebill (RB) is a transaction type that allows a merchant (or a customer via the merchant’s website/portal) to perform a purchase without entering their card details, but instead to charge the customer’s card details stored with Fibonatix. Rebill transactions are commonly used by merchants for processing recurring payments as well as for allowing easier checkout for repeat customers.

Please note that a Rebill can only be performed on a previously successful Sale (SL) or Capture (CP) transactions!

Paragon supports performing Rebill (RB) transactions manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

Please note that for a Rebill you will need to follow a few steps: 1. Process a successful Sale or Capture Transaction. 2. Generate a Token, see section 7. 3. Make sure to add the following key and value, in the headers tab:
Key: control-key
Value: The generated SHA-1 from the following details- ENDPOIND_ID+Login+Merchant_Control (for help creating the SHA-1, see Section 11)

5.5.1 Rebill API URL

Rebill transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/rebill/ENDPOINTID

Make sure to send the request with the parameters in the “Body” Tab, under “RAW” using JSON. See example:

Rebill Request Example: java { "client_orderid": "101", "payment_token": "691418ae-3e8a-4fbc-b4fb-8a94c124fafb", "order_desc": "Tasty Test", "amount": "39.00", "currency": "EUR", "ipaddress": "10.10.10.1", "site_url": "www.google.com", "purpose": "Testing Tasty Tests", "redirect_url": "http%3a%2f%2fdoc.fibonatix.com%2fdoc%2fdummy.htm", "server_callback_url": "https://whereeveryouwouldliketo.callbacks.justchoose", "cell_phone": "3636363636" }

5.5.2 Rebill Request Parameters

Parameter	Length/Type	Description	Stipulation
client_orderid	48/String	Brand/Merchant’s Transaction ID	Mandatory
order_desc	256/String	Brand/Merchant’s Transaction Description	Conditional
payment_token	36/String	The Token created in the original transaction	Mandatory
amount	10/Numeric	Transaction Amount (i.e., 10.5 = £10.5)¹	Optional
currency	3/String	Transaction Currency (per ISO 4217)	Mandatory
cvv2	3-4/Numeric	The Customer’s credit/debit card security code	Conditional
ipaddress	48/String	Customer’s IP address	Mandatory

¹ If no amount is stated, the Rebill will be for the full sum of the original Transaction.

5.5.3 Rebill Response Parameters

Rebill Request Response Example:

type=async-response
&paynet-order-id=INI30VnZ
&merchant-order-id=9229e21d-33b1-4e66-9d3a-1bbd8ee11c53
&serial-number=AkHfpKeO

5.6 Refund (RF)

A Refund (RF) is a transaction type designed to return customer funds that have already been captured. Unlike a Void transaction, a Refund is considered as a ‘second transaction’ (to the sale) and will appear on the customer’s card statement. It is possible to do multiple refunds on a transaction, but the sum of the refunded amounts must be equal to or less than the amount of the original Sale/Capture amount.

Paragon supports performing Refund (RF) transactions manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

5.6.1 Refund API URL

Refund transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v1/refund/ENDPOINTID

5.6.2 Refund Request Parameters

¹. If the amount parameter contains no value, the refund will be performed on the full Pre-Authorisation amount!
². Details on how to create the control parameter are outlined in section 10.1

5.6.3 Refund Response Parameters

Refund Response Example:

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

5.7 Payout (PO)

A Payout (PO) is a transaction type based on the Visa Original Credit Transfer (OCT) or Mastercard MoneySend protocols that allows a merchant to send funds from their Merchant Account balance to a customer’s credit/debit card. Unlike a Refund (RF), the amount the merchant can send to a customer’s card with a Payout transaction is irrespective of the original payment amount. Payout (PO) transactions are commonly used by merchants when the amount that needs to be returned to a customer exceeds the original transaction amount (e.g., gambling merchants, or cases in which the customer paid an initial deposit by credit/debit card and the rest via a different payment method).

Paragon supports performing Payout (PO) transactions manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

5.7.1 Payout API URL

Payout transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/payout/ENDPOINTID

5.7.2 Payout Request Parameters

¹. If the amount parameter contains no value, the refund will be performed on the full Pre-Authorisation amount!
². Details on how to create the control parameter are outlined in section 10.1

5.7.3 Payout Response Parameters

6. Recurring Payments

Recurring Payments (also known as subscription payments, automatic payments, or recurring billing) is a term referring to transactions that are charged repeatedly on a prearranged schedule (daily/weekly/monthly). Recurring Payments are commonly used by merchants for subscription services (e.g., gym membership) as well as for other forms of periodic billing (e.g., household bills, car loans, mortgage, rent, insurance, etc.). In addition, the Recurring Payments functionality can be used for instalment payments to make it easier for customers to pay for a higher ticket item over a period of time.

Paragon supports Recurring Payments via the following workflow:

6.1 Recurring Initialisation (RI)

A Recurring Payments contract must begin with a Recurring Initialisation (RI) transaction. This transaction type contains all the data needed to establish the Recurring Payments contract and set it in motion. Recurring Initialisation transactions are performed via one of the following API workflows:

6.1.1 Payment Page Recurring Initialisation Flow

The Payment Page Recurring Initialisation Flow relies on a Paragon hosted payment page and is primarily intended for merchants who do not have their own payment page (either for PCI DSS reasons or for convenience).

6.1.1.1 Payment Page Recurring Initialisation API URL

Payment Page Recurring Initialisation Flow transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/initRecurring-form/ENDPOINTID

6.1.1.2 Payment Page Recurring Initialisation Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

Recurring Initialisation-Form Request Parameters

Init Recurring Request Parameters Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&card_printed_name=CARD HOLDER
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
&first_payment_date=30.10.20
&recurring_date_type=day
&time_interval= 3
&number_of_payments= 3

6.1.1.3 Payment Page Recurring Initialisation Response Parameters

6.1.1.4 Payment Page Customisation (Optional)

For merchants wishing to exercise more control over how the payment looks, Paragon can support hosting a custom-made HTML payment page created by the merchant. Any merchant-created payment page would need to be approved by Fibonatix’s Risk department and contain the following input fields:

6.1.2 Server-to-Server Recurring Initialisation Flow

The Server-to-Server Recurring Initialisation Flow is primarily intended for merchants who have their own payment page which is used to send the payment data to Paragon.

6.1.2.1 Server-to-Server Recurring Initialisation API URL

Server-to-Server Sale Flow transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/init-recurring/ENDPOINTID

6.1.2.2 Server-to-Server Recurring Initialisation Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

6.1.2.3 Server-to-Server Recurring Initialisation Response Parameters

6.1.2.4 Server-to-Server Recurring Initialisation 3DS Authentication Variant

For 3D Secure transactions, the merchant is required to use the Order Status API (described in section 8.2 of this document) to poll the transaction status and retrieve the HTML value provided in the HTML field. The merchant must then use the HTML value to redirect the customer to the 3D Secure authentication page.

6.2 Recurring Payment (RC)

Recurring Payment (RC) is a transaction type denoting a transaction that is a part of the Recurring Payments cycle. Recurring Payment transactions are performed automatically via the Paragon system in accordance with the factors set by the Recurring Initialisation transaction and cannot be performed in any other means (i.e., manually via the back-office or via API).

6.2.1 Recurring Payment API URL

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v2/recurring/ENDPOINTID

6.2.2 Recurring Payment API URL Response

6.3 Recurring Modification (MR)

Recurring Modification (MR) is a transaction type used by merchants to change any (or all) of the previously defined factors for a Recurring Payments Cycle (e.g., the card details, the amount, the charging date, etc.).

6.3.1 Recurring Modification API URL

Recurring Modification transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/modify-recurring/ENDPOINTID

6.3.2 Recurring Modification Request Parameters

¹. Parameter value must be from the options contained in 9.2
². Parameter value must be from the options contained in 9.1
³. Details on how to create the control parameter are outlined in section 10.1

6.3.3 Recurring Modification Response Parameters

6.4 Recurring Cancellation (CR)

Recurring Cancellation (CR) is a transaction type used by merchants to cancel a Recurring Payments contract.

6.4.1 Recurring Cancellation API URL

Recurring Cancellation transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/cancel-recurring/

6.4.2 Recurring Cancellation Request Parameters

6.4.3 Recurring Cancellation Response Parameters

6.4.4 Recurring Status Request Parameters

Recurring Status Requests are initiated by sending a POST request to the following URL:

https://channel.paragon.online/v1/recurring-status/{endpoint}

¹. Details on how to create the control parameter are outlined in section 10.1

6.5 Duplicate Recurring transactions

This feature allows for the duplication of a Recurring Transaction.

6.5.1 Duplicate Recurring transaction API URL

This request will duplicate an existing Recurring Transaction, just by sendin a POST request to the following URL:

https://channel.paragon.online/v2/duplicate-recurring-form/{endpoint}

6.5.2 Duplicate Recurring transaction Request Parameters

¹. Details on how to create the control parameter are outlined in section 10.1

6.5.3 Duplicate Recurring transaction Response Parameters

7. Tokenisation Services

Tokenisation in the context of payments refers to the process of replacing the full card number (PAN) with a unique string of numbers. The purpose of Tokenisation is primarily as a security measure, since the PAN is not transmitted during the transaction there is less likelihood of it being compromised by a security breach on the merchant’s side. In addition, the use of Tokenisation services also offers merchants and their customers the benefit of using certain convenience features such as 1-click purchasing or storing a card for faster checkout which require Tokenisation in order to be able to work.

In Paragon, Tokenisation is a mandatory prerequisite in order to be able to support certain transactional workflows such as Recurring Payments and Rebills.

7.1 Create Token (TK)

A Create Token (TK) transaction enables a Merchant to store a customer’s details (including payment data) securely within Paragon. The system will then provide a token for the saved information which can be used later by the merchant to complete payment transactions (e.g., for recurring transactions), improve the checkout experience for a returning customer, etc.

Paragon supports Creating a Token manually through the Quick Actions button in the back-office user interface or via API using the following workflow:

7.1.1 Create Token API URL

Create Token transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/token/create-fromsn/{serial_number}

8. Callbacks & Status Requests

The following section contains the operations that merchants can use to pull transaction data via the Paragon API.

8.1 Merchant Callback

A Merchant Callback is a built-in functionality within the Paragon system that allows a merchant to receive information regarding a specific transaction once it reaches a final status. Merchant Callbacks are commonly used by Merchants to ascertain whether a customer successfully paid for the product/service and to update the corresponding internal CRMs and/or accounting systems.

8.1.1 Merchant Callback URL

Once a transaction reaches its final state, the Paragon system sends a HTTP POST/GET message (can be configured per the Merchant’s request) to the Merchant Callback URL provided by the Merchant. The Merchant’s server needs to answer this POST/GET message with a 200 (OK) response or else the Paragon system will continue to send a Merchant Callback every 10 minutes for 24 hours. Please note only HTTPS port 443 is supported for Merchant Callbacks!

8.1.2 Merchant Callback Parameters

You may see an example how to check the callback siganture using JAVA programming language below. Example:

import org.junit.Test;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import static org.junit.Assert.assertEquals;

public class TestCallbackSignatureExampleTest {

    @Test
    public void test() {
        String digest3 = calculateCallbackSignature("approved", 123, "invoice-1", "AF4B5DE6-3468-424C-A922-C1DAD7CB4509");
        assertEquals("5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1", digest3);
    }

    public String calculateCallbackSignature(String aTransactionStatus, long aOrderId, String aMerchantOrderId, String aMerchantControlKey) {
        String text   = aTransactionStatus + aOrderId + aMerchantOrderId + aMerchantControlKey;
        byte[] buffer = text.getBytes(StandardCharsets.UTF_8);
        byte[] shaSum = sha(buffer);
        return toHexString(shaSum);
    }

    /**
    * Calculates the SHA-1 digest and returns the value as a <code>byte[]</code>.
    *
    * @param data
    *            Data to digest
    * @return SHA-1 digest
    */
    private static byte[] sha(byte[] data) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA");
            return digest.digest(data);
        } catch (NoSuchAlgorithmException e) {
           throw new IllegalStateException("Couldn't calculate SHA-1 digest", e);
        }
    }

    /**
     * Converts bytes to hex string
     */
    private static String toHexString(byte[] data) {
        StringBuilder sb = new StringBuilder();
        for (byte b : data) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                sb.append('0');
            }
            sb.append(hex);
        }
        return sb.toString();
    }

}

8.2 Transaction Status Requests

A Transaction Status Request is a functionality type that allows a merchant to receive information on a specific transaction or transaction range. A Transaction Status Request differs from a Merchant Callback in that a Merchant Callback is initiated immediately following a transaction reaching final status, whereas a Transaction Status Request can be performed at any time (post final status) by the merchant. The Paragon system supports two types of Transaction Status Requests:
* Specific Transaction Status Request – used to pull information regarding a single transaction.
* Transaction Range Status Request – used to pull information regarding transactions corresponding to certain query parameters.

8.2.1 Transaction Status Request API URL

Both Transaction Status Request types are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v1/status/ENDPOINTID

8.2.2 Specific Transaction Status Request Parameters

¹. This unique Control value is created using the following details: login + client_orderid + orderid + merchant_control. For more details on how to create the control parameter, please see section 10.1

8.2.3 Specific Transaction Status Request Response Parameters

8.2.4 Transaction Range Status Request Parameters

¹. Details on how to create the control parameter are outlined in section 10.1

8.2.5 Transaction Range Status Request Response Parameters

9. Reference

Country and State Codes

9.1 Two-Letter Country Codes

9.2 State Codes

Status Classes

Within Paragon the following transaction status classes are used:

9.3 Status Codes

The following section outlines the various status codes per status class as well as an explanation on what they mean. In addition, the decline status codes are also organised into three different tiers based on our recommended approach for resolving them:

• Tier 0 (T0) – includes temporary declines and declines due to invalid or missing data from the merchant. This can be resolved by simply retrying the transaction or verifying the data and retrying.

• Tier 1 (T1) – if you are sure that the transaction data provided is correct and you are still getting declines of this type, we recommend contacting a member of staff at Fibonatix to resolve the matter (either support or the relevant Account Manager).

• Tier 2 (T2) – declines of this type require the cardholder/account holder to contact their card issuer/payment account provider and ascertain what was the reason for the decline and what can be done about it.

• Tier 3 (T3) – if you are sure that the transaction data provided is correct and you are still getting declines of this type, we recommend using a different card/payment means.

Received (10)

Approved (20)

Pending (30)

Declined by Validation (41)

Declined by Risk Management (42)

Declined by Authentication (43)

A transaction will receive one of the ‘Declined by Authentication’ status codes when the cardholder fails to complete the 3D Secure authentication procedure. The best course of action would be to review the transaction in light of the provided status code and try and understand what went wrong and whether the cardholder should retry.

Declined by Processor (44)

A transaction will receive one of the ‘Declined by Processor’ status codes when a transaction is declined due to some consideration on the processor’s side. The best course of action would be to review the transaction in light of the provided status code and try and understand what went wrong or discuss the matter with your account manager.

Declined by Issuer (45)

A transaction will receive one of the ‘Declined by Issuer’ status codes when a transaction is declined due to some consideration on the card issuer’s side. The best course of action would be to review the transaction in light of the provided status code and try and understand what went wrong or discuss the matter with your account manager.

Declined by Technical Error (46)

A transaction will receive one of the ‘Declined by Technical Error’ status codes when a transaction is declined due to some technical issue on Paragon’s side. The best course of action would be to discuss the matter with your account manager who will advise on how to resolve the matter.

Unknown (90)

10. Customer Payment Page Customisation (Optional)

Fibonatix offers a basic ready-to-use Payment Page for all its customers (see example below). However, we are aware some customers prefer to have their own customised Payment Page with their own personal touch.

In this section, customers who wish to customise their Payment Page can do so easily, by following a few easy steps and observing a few key points:

1. Do NOT change any ID or name in a field which is designated as ID or Button.
2. Do NOT delete the JavaScript document provided by Fibonatix.
3. Due to security concerns, do NOT use CDN.
4. If a customer wishes to add Photos, Logos, Fonts, etc. to their Payment Page, they must send them all to Fibonatix, placed in a single folder.
5. Some fields are marked with "$!", this represents fields where the client will input real data. Changing their position is fine, however, do NOT change the name or type.
6. All Customer Payment Pages must include the relevant credit card companies' logos.
7. All Customer Payment Pages must include the customer' address.
8. All Customer Payment Pages must include a Descriptor, which cannot be deleted or omitted.

Payment Page Example

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta http-equiv="Pragma" content="no-cache" />
    <base href="$!URL_PAYMENT_PAGE" />
    <meta http-equiv="Expires" content="-1" />
    <meta http-equiv="Content-Security-Policy" content="default-src *; img-src *; media-src *; script-src * localhost; style-src * localhost;style-src-elem * localhost;" />
    <title>Custom payment page</title>
    <script type="text/javascript" src="https://cdn.paragon.online/scripts/ccform.js?v=1.86"></script>
  </head>
  <body>
    <div class="container">
      <form action="" method="post">
        <div class="form-container">
          <div class="form-content">
            <div class="top-title">
              <b>Your Credit Card Will Be Charged By:</b><br />
              <span class="descriptor">$!DESCRIPTOR</span>
            </div>
            <div class="validation-error" id="valdiation_error"></div>
            <div class="form-label">
              Card number<span class="form-label-comment">The 13-19 digits on the front of your card</span>
            </div>
            <input class="credit_card_number-field" id="credit_card_number" name="credit_card_number" type="text" maxlength="19" autocomplete="off" />
            <div class="form-label-nobottom">
              <span class="form-label-expiration">Expiration date</span>
              <span class="form-label-cvv">Card verification value</span>
            </div>
            <div class="form-label-notop">
              <span class="form-label-expiration">
                <select class="expiry-month" name="expire_month" id="expire_month" size="1" >
                  <option value="01">January</option>
                  <option value="02">February</option>
                  <option value="03">March</option>
                  <option value="04">April</option>
                  <option value="05">May</option>
                  <option value="06">June</option>
                  <option value="07">July</option>
                  <option value="08">August</option>
                  <option value="09">September</option>
                  <option value="10">October</option>
                  <option value="11">November</option>
                  <option value="12">December</option>
                </select>
                <select class="expiry-year"name="expire_year"id="expire_year" size="1"></select>
              </span>
              <span class="form-label-cvv">
                <input class="card-verification-value" name="cvv2" id="cvv2" type="text" maxlength="4" autocomplete="off"/>
                <span class="form-label-comment-cvv">
                  The last 3 digits displayed on the back of your card
                </span>
              </span>
            </div>
            <div class="form-label">Full Name on a Card</div>
            <input
              class="card-holder-name"
              name="card_printed_name"
              id="card_printed_name"
              type="text"
              maxlength="64"
            />
            <div class="legal">$!LEGAL</div>
          </div>
          <div class="ssl-footer">You will be charged $!AMOUNT $!CURRENCY</div>
        </div>
        <input class="form-submit" name="bSubmit" id="bSubmit" type="button" value="Complete Transaction" />
        <input type="hidden" name="serial_number" id="serial_number" value="$!SERIAL"/>
        <input type="hidden" name="endpointid" id="endpointid" value="$!ENDPOINTID"/>
        <input type="hidden" name="action" id="action" value="sale-form/pay" />
      </form>
    </div>
  </body>
</html>

11. Integration Helpers

• The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
  ## 11.1 SHA-1 Overview This page allows you to generate SHA-1 signatures using a known good SHA-1 library, https://code.google.com/archive/p/crypto-js/downloads. This way you can quickly identify if INVALID_CONTROL_CODE error received from the Fibonatix API server is due to a bad signature or another issue.
  

To reproduce your API call, input all of the data from your original request. An SHA-1 signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your SHA-1 signature code.

11.2 Control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters’ values in the following order:

• ENDPOINTID
• client_orderid
• minimal monetary units amount (i.e. cent, penny etc.)
• email
• merchant_control

A complete string example may look as follows:
[email protected]

Encrypt the string using SHA-1 algorithm, which can be found free online, such as: http://www.sha1-online.com/ The resultant string yields the control parameter which is required for request authorization. For the above-mentioned example the control will take the following value: d02e67236575a8e02dea5e094f3c8f12f0db43d7

11.3 Testing Integration in Sandbox Environment

Once a merchant finishes his Integration with the API, he can use these following cards in the Sandbox Environment (Credetials and access will be provided by the Merchant's Account Manager):

Card Number: 4111111111111111
Expiration: 01/2026
CCV: 123

Card Number: 4111110000000211
Expiration: 01/2026
CCV: 123