NAV

3. Definitions

Throughout this document, the following definitions are used:

4. Transaction Types

Currently, Paragon supports the following transaction types:

Designation Full Name Environments
PA Pre-Authorisation PP, API, PBL, VT
CP Capture API, BO
Sl Sale PP, API, PBL, VT
RB Rebill API, BO
RI Recurring Initialisation PP, API, PBL, VT
RC Recurring Payment SYS
CR Payout API, BO
VD Void API, BO
RF Refund API, BO
TK Create Token PP, API, PBL, VT, BO
DT Delete Token API, BO
AV Account Verification PP, API
RQ Retrieval Request SYS
CB Chargeback SYS
FR Fraud SYS
PR Pre-Arbitration SYS
AR Arbitration SYS
C2 Chargeback 2 SYS
RP Representment SYS

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 Length/Type Description Stipulation*
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
preferred language 2/String Language choice for the Payment Page Optional
control 40/String Checksum generated by SHA-1 ³ Mandatory

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


Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error
redirect_url The URL to which the merchant would need to redirect the customer once the transaction is complete (via iframe or redirect)

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:

Parameter Name Description
credit_card_number The Customer’s credit/debit card number
expire_month The Customer’s credit/debit card expiry month
expire_year The Customer’s credit/debit card expiry year
cvv2 The Customer’s credit/debit card security code
card_printed_name The Customer’s name as it is printed on the credit/debit card

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
credit_card_number 19/Numeric The Customer’s credit/debit card number Mandatory
expire_month 2/Numeric The Customer’s credit/debit card expiry month Mandatory
expire_year 4/Numeric The Customer’s credit/debit card expiry year Mandatory
cvv2 3-4/Numeric The Customer’s credit/debit card security code Conditional
card_printed_name 128/String The Customer’s name as it is printed on the credit/debit card Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
control 40/String Checksum generated by SHA-1 ³ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String TRX ID assigned by our system Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5)¹ Optional
control 40/String Checksum generated by SHA-1 ² Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String TRX ID assigned by our system Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5)¹ Optional
control 40/String Checksum generated by SHA-1 ² Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
preferred language 2/String Language choice for the Payment Page Optional
control 40/String Checksum generated by SHA-1³ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error
redirect_url The URL to which the merchant would need to redirect the customer once the transaction is complete (via iframe or redirect)

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:

Parameter Name Description
credit_card_number The Customer’s credit/debit card number
expire_month The Customer’s credit/debit card expiry month
expire_year The Customer’s credit/debit card expiry year
cvv2 The Customer’s credit/debit card security code
card_printed_name The Customer’s name as it is printed on the credit/debit card

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
credit_card_number 19/Numeric The Customer’s credit/debit card number Mandatory
expire_month 2/Numeric The Customer’s credit/debit card expiry month Mandatory
expire_year 4/Numeric The Customer’s credit/debit card expiry year Mandatory
cvv2 3-4/Numeric The Customer’s credit/debit card security code Conditional
card_printed_name 128/String The Customer’s name as it is printed on the credit/debit card Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
control 40/String Checksum generated by SHA-1³ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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:

5.5.1 Rebill API URL

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

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String The TRX ID of the PA transaction Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5)¹ Optional
control 40/String Checksum generated by SHA-1² Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String The TRX ID of the PA transaction Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5)¹ Optional
control 40/String Checksum generated by SHA-1² Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
preferred language 2/String Language choice for the Payment Page Optional
control 40/String Checksum generated by SHA-1³ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error
redirect_url The URL to which the merchant would need to redirect the customer once the transaction is complete (via iframe or redirect)

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:

Parameter Name Description
credit_card_number The Customer’s credit/debit card number
expire_month The Customer’s credit/debit card expiry month
expire_year The Customer’s credit/debit card expiry year
cvv2 The Customer’s credit/debit card security code
card_printed_name The Customer’s name as it is printed on the credit/debit card

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
email 48/String Customer’s Email address Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
phone 48/String Customer’s Phone Number Optional
ipaddress 48/String Customer’s IP address Mandatory
credit_card_number 19/Numeric The Customer’s credit/debit card number Mandatory
card_printed_name 128/String The Customer’s name as it is printed on the credit/debit card Mandatory
expire_month 2/Numeric The Customer’s credit/debit card expiry month Mandatory
expire_year 4/Numeric The Customer’s credit/debit card expiry year Mandatory
cvv2 3-4/Numeric The Customer’s credit/debit card security code Conditional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
control 40/String Checksum generated by SHA-1³ Mandatory
first_recurring_payment_date 8/Numeric Date of first recurring payment (DD-MM-YYYY) Mandatory
recurring_date_type 8/String The type of recurring payment, such as: Day, week, month, year Mandatory
time_interval 8/String The number of time intervals (day,month,year- as indicated in previous field) between each recurring payment Mandatory
number_of_payments 4/Numeric The number of overall recurring payments Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial-number TRX ID assigned by our system
recurring-sn Recurring ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

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
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
ipaddress 48/String Customer’s IP address Mandatory
by-recurring-sn 8/String Recurring ID assigned by our system Mandatory

6.2.2 Recurring Payment API URL Response

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id The Cluster ID of the transaction sent in the request
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial-number TRX ID assigned by our system
redirect-url The URL to which the customer will be redirected after the transaction is complete
recurring-sn Recurring ID assigned by our system

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 Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
order_desc 256/String Brand/Merchant’s Transaction Description Conditional
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
currency 3/String Transaction Currency (per ISO 4217) Mandatory
first_name 48/String Customer’s first name Mandatory
last_name 48/String Customer’s last name Mandatory
ssn 24/String Customer’s ID/SSN Number Optional
birthdate 8/Numeric Customer’s Date of Birth (YYYY-MM-DD) Optional
address1 150/String Customer’s address Conditional
city 50/String Customer’s city Conditional
state 3/String Customer’s state¹ Conditional
zip_code 16/String Customer’s ZIP code/ Postal Code Conditional
country 2/String Customer’s Country of Residence² Mandatory
phone 48/String Customer’s Phone Number Optional
email 48/String Customer’s Email address Mandatory
ipaddress 48/String Customer’s IP address Mandatory
credit_card_number 19/Numeric The Customer’s credit/debit card number Mandatory
expire_month 2/Numeric The Customer’s credit/debit card expiry month Mandatory
expire_year 4/Numeric The Customer’s credit/debit card expiry year Mandatory
cvv2 3-4/Numeric The Customer’s credit/debit card security code Conditional
card_printed_name 128/String The Customer’s name as it is printed on the credit/debit card Mandatory
redirect_url 1024/String The URL to which the customer will be redirected after the transaction is complete Optional
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional
control 40/String Checksum generated by SHA-1³ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
by-recurring-sn 8/String Recurring ID assigned by our system Mandatory
login 40/String Merchant login name Mandatory
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory


