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

Preauth Request Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=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
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

¹. 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
&serial-number=000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&redirect-url=https%3a%2f%2fchannel.paragon.online%2fpayment-form%000002d53397

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

Preauth Request Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=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
&credit_card_number=4111111111111111
&expire_month=12
&expire_year=2026
&cvv2=123
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

Sale Response Example:

type=async-response
&serial-number=000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821

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

Capture Request Example:

client_orderid=902B4FF5
&orderid=k2s94FF5
&amount=10.42
&by-request-sn=s34B4FF5
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

¹. 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
&serial-number=2d53397

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

Void Request Example:

client_orderid=902B4FF5
&orderid=12mM4FF5
&by-request-sn=s34B4FF5
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

Void Response Example:

type=async-response
&paynet-order-id=6666821
&merchant-order-id=902B4FF5
&serial-number=2d53397

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

Sale Request Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=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
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

Sale Response Example:

type=async-response
&serial-number=000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&redirect-url=https%3a%2f%2fchannel.paragon.online%2fpayment-form%000002d53397

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

Sale Request Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=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
&credit_card_number=4111111111111111
&expire_month=12
&expire_year=2026
&cvv2=123
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

Sale Response Example:

type=async-response
&serial-number=000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&redirect-url=https%3a%2f%2fchannel.paragon.online%2fpayment-form%000002d53397

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:

• Process a successful Sale or Capture Transaction.
• Generate a Token, see section 7.
• Generate a Order Status API request, see section 8.2.
• 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)
  • The Control Key parameter needs to be added both to the token and the rebill requests.

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:

5.5.2 Rebill Request Parameters

Rebill Request Example:

client_orderid: 101
&email: john@smith.com
&payment_token: 691418ae-3e8a-4fbc-b4fb-8a94c124fafb
&order_desc: Testy Test
&amount: 39.00
&currency: EUR
&ipaddress: 10.10.10.1
&redirect_url: http://doc.fibonatix.com/doc/dummy.htm

¹ 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

Refund Request Example:

"client_orderid" = "902B4FF5", 
"orderid"= "12mM4FF5",
"amount" = "10.42",
"by-request-sn" = "s34B4FF5"
"control" = "768eb8162fc361a3e14150ec46e9a6dd8fbfa483"

¹. 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
&paynet-order-id=6666821
&merchant-order-id=902B4FF5
&serial-number=2d53397

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

Payout Request Examples

client_orderid=902B4FF5
&by-request-sn=s34B4FF5
&orderid=k2s94FF5
&first_name=John
&last_name=Smith
&country=US
&amount=100
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&card_printed_name=CARD HOLDER
&credit_card_number=4111111111111111
&expire_month=12
&expire_year=2026
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

5.7.3 Payout Response Parameters

Payout Response Example:

type=async-response
&paynet-order-id=6666821
&merchant-order-id=902B4FF5
&serial-number=2d53397

5.8 Chargeback (CK)

A chargeback/dispute is a return of funds back to the cardholder from the merchant. To process a chargeback, the issuer creates a formal dispute and the money is held from the merchant's account until the decision is ruled. In case of the cardholder's win, the payment amount, along with a separate dispute fee, is then deducted from the merchant's account balance.

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

Init Recurring Request Parameters Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=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
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

¹. 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.1.3 Payment Page Recurring Initialisation Response Parameters

Init Recurring Response Example:

type=async-response
&serial-number=000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&redirect-url=https%3a%2f%2fchannel.paragon.online%2fpayment-form%000002d53397
&recurring-sn=000002d532390w

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

Init Recurring Request Parameters Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&amount=10.42
&email=john.smith@gmail.com
&card_printed_name=CARD HOLDER
&credit_card_number=4111111111111111
&expire_month=12
&expire_year=2026
&cvv2=123
&currency=USD
&ipaddress=65.153.12.232
&first_payment_date=30.10.20
&recurring_date_type=day
&time_interval= 3
&number_of_payments= 3
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

Init Recurring Response Example:

{
  "type": "async-response",
  "paynet-order-id": "83n430ems",
  "merchant-order-id": "123abcd",
  "serial-number": "123dcba",
  "recurring-sn": "9872bshf",
}

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 (RP)

Recurring Payment (RP) 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.1.1 Recurring Payment Request Parameters

Recurring Request Example:

client_orderid=902B4FF5
&order_desc=Test Order Description
&by-recurring-sn=gwbcje02
&amount=1
&currency=USD

6.2.1.2 Recurring Payment API URL Response

Recurring Response Example:

{
  "type": "async-response",
  "paynet-order-id": "83n430ems",
  "merchant-order-id": "123abcd",
  "serial-number": "123dcba",
  "recurring-sn": "9872bshf",
}

