3. Definitions
Throughout this document, the following definitions are used:
Acquirer – (also known as an ‘Acquiring Bank’) refers to a financial institution that processes card payments from a particular Card Scheme on behalf of a Merchant.
Alternative Payment Method (APM) – refers to a collective term used to designate any type of payment method that falls outside the scope of Card Payments. This typically includes the following types of payment methods: Offline Credit Transfers, Direct Debits, E-Wallets, Vouchers, Carrier-Billing Mobile Payments, and Crypto Payments.
Application Programming Interface (API) – refers to a computer interface that allows different applications to communicate with one another, access and share data.
Card Scheme – (also known as ‘Card Association’) refers to a payment network linked to payment cards. Examples of Card Schemes include: Visa, Mastercard, American Express, UnionPay, etc.
Integration – refers to a term used to describe the processes and activities needed to connect two separate technological systems to each other so they can communicate with one another, access and share data.
Issuer – (also known as ‘Issuing Bank’) refers to a financial institution that issues Card Scheme branded payment cards such as credit cards, debit cards and prepaid cards directly to consumers.
Merchant – refers to any entity (store, restaurant, etc.) that accepts payments in exchange for providing a customer with goods and/or services.
Merchant Account – refers to an account with a Payment Services Provider (PSP) that enables a business to accept payments in a variety of methods from its customers. A Merchant Account is typically payment method specific (meaning that it supports particular payment types and not others).
Merchant Category Code (MCC) – refers to a four-digit number listed in ISO 18245 which is used to classify a business by the type(s) of goods and/or services it provides.
4. Transaction Types
Currently, Paragon supports the following transaction types:
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 |
RA |
Risk-Alert | 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:
Please note that for a Rebill you will need to follow a few steps:
1. Process a successful Sale or Capture Transaction.
2. Generate a Token, see section 7.
3. Make sure to add the following key and value, in the headers tab:
Key: control-key
Value: The generated SHA-1 from the following details- ENDPOIND_ID+Login+Merchant_Control (for help creating the SHA-1, see Section 11)
5.5.1 Rebill API URL
Rebill transactions are initiated by sending a POST request to the following URL:
https://channel.paragon.online/v2/rebill/ENDPOINTID
Make sure to send the request with the parameters in the “Body” Tab, under “RAW” using JSON. See example:
Rebill Request Example:
java { "client_orderid": "101", "payment_token": "691418ae-3e8a-4fbc-b4fb-8a94c124fafb", "order_desc": "Tasty Test", "amount": "39.00", "currency": "EUR", "ipaddress": "10.10.10.1", "site_url": "www.google.com", "purpose": "Testing Tasty Tests", "redirect_url": "http%3a%2f%2fdoc.fibonatix.com%2fdoc%2fdummy.htm", "server_callback_url": "https://whereeveryouwouldliketo.callbacks.justchoose", "cell_phone": "3636363636" }
5.5.2 Rebill Request Parameters
Parameter Length/Type Description Stipulation client_orderid
48/String Brand/Merchant’s Transaction ID Mandatory order_desc
256/String Brand/Merchant’s Transaction Description Conditional payment_token
36/String The Token created in the original transaction Mandatory amount
10/Numeric Transaction Amount (i.e., 10.5 = £10.5)¹ Optional currency
3/String Transaction Currency (per ISO 4217) Mandatory cvv2
3-4/Numeric The Customer’s credit/debit card security code Conditional ipaddress
48/String Customer’s IP address Mandatory
¹ If no amount is stated, the Rebill will be for the full sum of the original Transaction.
5.5.3 Rebill Response Parameters
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
¤cy=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) | Optional |
recurring_date_type |
8/String | The type of recurring payment, such as: Day, week, month, year | Optional |
time_interval |
8/String | The number of time intervals (day,month,year- as indicated in previous field) between each recurring payment | Optional |
number_of_payments |
4/Numeric | The number of overall recurring payments | Optional |
¹. 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:
Tier 0 (T0)
– includes temporary declines and declines due to invalid or missing data from the merchant. This can be resolved by simply retrying the transaction or verifying the data and retrying.Tier 1 (T1)
– if you are sure that the transaction data provided is correct and you are still getting declines of this type, we recommend contacting a member of staff at Fibonatix to resolve the matter (either support or the relevant Account Manager).Tier 2 (T2)
– declines of this type require the cardholder/account holder to contact their card issuer/payment account provider and ascertain what was the reason for the decline and what can be done about it.Tier 3 (T3)
– if you are sure that the transaction data provided is correct and you are still getting declines of this type, we recommend using a different card/payment means.
Received (10)
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:
- Do NOT change any ID or name in a field which is designated as ID or Button.
- Do NOT delete the JavaScript document provided by Fibonatix.
- Due to security concerns, do NOT use CDN.
- 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.
- 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.
- All Customer Payment Pages must include the relevant credit card companies' logos.
- All Customer Payment Pages must include the customer' address.
- All Customer Payment Pages must include a Descriptor, which cannot be deleted or omitted.
Payment Page Example
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Pragma" content="no-cache" />
<base href="$!URL_PAYMENT_PAGE" />
<meta http-equiv="Expires" content="-1" />
<meta http-equiv="Content-Security-Policy" content="default-src *; img-src *; media-src *; script-src * localhost; style-src * localhost;style-src-elem * localhost;" />
<title>Custom payment page</title>
<script type="text/javascript" src="https://cdn.paragon.online/scripts/ccform.js?v=1.86"></script>
</head>
<body>
<div class="container">
<form action="" method="post">
<div class="form-container">
<div class="form-content">
<div class="top-title">
<b>Your Credit Card Will Be Charged By:</b><br />
<span class="descriptor">$!DESCRIPTOR</span>
</div>
<div class="validation-error" id="valdiation_error"></div>
<div class="form-label">
Card number<span class="form-label-comment">The 13-19 digits on the front of your card</span>
</div>
<input class="credit_card_number-field" id="credit_card_number" name="credit_card_number" type="text" maxlength="19" autocomplete="off" />
<div class="form-label-nobottom">
<span class="form-label-expiration">Expiration date</span>
<span class="form-label-cvv">Card verification value</span>
</div>
<div class="form-label-notop">
<span class="form-label-expiration">
<select class="expiry-month" name="expire_month" id="expire_month" size="1" >
<option value="01">January</option>
<option value="02">February</option>
<option value="03">March</option>
<option value="04">April</option>
<option value="05">May</option>
<option value="06">June</option>
<option value="07">July</option>
<option value="08">August</option>
<option value="09">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12">December</option>
</select>
<select class="expiry-year"name="expire_year"id="expire_year" size="1"></select>
</span>
<span class="form-label-cvv">
<input class="card-verification-value" name="cvv2" id="cvv2" type="text" maxlength="4" autocomplete="off"/>
<span class="form-label-comment-cvv">
The last 3 digits displayed on the back of your card
</span>
</span>
</div>
<div class="form-label">Full Name on a Card</div>
<input
class="card-holder-name"
name="card_printed_name"
id="card_printed_name"
type="text"
maxlength="64"
/>
<div class="legal">$!LEGAL</div>
</div>
<div class="ssl-footer">You will be charged $!AMOUNT $!CURRENCY</div>
</div>
<input class="form-submit" name="bSubmit" id="bSubmit" type="button" value="Complete Transaction" />
<input type="hidden" name="serial_number" id="serial_number" value="$!SERIAL"/>
<input type="hidden" name="endpointid" id="endpointid" value="$!ENDPOINTID"/>
<input type="hidden" name="action" id="action" value="sale-form/pay" />
</form>
</div>
</body>
</html>
11. Integration Helpers
- The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
## 11.1 SHA-1 Overview This page allows you to generate SHA-1 signatures using a known good SHA-1 library,https://code.google.com/archive/p/crypto-js/downloads
. This way you can quickly identify if INVALID_CONTROL_CODE error received from the Fibonatix API server is due to a bad signature or another issue.
To reproduce your API call, input all of the data from your original request. An SHA-1 signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your SHA-1 signature code.
11.2 Control parameter
The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters’ values in the following order:
- ENDPOINTID
- client_orderid
- minimal monetary units amount (i.e. cent, penny etc.)
- merchant_control
A complete string example may look as follows:
[email protected]
Encrypt the string using SHA-1 algorithm, which can be found free online, such as: http://www.sha1-online.com/
The resultant string yields the control parameter which is required for request authorization.
For the above-mentioned example the control will take the following value:
d02e67236575a8e02dea5e094f3c8f12f0db43d7
11.3 Testing Integration in Sandbox Environment
Once a merchant finishes his Integration with the API, he can use these following cards in the Sandbox Environment (Credetials and access will be provided by the Merchant's Account Manager):
Card Number: 4111111111111111
Expiration: 01/2026
CCV: 123
Card Number: 4111110000000211
Expiration: 01/2026
CCV: 123