6.4.3 Recurring Cancellation Response Parameters

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
recurring-sn Recurring ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error


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}

Parameter Length/Type Description Stipulation
by-recurring-sn 8/String Recurring ID assigned by our system Mandatory
control 40/String Checksum generated by SHA-1¹ Mandatory

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

Parameter Length/Type Description Stipulation
by-recurring-sn 8/String Recurring ID assigned by our system Mandatory
login 40/String Merchant login name Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Mandatory
control 40/String Checksum generated by SHA-1¹ Mandatory
recurring_date_type 8/String The type of recurring payment, such as: Day, week, month, year Mandatory
time_interval 8/String The number of time intervals (day,month,year- as indicated in previous field) between each recurring payment Mandatory
number_of_payments 4/Numeric The number of overall recurring payments Mandatory
first_recurring_payment_date 8/Numeric Date of first recurring payment (DD-MM-YYYY) Mandatory
server_callback_url 1024/String The URL to which the callback is sent after the transaction is complete Optional

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

6.5.3 Duplicate Recurring transaction Response Parameters

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial-number TRX ID assigned by our system
recurring-sn Recurring ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

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

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String The TRX ID of the PA transaction Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Optional
control 40/String Checksum generated by SHA-1¹ Mandatory

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

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details
status The status of the transaction.
amount Transaction Amount
currency Transaction Currency (per ISO 4217)
serial_number TRX ID assigned by our system
bank name The name of the bank the transaction went through
bin The first 6 digits of the credit card number
by-request-sn The TRX ID of the PA transaction
expire_month The Customer’s credit/debit card expiry month
expire_year The Customer’s credit/debit card expiry year
cardholder_name The Customer’s name
card_type Credit card type
email Customer’s Email address
last_four_digits The last 4 digits from customer's credit card
phone Customer's phone
terminal_id Merchant's ENDPOINT ID
transaction_type The transaction's type
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
processor_name The transaction's processor name
redirect-url-3d The merchant can use this address to redirect the client to the 3DS page, intesad of the regular HTML.


8.2.4 Transaction Range Status Request Parameters

Parameter Length/Type Description Stipulation
client_orderid 48/String Brand/Merchant’s Transaction ID Mandatory
orderid 8/String The Cluster ID received from the PA transaction Mandatory
by-request-sn 8/String The TRX ID of the PA transaction Mandatory
amount 10/Numeric Transaction Amount (i.e., 10.5 = £10.5) Optional
control 40/String Checksum generated by SHA-1¹ Mandatory

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

8.2.5 Transaction Range Status Request Response Parameters

Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Cluster ID assigned to the transaction by our system
merchant-order-id The Brand/Merchant’s Transaction ID sent in the request
serial_number TRX ID assigned by our system
error-message If status is declined or error this parameter contains the decline/error explanation
error-code The status code in case of declined or error

9. Reference

Country and State Codes

9.1 Two-Letter Country Codes