6.3 Recurring Modification (RM)

Recurring Modification (RM) is a transaction type used by merchants to change some of the previously defined factors for a Recurring Payments Cycle (i.e. personal details, the amount and customer address).

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

Modify Recurring Request Example:

recurring_sn=usnf729343
&first_name=John
&last_name=Smith
&ssn=1267
&birthdate=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&amount=10.42
&email=john.smith@gmail.com

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

Modify Recurring Response Example:

{
  "type": "async-response",
  "status":"ok"
}

6.4 Recurring Cancellation (RC)

Recurring Cancellation (RC) 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

Recurring Cancellation Request Example:

by-recurring_sn=usnf729343
&login=MerchantLogin
&client_orderid=bjsd9w339f
&orderid=234kdk0L

6.4.3 Recurring Cancellation Response Parameters

Recurring Cancellation Response Example:

{
  "type": "async-response",
  "recurring-sn": "9872bshf",
}

6.5 Recurring Status

Recurring Status is a request type used by merchants to look at the overall status of a recurring payment contract, mostly used to verify a contract has been canceled or modified correctly.

6.5.1 Recurring Status API URL

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

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

6.5.2 Recurring Status Response Parameters

Recurring Status Response Example:

by-recurring_sn=usnf729343
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

6.5.3 Recurring Status Response Parameters

Recurring Status Response Example:

{
  "type": "status-response",
  "recurring-sn": "9872bshf",
  "time-interval": "1",
  "number-of-payments": 12,
  "date-type": "Day",
  "recurring-sn": "bhwmJGS9",
    "related-transactions":[
        {
            "amount": "1",
            "type": "initRecurring",
            "trx-id": "vduf8e779",
            "cluster-sn": "bshje820k",
            "is-charged": true,
            "charging-date": "2022-06-13T10:24:10"
        }
        ],
    "exp-year": "2026",
    "exp-month": "01"
}

6.6 Recurring Duplication transactions

This feature allows for the duplication of a Recurring Transaction.

6.6.1 Recurring Duplication 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.6.2 Recurring Duplication transaction Request Parameters

Recurring Duplication Request Example:

by-recurring-sn=902B4FF5
&login=MerchantLogin
&amount=10
&recurring_date_type=day
&time_interval=1
&number_of_payments=12
&first_recurring_payment_date=21.06.2022
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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

6.6.3 Recurring Duplication transaction Response Parameters

Recurring Duplication Response Example:

{
  "type": "async-response",
  "paynet-order-id": "nidmw23FFG",
  "merchant-order-id": "123",
  "serial-number": "000k9SSdfm",
  "redirect-url": "https%3a%2f%2fchannel.paragonon.line%2fpayment-form%2f000k9SSdfm",
  "recurring-sn": "9872bshf",
}

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}

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)

When creating a token from a CP, use the serial number of the original PA transaction.

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. In case of any other response, here is a reference with different response codes explained: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Please note only HTTPS port 443 is supported for Merchant Callbacks!

Merchants might need to whitelist our IP addresses in order to recieve callbacks: 18.169.68.24, 18.170.157.243

8.1.2 Merchant Callback Parameters

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.
In addition, a transaction status request is performed as a part of server-to-server requests, in order to redirect the client to the 3DS page.

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 Transaction Status Request Parameters

Transaction Status Request Example:

client_orderid=902B4FF5
&orderid=902B4Fmk
&by-request-sn=xx23456F5
&language=en
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Please note that this unique Control value is created using the following details: login + client_orderid + orderid + merchant_control.
For more details on where to create the control parameter, please see section 11.2

8.2.3 Transaction Status Response Parameters

Transaction Status Response Example:

type=status-response
&status=processing
&amount=10
&currency=GBP
&serial_number=1234dbca
&bank-name=BANKNAME
&bin=411111
&by-request-sn=1234abcd
&card-exp-month=01
&card-exp-year=2026
&cardholder-name=Testy Test
&card-type=CARDTYPE
&email=test@gmail.com
&html={redirect-url-with-html-to-render}
&last-four-digits=1111
&phone=00000001
&terminal-id={endpoint}
&transaction-type=sale
&paynet-order-id=bcda1234
&merchant-order-id=123
&status_description=Collecting Customer Data
&redirect-url=
&redirect-url3-d=
&processor-name=ABC
&dispute-age=

9. Reference

Country and State Codes

9.1 Two-Letter Country Codes

All country codes are according to ISO 3306. In requests please use the references below (in CAPITAL LETTERS):

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)

Resolved (11)

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.