Country ID Country Code
1 Åland Islands AX
2 Afghanistan AF
3 Albania AL
4 Algeria DZ
5 American Samoa AS
6 Andorra AD
7 Angola AO
8 Anguilla AI
9 Antarctica AQ
10 Antigua and Barbuda AG
11 Argentina AR
12 Armenia AM
13 Aruba AW
14 Australia AU
15 Austria AT
16 Azerbaijan AZ
17 Bahamas BS
18 Bahrain BH
19 Bangladesh BD
20 Barbados BB
21 Belarus BY
22 Belgium BE
23 Belize BZ
24 Benin BJ
25 Bermuda BM
26 Bhutan BT
27 Bolivia, Plurinational State of BO
28 Bosnia and Herzegovina BA
29 Botswana BW
30 Bouvet Island BV
31 Brazil BR
32 British Indian Ocean Territory IO
33 Brunei Darussalam BN
34 Bulgaria BG
35 Burkina Faso BF
36 Burundi BI
37 Cambodia KH
38 Cameroon CM
39 Canada CA
40 Cabo Verde CV
41 Cayman Islands KY
42 Central African Republic CF
43 Chad TD
44 Chile CL
45 China CN
46 Christmas Island CX
47 Cocos (Keeling) Islands CC
48 Colombia CO
49 Comoros KM
50 Congo CG
51 Congo, the Democratic Republic of CD
52 Cook Islands CK
53 Costa Rica CR
54 Cote d’Ivoire CI
55 Croatia HR
56 Cyprus CY
57 Czech Republic CZ
58 Denmark DK
59 Djibouti DJ
60 Dominica DM
61 Dominican Republic DO
62 Ecuador EC
63 Egypt EG
64 El Salvador SV
65 Equatorial Guinea GQ
66 Eritrea ER
67 Estonia EE
68 Ethiopia ET
69 Falkland Islands (Malvinas) FK
70 Faroe Islands FO
71 Fiji FJ
72 Finland FI
73 France FR
74 French Guiana GF
75 French Polynesia PF
76 French Southern Territories TF
77 Gabon GA
78 Gambia GM
79 Georgia GE
80 Germany DE
81 Ghana GH
82 Gibraltar GI
83 Greece GR
84 Greenland GL
85 Grenada GD
86 Guadeloupe GP
87 Guam GU
88 Guatemala GT
89 Guernsey GG
90 Guinea GN
91 Guinea-Bissau GW
92 Guyana GY
93 Haiti HT
94 Heard Island and McDonald Islands HM
95 Holy See (Vatican City State) VA
96 Honduras HN
97 Hong Kong HK
98 Hungary HU
99 Iceland IS
100 India IN
101 Indonesia ID
102 Iraq IQ
103 Ireland IE
104 Isle of Man IM
105 Israel IL
106 Italy IT
107 Jamaica JM
108 Japan JP
109 Jersey JE
110 Jordan JO
111 Kazakhstan KZ
112 Kenya KE
113 Kosovo QZ
114 Kiribati KI
115 Korea, Republic of KR
116 Kuwait KW
117 Kyrgyzstan KG
118 Lao People’s Democratic Republic LA
119 Latvia LV
120 Lebanon LB
121 Lesotho LS
122 Liberia LR
123 Libya LY
124 Liechtenstein LI
125 Lithuania LT
126 Luxembourg LU
127 Macao MO
128 Macedonia, North MK
129 Madagascar MG
130 Malawi MW
131 Malaysia MY
132 Maldives MV
133 Mali ML
134 Malta MT
135 Marshall Islands MH
136 Martinique MQ
137 Mauritania MR
138 Mauritius MU
139 Mayotte YT
140 Mexico MX
141 Micronesia, Federated States of FM
142 Moldova, Republic of MD
143 Monaco MC
144 Mongolia MN
145 Montenegro ME
146 Montserrat MS
147 Morocco MA
148 Mozambique MZ
149 Myanmar MM
150 Namibia NA
151 Nauru NR
152 Nepal NP
153 Netherlands NL
154 Netherlands Antilles AN
155 New Caledonia NC
156 New Zealand NZ
157 Nicaragua NI
158 Niger NE
159 Nigeria NG
160 Niue NU
161 Norfolk Island NF
162 Northern Mariana Islands MP
163 Norway NO
164 Oman OM
165 Pakistan PK
166 Palau PW
167 Panama PA
168 Papua New Guinea PG
169 Paraguay PY
170 Peru PE
171 Philippines PH
172 Pitcairn PN
173 Poland PL
174 Portugal PT
175 Puerto Rico PR
176 Qatar QA
177 Reunion RE
178 Romania RO
179 Russian Federation RU
180 Rwanda RW
181 Saint Barthelemy BL
182 Saint Helena, Ascension and Tristan da Cunha SH
183 Saint Kitts and Nevis KN
184 Saint Lucia LC
185 Saint Martin (French part) MF
186 Saint Pierre and Miquelon PM
187 Saint Vincent and the Grenadines VC
188 Samoa WS
189 San Marino SM
190 Sao Tome and Principe ST
191 Saudi Arabia SA
192 Senegal SN
193 Serbia RS
194 Seychelles SC
195 Sierra Leone SL
196 Singapore SG
197 Slovakia SK
198 Slovenia SI
199 Solomon Islands SB
200 Somalia SO
201 South Africa ZA
202 South Georgia and the South Sandwich Islands GS
203 Spain ES
204 Sri Lanka LK
205 Sudan SD
206 Suriname SR
207 Svalbard and Jan Mayen SJ
208 Swaziland SZ
209 Sweden SE
210 Switzerland CH
211 Taiwan TW
212 Tajikistan TJ
213 Tanzania, United Republic of TZ
214 Thailand TH
215 Timor-Leste TL
216 Togo TG
217 Tokelau TK
218 Tonga TO
219 Trinidad and Tobago TT
220 Tunisia TN
221 Turkey TR
222 Turkmenistan TM
223 Turks and Caicos Islands TC
224 Tuvalu TV
225 Uganda UG
226 Ukraine UA
227 United Arab Emirates AE
228 United Kingdom GB
229 United States US
230 United States Minor Outlying Islands UM
231 Uruguay UY
232 Uzbekistan UZ
233 Vanuatu VU
234 Venezuela, Bolivarian Republic of VE
235 Vietnam VN
236 Virgin Islands, British VG
237 Virgin Islands, U.S. VI
238 Wallis and Futuna WF
239 Western Sahara EH
240 Yemen YE
241 Zambia ZM
242 Zimbabwe ZW
243 Europe EU
244 Asia/Pacific Region AP
245 Satellite Provider A2
246 Anonymous Proxy A1
247 Sint Maarten (Dutch part) SX
258 Curaçao CW
259 Bonaire, Sint Eustatius and Saba BQ
260 South Sudan SS

9.2 State Codes

Country State Code State Name
AU ACT Australian Capital Territory
AU NSW New South Wales
AU NT Northern Territory
AU QLD Queensland
AU SA South Australia
AU TAS Tasmania
AU VIC Victoria
AU WA Western Australia
CA AB Alberta
CA BC British Columbia
CA MB Manitoba
CA NB New Brunswick
CA NL Newfoundland and Labrador
CA NT Northwest Territories
CA NS Nova Scotia
CA NU Nunavut
CA ON Ontario
CA PE Prince Edward Island
CA QC Quebec
CA SK Saskatchewan
CA YT Yukon
US AL Alabama
US AK Alaska
US AS American Samoa
US AZ Arizona
US AR Arkansas
US CA California
US CO Colorado
US CT Connecticut
US DE Delaware
US DC District of Columbia
US FL Florida
US GA Georgia
US GU Guam
US HI Hawaii
US ID Idaho
US IL Illinois
US IN Indiana
US IA Iowa
US KS Kansas
US KY Kentucky
US LA Louisiana
US ME Maine
US MD Maryland
US MA Massachusetts
US MI Michigan
US MN Minnesota
US MS Mississippi
US MO Missouri
US MT Montana
US NE Nebraska
US NV Nevada
US NH New Hampshire
US NJ New Jersey
US NM New Mexico
US NY New York
US NC North Carolina
US ND North Dakota
US OH Ohio
US OK Oklahoma
US OR Oregon
US PA Pennsylvania
US PR Puerto Rico
US RI Rhode Island
US SC South Carolina
US SD South Dakota
US TN Tennessee
US TX Texas
US UT Utah
US VT Vermont
US VI Virgin Islands
US VA Virginia
US WA Washington
US WV West Virginia
US WI Wisconsin
US WY Wyoming

Status Classes

Within Paragon the following transaction status classes are used:

CODE NAME DESCRIPTION STATE
10 Received The transaction is received (for received transaction types) Final
20 Approved The transaction is approved (for transmitted transaction types) Final
30 Pending The transaction is in process Transitionary
41 Declined by Validation The transaction was declined by a validation check Final
42 Declined by Risk Management The transaction was declined by a risk management rule/decision Final
43 Declined by Authentication The transaction was declined by authentication protocol Final
44 Declined by Processor The transaction was declined by the payment processor Final
45 Declined by Issuer The transaction was declined by the card issuer Final
46 Declined by Technical Error The transaction was declined due to a technical issue Final
90 Unknown The transaction status is unknown Final

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:

Received (10)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
10000 Transaction Received A notification transaction has been received from the processor/issuer N/A CB, FR, RQ, RP, PR, AR, C2

Approved (20)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
20000 Transaction Approved A transmitted transaction has been approved by the processor/issuer N/A PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV

Pending (30)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
30001 Transaction Started The transaction flow has started N/A PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
30002 Payment Page Engaged The payment page has been accessed by the customer N/A PA, SL, RI
30003 Collecting Customer Data The system is collecting customer data provided by the merchant, the customer and via various services N/A PA, SL, RI, RB
30004 Storing Customer Data The collected data is encrypted and stored in the system’s database N/A PA, SL, RI, RB
30005 Pre-3DS Redirection The system is preparing the 3DS authentication request N/A PA, SL, RI, RB
30006 Pending Authentication The system is waiting for the customer to complete the 3DS authentication protocol N/A PA, SL, RI, RB
30007 Post-3DS Redirection The system is routing the transaction to the relevant acquirer N/A PA, SL, RI, RB

Declined by Validation (41)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
41001 Invalid Brand TRX ID The request parameter was sent in an invalid format T0 PA, SL, CP, RF, VD, RI, RB, TK, DT, CR, AV
41002 Invalid Order Description The request parameter was sent in an invalid format T0 PA, SL, RI, RB, CR, AV
41003 Invalid First Name The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41004 Invalid Last Name The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41005 Invalid ID/SSN The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41006 Invalid Birthdate The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41007 Invalid Customer Address The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41008 Invalid Customer City The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41009 Invalid Customer Postcode The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41010 Invalid Customer State The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41011 Invalid Customer Country The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41012 Invalid Customer Phone The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41013 Invalid Customer Email The request parameter was sent in an invalid format T0 PA, SL, RI, RB, TK, CR, AV
41014 Invalid Amount The request parameter was sent in an invalid format T0 PA, SL, CP, RF, RC, RI, RB, CR
41015 Invalid Currency Code The request parameter was sent in an invalid format T0 PA, SL, CP, RF, RC, RI, RB, CR
41016 Invalid IP Address The request parameter was sent in an invalid format T0 PA, SL, RI, RB, CR, AV
41017 Invalid Merchant Control The request parameter was sent in an invalid format T0 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41018 Invalid Redirect URL The request parameter was sent in an invalid format T0 PA, SL, RI, RB
41019 Invalid Card Number The request parameter was sent in an invalid format T0 PA, SL, RI, TK, CR, AV
41020 Invalid CVV The request parameter was sent in an invalid format T0 PA, SL, RI, TK, AV
41021 Invalid Expiration Date The request parameter was sent in an invalid format T0 PA, SL, RI, TK, CR, AV
41022 Expired Card The card expiry date is in a valid format, but expired T3 PA, SL, RI, TK, CR, AV
41023 Invalid Cardholder Name The request parameter was sent in an invalid format T0 PA, SL, RI, TK, CR, AV
41024 Invalid Token The request parameter was sent in an invalid format T0 RB, RI, DT
41025 Invalid Reference SN The request parameter was sent in an invalid format T0 CP, RF, VD, RI
41026 Invalid Reference Cluster ID The request parameter was sent in an invalid format T0 CP, RF, VD, RI
41027 Invalid Action/Workflow The attempted transaction was is not possible within the current workflow (e.g. refund on a declined transaction) T0 RF, VD, CP, RC, DT
41028 Refund Amount Too High The attempted refund amount is higher than the original transaction amount T0 RF
41029 Capture Amount Too High The attempted capture amount is higher than the original pre-authorisation amount T0 CP
41030 Invalid Channel/Endpoint ID The request parameter was sent with an invalid channel/endpoint ID T0/T1 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41031 Invalid Server Callback URL The request parameter was sent in an invalid format T0 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41032 Invalid Comment The request parameter was sent in an invalid format T0 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41033 Invalid Time Interval The request parameter was sent in an invalid format T0 RI
41034 Invalid Number of Payments The request parameter was sent in an invalid format T0 RI
41035 Invalid First Payment Date The request parameter was sent in an invalid format T0 RI
41036 Invalid Date Type The request parameter was sent in an invalid format T0 RI
41101 Missing Brand TRX ID The request parameter field is missing from the request T0 PA, SL, CP, RF, VD, RI, RB, TK, DT, CR, AV
41102 Missing Order Description The request parameter field is missing from the request T0 PA, SL, RI, RB, CR, AV
41103 Missing First Name The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41104 Missing Last Name The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41105 Missing ID/SSN The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41106 Missing Birthdate The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41107 Missing Customer Address The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41108 Missing Customer City The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41109 Missing Customer Postcode The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41110 Missing Customer State The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41111 Missing Customer Country The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41112 Missing Customer Phone The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41113 Missing Customer Email The request parameter field is missing from the request T0 PA, SL, RI, RB, TK, CR, AV
41114 Missing Amount The request parameter field is missing from the request T0 PA, SL, CP, RF, RC, RI, RB, CR
41115 Missing Currency Code The request parameter field is missing from the request T0 PA, SL, CP, RF, RC, RI, RB, CR
41116 Missing IP Address The request parameter field is missing from the request T0 PA, SL, RI, RB, CR, AV
41117 Missing Merchant Control The request parameter field is missing from the request T0 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41118 Missing Redirect URL The request parameter field is missing from the request T0 PA, SL, RI, RB
41119 Missing Card Number The request parameter field is missing from the request T0 PA, SL, RI, TK, CR, AV
41120 Missing CVV The request parameter field is missing from the request T0 PA, SL, RI, TK, AV
41121 Missing Expiration Date The request parameter field is missing from the request T0 PA, SL, RI, TK, CR, AV
41122 Missing Cardholder Name The request parameter field is missing from the request T0 PA, SL, RI, TK, CR, AV
41123 Missing Token The request parameter field is missing from the request T0 RB, RI, DT
41124 Missing Reference SN The request parameter field is missing from the request T0 CP, RF, VD, RI
41125 Missing Reference Cluster ID The request parameter field is missing from the request T0 CP, RF, VD, RI
41126 Duplicate Request/Transaction The request/transaction is a duplicate T0 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
41127 Missing Time Interval The request parameter field is missing from the request T0 RI
41128 Missing Number of Payments The request parameter field is missing from the request T0 RI
41129 Missing First Payment Date The request parameter field is missing from the request T0 RI
41130 Missing Date Type The request parameter field is missing from the request T0 RI

Declined by Risk Management (42)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
42001 Card is Blacklisted The payment card used is in a global or merchant-specific blacklist (for card payments) T0, T1 PA, SL, RC, RI, RB, CR, AV
42002 Payment Account is Blacklisted The payment account used is in a global or merchant-specific blacklist (for APMs/Wires) T0, T1 PA, SL, RC, RI, RB, CR, AV
42003 Email Address is Blacklisted The customer’s email address is in a global or merchant-specific blacklist T0, T1 PA, SL, RC, RI, RB, CR, AV
42004 IP Address is Blacklisted The customer’s IP address is in a global or merchant-specific blacklist T0, T1 PA, SL, RI, RB, CR, AV
42005 ID/SSN is Blacklisted The customer’s ID/SSN is in a global or merchant-specific blacklist T0, T1 PA, SL, RC, RI, RB, CR, AV
42006 Card BIN is Blacklisted The BIN (first 6 digits) of the card used is in a global or merchant-specific blacklist (for card payments) T0, T1 PA, SL, RC, RI, RB, CR, AV
42007 Card Issuer is Blacklisted The issuer (e.g. Bank) of the card used is in a global or merchant-specific blacklist (for card payments) T0, T1 PA, SL, RC, RI, RB, CR, AV
42008 Card Country is Blacklisted The card used is from a country in a global or merchant-specific blacklist (for card payments) T0, T1 PA, SL, RC, RI, RB, CR, AV
42009 Payment Account Country is Blacklisted The payment account used is from a country in a global or merchant-specific blacklist (for APMs/Wires) T0, T1 PA, SL, RC, RI, RB, CR, AV
42010 IP Country is Blacklisted The customer’s IP address is from a country in a global or merchant-specific blacklist T0, T1 PA, SL, RI, RB, CR, AV
42011 Email Domain is Blacklisted The customer’s email address domain is in a global or merchant-specific blacklist T0, T1 PA, SL, RC, RI, RB, CR, AV
42012 Postcode is Blacklisted The customer’s postcode is in a global or merchant-specific blacklist T0, T1 PA, SL, RI, RB, CR, AV
42013 The customer’s physical address is from a state in a global or merchant-specific blacklist T0, T1 PA, SL, RI, RB, CR, AV
42014 Phone is Blacklisted The customer’s phone number is in a global or merchant-specific blacklist T0, T1 PA, SL, RI, RB, CR, AV
42101 Transaction Amount is Too High The transaction amount exceeds the maximum amount limit T1 PA, SL, RC, RI, RB
42102 Transaction Amount is Too Low The transaction amount doesn’t meet the minimum amount threshold T1 PA, SL, RC, RI, RB
42103 Transaction Exceeds Amount Limit per Card The total volume of transactions using this card has exceeded the amount limit (for card payments) T1 PA, SL, RC, RI, RB
42104 Transaction Exceeds Amount Limit per Payment Account The total volume of transactions using this payment account has exceeded the Amount limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42105 Transaction Exceeds Amount Limit per Email The total volume of transactions using this email address has exceeded the Amount limit T1 PA, SL, RC, RI, RB
42106 Transaction Exceeds Amount Limit per IP Address The total volume of transactions using this IP address has exceeded the Amount limit T1 PA, SL, RI, RB
42107 Transaction Exceeds Daily Amount Limit per Card The volume of transactions using this card has exceeded the daily amount limit (for card payments) T1 PA, SL, RC, RI, RB
42108 Transaction Exceeds Daily Amount Limit per Payment Account The volume of transactions using this payment account has exceeded the daily amount limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42109 Transaction Exceeds Daily Amount Limit per Email The volume of transactions using this email address has exceeded the daily amount limit T1 PA, SL, RC, RI, RB
42110 Transaction Exceeds Daily Amount Limit per IP Address The volume of transactions using this IP address has exceeded the daily amount limit T1 PA, SL, RI, RB
42111 Transaction Exceeds Daily Amount Limit per Brand The volume of transactions for this brand has exceeded the daily amount limit T1 PA, SL, RI, RB
42112 Transaction Exceeds Daily Amount Limit per Channel The volume of transactions for this channel has exceeded the daily amount limit T1 PA, SL, RI, RB
42113 Transaction Exceeds Daily Amount Limit per Environment The volume of transactions for this environment has exceeded the daily amount limit T1 PA, SL, RI, RB
42114 Transaction Exceeds Weekly Amount Limit per Card The volume of transactions using this card has exceeded the weekly amount limit (for card payments) T1 PA, SL, RC, RI, RB
42115 Transaction Exceeds Weekly Amount Limit per Payment Account The volume of transactions using this payment account has exceeded the weekly amount limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42116 Transaction Exceeds Weekly Amount Limit per Email The volume of transactions using this email address has exceeded the weekly amount limit T1 PA, SL, RC, RI, RB
42117 Transaction Exceeds Weekly Amount Limit per IP Address The volume of transactions using this IP address has exceeded the weekly amount limit T1 PA, SL, RI, RB
42118 Transaction Exceeds Weekly Amount Limit per Brand The volume of transactions for this brand has exceeded the weekly amount limit T1 PA, SL, RI, RB
42119 Transaction Exceeds Weekly Amount Limit per Channel The volume of transactions for this channel has exceeded the weekly amount limit T1 PA, SL, RI, RB
42120 Transaction Exceeds Weekly Amount Limit per Environment The volume of transactions for this environment has exceeded the weekly amount limit T1 PA, SL, RI, RB
42121 Transaction Exceeds Monthly Amount Limit per Card The volume of transactions using this card has exceeded the monthly amount limit (for card payments) T1 PA, SL, RC, RI, RB
42122 Transaction Exceeds Monthly Amount Limit per Payment Account The volume of transactions using this payment account has exceeded the monthly amount limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42123 Transaction Exceeds Monthly Amount Limit per Email The volume of transactions using this email address has exceeded the monthly amount limit T1 PA, SL, RC, RI, RB
42124 Transaction Exceeds Monthly Amount Limit per IP Address The volume of transactions using this IP address has exceeded the monthly amount limit T1 PA, SL, RI, RB
42125 Transaction Exceeds Monthly Amount Limit per Brand The volume of transactions for this brand has exceeded the monthly amount limit T1 PA, SL, RI, RB
42126 Transaction Exceeds Monthly Amount Limit per Channel The volume of transactions for this channel has exceeded the monthly amount limit T1 PA, SL, RI, RB
42127 Transaction Exceeds Monthly Amount Limit per Environment The volume of transactions for this environment has exceeded the monthly amount limit T1 PA, SL, RI, RB
42140 Transaction Exceeds Count Limit per Card The total number of transactions using this card has exceeded the count limit (for card payments) T1 SL, PA, RB
42141 Transaction Exceeds Count Limit per Payment Account The total number of transactions using this payment account has exceeded the count limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42142 Transaction Exceeds Count Limit per Email The total number of transactions using this email address has exceeded the count limit T1 PA, SL, RC, RI, RB
42143 Transaction Exceeds Count Limit per IP Address The total number of transactions using this IP address has exceeded the count limit T1 PA, SL, RI, RB
42144 Transaction Exceeds Daily Count Limit per Card The number of transactions using this card has exceeded the daily count limit (for card payments) T1 PA, SL, RC, RI, RB
42145 Transaction Exceeds Daily Count Limit per Payment Account The number of transactions using this payment account has exceeded the daily count limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42146 Transaction Exceeds Daily Count Limit per Email The number of transactions using this email address has exceeded the daily count limit T1 PA, SL, RC, RI, RB
42147 Transaction Exceeds Daily Count Limit per IP Address The number of transactions using this IP address has exceeded the daily count limit T1 PA, SL, RI, RB
42148 Transaction Exceeds Daily Count Limit per Brand The number of transactions for this brand has exceeded the daily count limit T1 PA, SL, RC, RI, RB
42149 Transaction Exceeds Daily Count Limit per Channel The number of transactions for this channel has exceeded the daily count limit T1 PA, SL, RI, RB
42150 Transaction Exceeds Daily Count Limit per Environment The number of transactions for this environment has exceeded the daily count limit T1 PA, SL, RI, RB
42151 Transaction Exceeds Weekly Count Limit per Card The number of transactions using this card has exceeded the weekly count limit (for card payments) T1 PA, SL, RC, RI, RB
42152 Transaction Exceeds Weekly Count Limit per Payment Account The number of transactions using this payment account has exceeded the weekly count limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42153 Transaction Exceeds Weekly Count Limit per Email The number of transactions using this email address has exceeded the weekly count limit T1 PA, SL, RC, RI, RB
42154 Transaction Exceeds Weekly Count Limit per IP Address The number of transactions using this IP address has exceeded the weekly count limit T1 PA, SL, RI, RB
42155 Transaction Exceeds Weekly Count Limit per Brand The number of transactions for this brand has exceeded the weekly count limit T1 PA, SL, RI, RB
42156 Transaction Exceeds Weekly Count Limit per Channel The number of transactions for this channel has exceeded the weekly count limit T1 PA, SL, RI, RB
42157 Transaction Exceeds Weekly Count Limit per Environment The number of transactions for this environment has exceeded the weekly count limit T1 PA, SL, RI, RB
42158 Transaction Exceeds Monthly Count Limit per Card The number of transactions using this card has exceeded the monthly count limit (for card payments) T1 PA, SL, RC, RI, RB
42159 Transaction Exceeds Monthly Count Limit per Payment Account The number of transactions using this payment account has exceeded the monthly count limit (for APMs/Wires) T1 PA, SL, RC, RI, RB
42160 Transaction Exceeds Monthly Count Limit per Email The number of transactions using this email address has exceeded the monthly count limit T1 PA, SL, RC, RI, RB
42161 Transaction Exceeds Monthly Count Limit per IP Address The number of transactions using this IP address has exceeded the monthly count limit T1 PA, SL, RI, RB
42162 Transaction Exceeds Monthly Count Limit per Brand The number of transactions for this brand has exceeded the monthly count limit T1 PA, SL, RI, RB
42163 Transaction Exceeds Monthly Count Limit per Channel The number of transactions for this channel has exceeded the monthly count limit T1 PA, SL, RI, RB
42164 Transaction Exceeds Monthly Count Limit per Environment The number of transactions for this environment has exceeded the monthly count limit T1 PA, SL, RI, RB
42180 Transaction Exceeds Daily Amount Ratio per Environment The volume of transactions for this environment has exceeded the daily amount ratio (% of total sales) T1 PA, SL, RI, RB
42181 Transaction Exceeds Weekly Amount Ratio per Environment The volume of transactions for this environment has exceeded the Weekly amount ratio (% of total sales) T1 PA, SL, RI, RB
42182 Transaction Exceeds Monthly Amount Ratio per Environment The volume of transactions for this environment has exceeded the Monthly amount ratio (% of total sales) T1 PA, SL, RI, RB
42183 Refund Exceeds Daily Amount Ratio The volume of refunds for this brand has exceeded the daily amount ratio (% of total sales) T1 RF
42184 Refund Exceeds Weekly Amount Ratio The volume of refunds for this brand has exceeded the weekly amount ratio (% of total sales) T1 RF
42185 Refund Exceeds Monthly Amount Ratio The volume of refunds for this brand has exceeded the monthly amount ratio (% of total sales) T1 RF
42186 Payout Exceeds Daily Amount Ratio The volume of payouts for this brand has exceeded the daily amount ratio (% of total sales) T1 CR
42187 Payout Exceeds Weekly Amount Ratio The volume of payouts for this brand has exceeded the weekly amount ratio (% of total sales) T1 CR
42188 Payout Exceeds Monthly Amount Ratio The volume of payouts for this brand has exceeded the monthly amount ratio (% of total sales) T1 CR
42189 Transaction Exceeds Daily Count Ratio per Environment The number of transactions for this environment has exceeded the daily count ratio (% of total sales) T1 PA, SL, RI, RB
42190 Transaction Exceeds Weekly Count Ratio per Environment The number of transactions for this environment has exceeded the weekly count ratio (% of total sales) T1 PA, SL, RI, RB
42191 Transaction Exceeds Monthly Count Ratio per Environment The number of transactions for this environment has exceeded the monthly count ratio (% of total sales) T1 PA, SL, RI, RB
42192 Refund Exceeds Daily Count Ratio The number of refunds for this brand has exceeded the daily count ratio (% of total sales) T1 RF
42193 Refund Exceeds Weekly Count Ratio The number of refunds for this brand has exceeded the weekly count ratio (% of total sales) T1 RF
42194 Refund Exceeds Monthly Count Ratio The number of refunds for this brand has exceeded the monthly count ratio (% of total sales) T1 RF
42195 Payout Exceeds Daily Count Ratio The number of payouts for this brand has exceeded the daily count ratio (% of total sales) T1 CR
42196 Payout Exceeds Weekly Count Ratio The number of payouts for this brand has exceeded the weekly count ratio (% of total sales) T1 CR
42197 Payout Exceeds Monthly Count Ratio The number of payouts for this brand has exceeded the monthly count ratio (% of total sales) T1 CR

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.

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
43001 3DS Authentication Not Completed The transaction declined because the cardholder did not complete the authentication process within the given timeframe T0 PA, SL, RI, RB
43002 3DS Authentication Failed The transaction declined because the cardholder attempted the authentication process and failed T0 PA, SL, RI, RB
43003 Technical Error with 3DS Authentication The transaction declined because something (not related to the cardholder) went wrong during the 3DS authentication process T1 PA, SL, RI, RB
43004 Card Not Enrolled This decline means that either the customer’s card issuer (bank) is not yet supporting 3DS or that the cardholder has not yet been registered for the service. T3 PA, SL, RI, RB

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.

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
44001 Inactive Merchant/Terminal The MID(s) and/or terminal(s) are inactive with the processor and cannot accept transactions T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44002 Unsupported Payment Method/Type The card brand or payment method used by the customer is not supported by the processor T1 PA, SL, RI, RB, CR, AV
44003 Invalid Merchant/Terminal Configuration The brand/merchant/terminal has been improperly configured and needs to be amended T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44010 Transaction Declined by the Processor's Risk Management The processor’s risk management system declined the transaction without providing additional information T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44011 Card is Blacklisted by the Processor The payment card used is in the processor’s blacklist (for card payments) T1 PA, SL, RI, RC, RB, CR, AV
44012 Payment Account is Blacklisted by the Processor The payment account used is in the processor’s blacklist (for APMs/Wires) T1 PA, SL, RI, RC, RB, CR, AV
44013 Email Address is Blacklisted by the Processor The customer’s email address is in the processor’s blacklist T1 PA, SL, RI, RC, RB, CR, AV
44014 IP Address is Blacklisted by the Processor The customer’s IP address is in the processor’s blacklist T1 PA, SL, RI, RC, RB, CR, AV
44015 ID/SSN is Blacklisted by the Processor The customer’s ID/SSN is in the processor’s blacklist T1 PA, SL, RI, RC, RB, CR, AV
44016 Card BIN is Blacklisted by the Processor The BIN (first 6 digits) of the card used is in the processor’s blacklist (for card payments) T1 PA, SL, RI, RC, RB, CR, AV
44017 Card Issuer is Blacklisted by the Processor The issuer (e.g. Bank) of the card used is in the processor’s blacklist (for card payments) T1 PA, SL, RI, RC, RB, CR, AV
44018 Card Country is Blacklisted by the Processor The card used is from a country in the processor’s blacklist (for card payments) T1 PA, SL, RI, RC, RB, CR, AV
44019 Payment Account Country is Blacklisted by the Processor The payment account used is from a country in the processor’s blacklist (for APMs/Wires) T1 PA, SL, RI, RC, RB, CR, AV
44020 IP Country is Blacklisted by the Processor The customer’s IP address is from a country in the processor’s blacklist T1 PA, SL, RI, RB, CR, AV
44021 Email Domain is Blacklisted by the Processor The customer’s email address domain is in the processor’s blacklist T1 PA, SL, RI, RC, RB, CR, AV
44030 Transaction Exceeds Processor’s Volume Limit per Brand/Merchant The total volume of transactions exceeds the processor’s limit for this brand/merchant T1 PA, SL, RI, RC, RB, CR
44031 Transaction Exceeds Processor’s Count Limit per Brand/Merchant The total number of transactions exceeds the processor’s limit for this brand/merchant T1 PA, SL, RI, RC, RB, CR
44032 Transaction Exceeds Processor’s Volume Limit per Customer The total volume of transactions exceeds the processor’s limit for this customer T1 PA, SL, RI, RC, RB, CR
44033 Transaction Exceeds Processor’s Count Limit per Customer The total number of transactions exceeds the processor’s limit for this customer T1 PA, SL, RI, RC, RB, CR
44034 Refund Exceeds Processor Amount Limit The volume of refunds for this brand/merchant has exceeded the processor’s amount limit T1 RF
44035 Refund Exceeds Processor Count Limit The number of refunds for this brand/merchant has exceeded the processor’s count limit T1 RF
44036 Refund Exceeds Processor Amount Ratio The volume of refunds for this brand/merchant has exceeded the processor’s amount ratio (% of total sales) T1 RF
44037 Refund Exceeds Processor Count Ratio The number of refunds for this brand/merchant has exceeded the processor’s count ratio (% of total sales) T1 RF
44038 Payout Exceeds Processor Amount Ratio The volume of payouts for this brand/merchant has exceeded the processor’s amount ratio (% of total sales) T1 CR
44039 Payout Exceeds Processor Count Ratio The number of payouts for this brand/merchant has exceeded the processor’s count ratio (% of total sales) T1 CR
44050 Processor System Error A general system error occurred on the processor’s side or it could be temporarily down. If the problem persists, please contact support T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44051 Request to Processor Timed Out The processor does not respond within the given timeframe T0 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44052 Invalid Request Format Paragon has sent the processor a request in an invalid format T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44053 Missing Request Parameter Paragon has sent the processor a request without one or more mandatory parameters T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44054 Invalid Request Parameter Paragon has sent the processor a request with one or more parameters in an invalid format T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
44055 Invalid Action/Workflow The attempted transaction was is not possible within the current workflow (e.g. refund on a declined transaction) T1 RF, VD, CP, RC
44056 Invalid/Missing Transaction Reference The attempted transaction was is missing a required reference to another transaction or the provided reference is invalid T1 RF, VD, CP, RC
44057 Duplicate Transaction The processor has declined the transaction because it is a duplicate T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV

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.

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
45003 Declined Merchant The customer’s card issuer has declined the transaction because they have a (temporary or permanent) problem with the merchant and/or acquirer or because the transaction is not allowed for this type of card T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45004 Card Reported as Pick Up The customer’s card issuer has declined the transaction because it was attempted using a card the issuer would like back, typically because the account is closed, but this can also mean the card is reported as stolen or lost T3 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45005 Do Not Honour A generic decline meaning that card issuer is unwilling to authorise the transaction and does not provide any additional information as to why T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45012 Invalid Transaction The transaction is not authorized due to critical technical issues or restrictive card usage by the Issuer T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45014 Wrong Card Number The customer’s card issuer has declined the transaction because they cannot match the card number to any active account T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45015 No Such Issuer Generated by Visa STIP services when there is no associated BIN to the processed account number. T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45041 Card Reported as Lost The customer’s card issuer has declined the transaction because it was attempted using a card that has been reported as lost T3 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45043 Card Reported as Stolen The customer’s card issuer has declined the transaction because it was attempted using a card that has been reported as stolen T3 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45051 Insufficient Funds The customer’s card issuer has declined the transaction because the transaction amount exceeds the amount available to the customer T3 PA, SL, CP, RC, RI, RB
45054 Wrong Expiry Date The customer’s card issuer has declined the transaction because the expiry date provided is incorrect. Check that the expiry date is correct, and attempt the transaction again T2 PA, SL, RC, RI, RB, CR, AV
45055 Wrong CVV The customer’s card issuer has declined the transaction because the CVV provided is incorrect. Check that the CVV is correct, and attempt the transaction again T2 PA, SL, RI, RB, AV
45057 Transaction not permitted to cardholder A generic decline meaning that card issuer is unwilling to authorise the transaction and does not provide any additional information as to why T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45059 Suspected Fraud – Issuer The customer’s card issuer has declined the transaction because they suspect it is fraudulent T2 PA, SL, CP, RF, VD, RC, RI, RB, CR
45060 Cancel Recurring Contract Cancel Recurring Contract T2 PA, SL, CP, RF, VD, RC, RI, RB, CR
45062 Restricted Card A Restriction is placed at the cardholder (account) level and not at the BIN (product) level. T2 PA, SL, CP, RF, VD, RC, RI, RB, CR
45078 No Account The account is cancelled, or inactive. T2 PA, SL, CP, RF, VD, RC, RI, RB, CR
45093 Transaction Cannot be Completed Due to government, central bank or financial institution agreement, laws or regulations, these types of transactions cannot be authorized. T2 PA, SL, CP, RF, VD, RC, RI, RB, CR
45094 Duplicate Transaction The customer’s card issuer has declined the transaction because it is a duplicate T2 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
45096 Issuer System Error Communication between the processor and issuer failed. If the problem persists, please contact support T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV

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.

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
46001 System Error A general system error occurred. If the problem persists, please contact support T1 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV, CB, FR, RQ, RP, PR, AR, C2
46002 System Currently Down The system is currently down for maintenance T1 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV, CB, FR, RQ, RP, PR, AR, C2
46003 Request Timed Out The system does not respond within the given timeframe T1 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV
46010 Inactive Merchant/Terminal The MID(s) and/or terminal(s) are inactive and cannot accept transactions T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
46011 Unsupported Payment Method/Type The card brand or payment method used by the customer is not supported/configured T1 PA, SL, RI, RB, CR, AV
46012 Unsupported Currency Type The currency type requested is not supported/configured T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV
46013 Unsupported Environment Type The transactional environment you are trying to use is not supported/configured T1 PA, SL, CP, RF, VD, RC, RI, RB, CR, AV

Unknown (90)

CODE DESCRIPTION EXPLANATION TYPE VALID FOR
90001 Status Unknown A general error occurred that cannot be classified yet T1 PA, SL, CP, RF, VD, RC, RI, RB, TK, DT, CR, AV, CB, FR, RQ, RP, PR, AR, C2

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

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:

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