Card Payment API
Contents
- 1. Sale Transactions
- 1.1 General Sale Process Flow
- 1.2 Process Sale transaction
- 1.2.1 Sale transaction request URL
- 1.2.2 Sale Request Parameters
- 1.2.3 Sale Response
- 1.2.4 3D redirect
- 1.2.5 Server callback result
- 1.2.6 Sale request authorization through control parameter
- 1.3 Payment Form Integration
- 1.3.1 Payment Form API URL
- 1.3.2 Form Transaction by ENDPOINTID
- 1.3.3 General Payment Form Process Flow
- 1.3.4 Payment form fields
- 1.3.5 Payment Form Request Parameters
- 1.3.6 Payment Form Response
- 1.4 rebill
- 2. Refund Transactions
- 3. Preauth/Capture Trаnsactions
- 4. Recurring init Transactions
- 5. Order status
- 6. Common Utilities
- 6.1 Merchant Callbacks
- 6.1.1 Callback simple URL
- 6.1.2 Sale, Refund Callback Parameters
- 6.1.3 Sale, Refund, Chargeback customizable callback URL
- 6.1.4 Sale, Refund Callback Macros
- 6.1.5 Callback authorization through control parameter
- 6.1.6 Callback to Status Parameters Mapping
- 6.1.7 Callback Signature check example on Java
- 7. Reference
- 8. Integration Helpers
1. Sale Transactions
General Sale Process Flow
Merchant initiates a transaction by sending HTTPS POST request to the specified URL Fibonatix server immediately returns the response back to Merchant. The response contains paynet-order-id. For detailed request and response format see Sale Request Parameters Table Merchant shows the Customer message like Your order is being processed. Please, wait…. Merchant starts polling Fibonatix server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in Order status asynchronous call Fibonatix Server determines if 3D is required or not and drives the transaction authorization process as appropriate. Merchant is using single entry point for both 3D and Non 3D Sale transactions. Actually the Merchant can not know beforehand if the sale will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described below.
checkout order Customer checks out the order on Merchant’s website
process sale
Merchant sends Sale request to Fibonatix server with specified parameters described in Sale Request Parameters. Merchant must make sure redirect_url is passed. This is the URL the Customer will be redirected after 3D transaction is processed. redirect_url is not used if the transaction goes through Non 3D process.
order status=processing
Fibonatix Server immediately returns response with order status processing. See details at Sale Response
Get Order status
Merchant starts polling Fibonatix server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in Order status asynchronous call.
3D status required?
Fibonatix Gateway determines if 3D authorization required for the incoming sale transaction.
non 3D sale process
In case the gate is Non 3D Fibonatix returns empty html parameter and Merchant should keep polling Fibonatix server until approved or declined status is returned. See Non 3D Sale transaction diagram for details.
3D sale process
In case the gate is 3D Fibonatix returns non-empty html parameter Merchant should follow 3D sale process starting from step 5 described in 3D Sale transaction diagram.
Non 3D Sale transaction diagram
Merchant is using single entry point for both 3D and Non 3D Sale transactions. Actually the Merchant can not know beforehand if the Sale will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described in General Sale Process Flow.
3D Sale transaction diagram
Merchant is using single entry point for both 3D and Non 3D Sale transactions. Actually the Merchant can not know beforehand if the Sale will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described in General Sale Process Flow.
Process Sale transaction
Sale transactions are initiated through HTTPS POST request by using URL in the following format:
Sale transaction request URL
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v1/payment/ENDPOINTID
– for sale transaction
Sale Request Parameters
In order to initiate a Sale transaction Merchant sends an HTTPS POST request with the parameters specified in Sale Request Parameters Table below
Sale Request 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
&cell_phone=%2B19023384543
&amount=10.42
&email=john.smith@gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=www.twitch.tv/dreadztv
&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
Sale Request Parameters | Length/Type | Comment | Necessity |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier. | Mandatory |
order_desc |
64k/String | Brief order description | Conditional |
card_printed_name |
128/String | Card printed name | Mandatory |
first_name |
50/String | Customer’s first name | Mandatory |
last_name |
50/String | Customer’s last name | Mandatory |
ssn |
200/Numeric | Last four digits of the customer’s social security number. | Optional |
birthday |
200/Numeric | Customer’s date of birth, in the format YYYYMMDD. | Optional |
address |
150/String | Customer’s address line 1. | Optional |
city |
50/String | Customer’s city. | Optional |
state |
2-3/String | Customer’s state . Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
zip_code |
16/String | Customer’s ZIP code | Optional |
country |
2/String | Customer’s country(two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes. | Mandatory |
phone |
200/String | Customer’s full international phone number, including country code. | Optional |
cell_phone |
200/String | Customer’s full international cell phone number, including country code. | Optional |
email |
200/String | Customer’s email address. | Mandatory |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
credit_card_number |
20/Numeric | Customer’s credit card number. | Mandatory |
expire_month |
2/Numeric | Credit card expiration month | Mandatory |
expire_year |
4/Numeric | Credit card expiration year | Mandatory |
cvv2 |
3-4/Numeric | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
site_url |
1024/String | URL the original Sale is made from. | Optional |
purpose |
200/String | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; [email protected] etc. This value will be used by fraud monitoring system. | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details. | Mandatory |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non3D schema for transactions processing and you have no need to return customer anywhere. | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
merchant_data |
64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. | Optional |
dapi_imei |
32/String | Unique device identifier | Optional |
- acquirer can redefine the necessity of some fields so they become mandatory instead of optional
- leading and trailing whitespace in input parameters will be omitted
Please note the following characters must be escaped in the parameter values: &
+
“
.
Sale Response
Sale Response Example:
type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935-end-point-id=223
Sale Response Parameters | Description |
---|---|
type |
The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
paynet-order-id |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
by-request-sn |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
error-message |
If status is error this parameter contains the reason for decline or error details |
error-code |
The error code is case of error status |
3D redirect sale
If your gate supports 3D Secure you need to send status request and process html return parameter to send customer to 3D Secure Authorisation. The simplified schema looks like:
html
field is always present for 3D gates in status response, whether clients card supports 3D Secure or not.
Upon completion of 3D authorization process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.
3D redirect Parameter | Description |
---|---|
status |
See Status List for details. |
orderid |
Order id assigned to the order by Fibonatix |
merchant_order |
Merchant order id |
client_orderid |
Merchant order id |
error_message |
If status is declined or error this parameter contains the reason for decline or error details |
control |
Checksum used to ensure that it is Fibonatix (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control. |
descriptor |
Gate descriptor |
If Merchant has passed server_callback_url in original Sale request Fibonatix will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters
Server callback results
Server callback result example:
status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65
Upon completion by the System of 3D request processing it returns the result on the specified server_callback_url with the parameters described in Merchant Callbacks
The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:
status
orderid
client_orderid
merchant_control
A complete string example may look as follows:
approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:
e04bd50531f45f9fc76917ac78a82f3efaf0049c
All parameters are sent via GET method.
Sale request authorization through 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. The resultant string yields the control parameter (see Sale Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:
d02e67236575a8e02dea5e094f3c8f12f0db43d7
Payment Form Integration
Payment Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification). In case of Payment Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the Fibonatix gateway side. In addition merchant may customize the look and feel of the Payment Form. Merchant must send the template to his/her Manager for approval before it could be used.
Payment Form API URL
Payment Form transactions are initiated through HTTPS POST request by using URL in the following format:
Form Transaction by ENDPOINTID
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v2/sale-form/ENDPOINTID
- for sale - Payment page transactions
https://channel.paragon.online/v2/preauth-form/ENDPOINTID
- for preauth transactions
General Payment Form Process Flow
Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be either /sale-form/ENDPOINTID or /preauth-form/ENDPOINTID depending which transaction SMS or DMS should be accomlished.
Fibonatix gateway returns response which contains an additional parameter redirect-url. This is the URL where merchant must redirect Customer’s browser to.
See details about response format in Payment Form Response.
Merchant sends HTTP 302 redirect to Customer’s browser using URL which is obtained from the redirect-url response parameter.
Customer fills in payment details and submits the Payment Form.
Fibonatix gateway processes the transaction according to 3D or Non 3D process.
When sale authorization is completed Fibonatix gateway redirects the Customer’s browser to redirect_url request parameter provided by merchant in the original request accomplished at step 2. See details in Payment Form final redirect.
Payment form fields
This form contains the following fields:
Form field name | Description |
---|---|
credit_card_number |
Customer’s credit card number 4455555555555544 |
expire_month |
Credit card expiration month 01 or 12 |
expire_year |
Credit card expiration year 2016 |
cvv2 |
Card security code 432 |
card_printed_name |
Card printed name |
Payment Form Request Parameters
Request parameter name | Length/Type | Comment | Necessity* |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier. | Mandatory |
order_desc |
64k/String | Brief order description | Conditional |
first_name |
50/String | Customer’s first name | Mandatory |
last_name |
50/String | Customer’s last name | Mandatory |
ssn |
200/Numeric | Last four digits of the customer’s social security number. | Optional |
birthday |
200/Numeric | Customer’s date of birth, in the format YYYYMMDD. | Optional |
address1 |
150/String | Customer’s address line 1. | Optional |
city |
50/String | Customer’s city. | Optional |
state |
2/String | Customer’s state (two-letter state code). Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
zip_code |
16/String | Customer’s ZIP code | Optional |
country |
2/String | Customer’s country(two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes. | Mandatory |
phone |
200/String | Customer’s full international phone number, including country code. | Mandatory |
cell_phone |
200/String | Customer’s full international cell phone number, including country code. | Optional |
email |
200/String | Customer’s email address. | Mandatory |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
site_url |
1024/String | URL the original sale is made from. | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details. | Mandatory |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
preferred_language |
2/String | Customer’s two-letter language code for multi-language payment forms | Optional |
- acquirer can redefine the necessity of some fields so they become mandatory instead of optional
- leading and trailing whitespace in input parameters will be omitted
Payment Form Response
Response parameter name | 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 |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
serial-number |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
error-message |
If status is declined or error this parameter contains the reason for decline or error details |
error-code |
The error code in case of declined or error status |
redirect-url |
The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow |
Rebill
Rebill API URL
Rebill transactions are initiated through HTTPS POST request by using URL in the following format:
Create a token
Create a token response Example:
is-valid=true,
&token=f7efc7a3-62ce-485e-b926-12d868a8e1af
The Serial Number is from the transactions in status approved to make rebill on them.
https://channel.paragon.online/v2/Token/create-fromsn/SerialNumber
- To create a Token for transactions
Rebill by ENDPOINTID
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v2/rebill/ENDPOINTID
- for Rebill transactions
Rebill Request Parameters
In order to initiate a Rebill transaction Merchant sends an HTTPS POST request with the parameters specified in Rebill Request Parameters Table below
Rebill Request Example:
client_orderid=902B4FF5
&order_desc=Test Order Description
&amount=10.42
¤cy=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&cvv2=123
&purpose=www.twitch.tv/dreadztv
&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
&payment_token=7e929225-a110-4353-acbb-edd636875dcd
Rebill Request Parameters | Length/Type | Comment | Necessity |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier. | Mandatory |
order_desc |
64k/String | Brief order description | Conditional |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
cvv2 |
3-4/Numeric | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
site_url |
1024/String | URL the original Sale is made from. | Optional |
purpose |
200/String | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; [email protected] etc. This value will be used by fraud monitoring system. | Optional |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non3D schema for transactions processing and you have no need to return customer anywhere. | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
merchant_data |
64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details. | Mandatory |
payment_token |
40/String | Generated token for transaction to make rebill for it | Mandatory |
Rebill Response
Rebill Request Example:
type=async-response
&paynet-order-id=INI30VnZ
&merchant-order-id=9229e21d-33b1-4e66-9d3a-1bbd8ee11c53
&serial-number=AkHfpKeO
Response parameter name | 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 |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
serial-number |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
2. Refund Transactions
Refund transaction diagram
Refund request
Merchant sends Refund request to Fibonatix server with specified parameters described in Refund request Parameters.
Order ID
Fibonatix server sends back the response. Merchant starts polling for status with given orderid as described in Order status asynchronous call.
Process refund
Fibonatix server determines the actual type of Return transaction(Cancel or Reversal) depending o the type of initial sale transaction. Fibonatix server forwards the appropriate request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id
Merchant is polling for status with given orderid as described in Order status asynchronous call.
Processing result
The bank responds to Fibonatix server with approve or decline for requested return transaction.
Final Status
Fibonatix server returns status to Merchant through Order status asynchronous call.
Process Refund transaction
Refund API call returns money back to the customer. For Preauth it makes Cancel transaction, for Capture and Sale – Reversal. Void API call excludes transaction from clearing. Void transaction is always the result of this call. Void might not be supported by your acquirer, ask manager for detalies. Return and Void API calls are initiated through HTTPS POST request by using URL in the following format:
Refund transaction request URL
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v1/Refund/ENDPOINTID
– for Refund transaction
https://channel.paragon.online/v1/void/ENDPOINTID
– for void transaction
Refund request Parameters
Refund request Parameter | Length/Type | Comment | Necessity* |
---|---|---|---|
login |
20/String | Merchant login name | Mandatory |
orderid |
20/String | Unique identifier of Sale (SMS) or Preauth/Capture (DMS) order assigned by Fibonatix system and returned in the orderidresponse parameter. Please note that return can be made On a preauth transaction if the relative capture transaction has not taken place yet; or on a capture transaction. In the latter case, processing of a return on a preauth transaction is restricted. | Mandatory |
client_orderid |
128/String | Unique merchant identifier of Sale (SMS) or Preauth/Capture (DMS) transaction which is send to Fibonatix system in theclient_orderid parameter. | Mandatory |
by-request-sn |
50/String | Unique number assigned by Fibonatix server to particular request from the Merchant. | Mandatory |
amount |
10/Numeric | This optional parameter specifies amount to be reversed. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that you MUST specify currency if you specify amount! Not supported for void transactions | Mandatory |
currency |
3/String | Currency in which amount is specified (three-letter currency code). Valid parameter values are: USD for US Dollar EUR for European Euro. Not supported for void transactions | Mandatory |
control |
40/String | Checksum used to ensure that it is Merchant (and not a fraudster) that initiates the Refund request. This is SHA-1 checksum of the concatenation login + client_orderid + orderid + merchant-control if amount is not specified, and login + client_orderid + orderid + amount_in_cents + currency + merchant-control if amount is specified. | Mandatory |
comment |
50/String | A brief description of reason | Mandatory |
Please note the following characters must be escaped in the parameter values: &
+ “
.
Refund Response
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
Return Response Parameter | Description |
---|---|
type |
The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
status |
See Status List for details. |
paynet-order-id |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
by-request-sn |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
error-message |
If status is error this parameter contains the reason for decline or error details |
error-code |
The error code is case of error status |
3. Preauth/Capture Trаnsactions
Preauth Transaction General Flow
Merchant Site initiates a Pre-auth transaction by sending corresponding HTTPS POST request to the specified URL
The System processes the transaction and sends corresponding response (depending on 3D/Non-3D processing type). Upon successful completion of a preauth transaction the bank blocks the specified amount in the credit card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
Merchant sends Capture transaction in order to deduct the locked amount from credit card.
System processes capture transaction and returns corresponding response. In this case the money is actually transferred from the bank-issuer account to the bank-acquirer account, which means the end of the transaction.
Merchant is using single entry point for both 3D and Non 3D Preauth transactions. Actually the Merchant can not know beforehand if the sale will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described below.
Checkout order
Customer checks out the order on Merchant’s website
Process Preauth
Merchant sends Preauth request to Fibonatix server with specified parameters described in Preauth Request Parameters. Merchant must make sure edirect_url is passed. This is the URL the Customer will be redirected after 3D transaction is processed. redirect_url is not used if the transaction goes through Non 3D process.
Order status = processing
Fibonatix Server immediately returns response with order status processing. See details at Preauth Response
Get Order status
Merchant starts polling Fibonatix server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in Order status asynchronous call
Is 3D auth required?
Fibonatix Gateway determines if 3D authorization required for the incoming sale transaction.
Non 3D Preauth process
In case the gate is Non 3D Fibonatix returns empty html parameter and Merchant should keep polling Fibonatix server until approved or declined status is returned. See Non 3D Preauth transaction diagram for details.
3D Preauth process
In case the gate is 3D Fibonatix returns non-empty html parameter Merchant should follow 3D sale process starting from step 5 described in 3D Preauth transaction diagram.
Non 3D Preauth transaction diagram
Merchant is using single entry point for both 3D and Non 3D Preauth transactions. Actually the Merchant can not know beforehand if the Preauth will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described in General Preauth Process Flow.
Preauth request
Customer checks out the order and Merchant sends Non 3D Preauth request to Fibonatix server with specified parameters described in Preauth Request Parameters.
Order Id
Fibonatix server sends back the response with orderid. Merchant shows the customer a message like Your order is being processed. Please, wait… and starts polling for status with given orderid as described in Order status asynchronous call.
Process Preauth
Fibonatix server forwards Preauth request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id
Merchant is polling for status with given orderid as described in Order status asynchronous call.
Preauth approved or declined
The bank responds to Fibonatix server with approve or decline for requested Preauth
Return Status – approved or declined
Fibonatix server returns status to Merchant through Order status asynchronous call.
3D Preauth transaction diagram
Merchant is using single entry point for both 3D and Non 3D Preauth transactions. Actually the Merchant can not know beforehand if the Preauth will be driven through 3D authorization scheme. The Merchant should use Fibonatix API as described in General Preauth Process Flow.
Checkout order
Customer checks out the order on Merchant’s website Process 3D Preauth. Merchant sends 3D Preauth request to Fibonatix server with specified parameters described in Preauth Request Parameters. Merchant must make sure redirect_url is passed. This is the URL the Customer will be redirected after transaction is processed.
Get auth form
Fibonatix server requests 3D authentication form from the Issuer Bank
Return 3D form HTML
Issuer Bank returns HTML to 3D extra authentication form from the Issuer Bank to Fibonatix server
Return 3D response with auth form
Fibonatix server returns response including auth form HTML to Merchant. See details at Preauth Response
Show 3D form to customer
Merchant shows Customer Issuer Bank’s extra authentication form
Customer submits additional auth information
Customer follows Issuer Bank’s process to provide additional authorization information. The most usual way it’s accomplished is sending SMS message with a secret code to customer’s mobile phone which number is known to Issuer Bank. Customer then supplies this secret code through the auth form.
Authorized
The Issuer Bank verifies that extra authorization information supplied by the Customer is correct and replies back to Fibonatix server.
Process Preauth
Fibonatix server forwards Preauth request to bank acquirer. The bank starts processing the transaction.
Preauth approved or declined
The bank responds to Fibonatix server with approve or decline for requested Preauth
Show auto-submit order form
Fibonatix server creates order and redirects customer’s browser to auto-submit form with supplied order id. The form’s action is redirect_url passed at step 2.
Auto-submit form with order id
and status Customer’s browser automatically submits the form with order id and status to Merchant’s redirect_url passed at step 2. Status may be either approved or declined
Process Preauth transaction
Preauth transactions are initiated through HTTPS POST request by using URL in the following format:
Preauth transaction by ENDPOINTID
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v1/preauth/ENDPOINTID
– for pre-auth transaction
Preauth Request Parameters
Preauth Request Example:
client_orderid=123098
credit_card_number=XXXX XXXX XXXX XXXX
expire_year=2012
expire_month=8
cvv2=XXX
amount=114.94
control=b78f3420dasdef50469a6fd40c7625cd5a1f05eba
card_printed_name=Francis Benedict
ipaddress=115.135.52.242
state=
currency=USD
phone=+6072344354
zip_code=81200
order_desc=Super product 1
email=francislusaikun@yahoo.com
country=MY
city=Johor Bahru
address1=11Jalan Lurah 6 Kg. Kempas Baru
&merchant_data=VIP customer
In order to initiate a Preauth transaction Merchant sends an HTTPS POST request with the parameters specified in Preauth Request Parameters Table below
Preauth Request Parameter | Length/Type | Comment | Necessity* |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier. | Mandatory |
order_desc |
64K/String | Brief order description | Conditional |
card_printed_name |
128/String | Card printed name | Mandatory |
first_name |
50/String | Customer’s first name | Mandatory |
last_name |
50/String | Customer’s last name | Mandatory |
ssn |
200/Numeric | Last four digits of the customer’s social security number. | Optional |
birthday |
200/Numeric | Customer’s date of birth, in the format YYYYMMDD. | Optional |
address1 |
150/String | Customer’s address line 1. | Optional |
city |
50/String | Customer’s city. | Optional |
state |
2-3/String | Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia. | Conditional |
zip_code |
16/String | Customer’s ZIP code | Optional |
country |
2/String | Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. | Mandatory |
phone |
200/String | Customer’s full international phone number, including country code. | Optional |
cell_phone |
200/String | Customer’s full international cell phone number, including country code. | Optional |
email |
200/String | Customer’s email address. | Mandatory |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
credit_card_number |
20/Numeric | Customer’s credit card number. | Mandatory |
expire_month |
2/Numeric | Credit card expiration month | Mandatory |
expire_year |
4/Numeric | Credit card expiration year | Mandatory |
cvv2 |
3-4/Numeric | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
site_url |
1024/String | URL the original Preauth is made from. | Optional |
purpose |
200/String | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; [email protected] etc. This value will be used by fraud monitoring system. | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details. | Mandatory |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non3D schema for transactions processing and you have no need to return customer anywhere. | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect Preauth data in Merchant’s database. See more details at Merchant Callbacks | Optional |
merchant_data |
64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. | Optional |
- acquirer can redefine the necessity of some fields so they become mandatory instead of optional
- leading and trailing whitespace in input parameters will be omitted
Please note the following characters must be escaped in the parameter values: &
+ “
.
Preauth Response
Preauth Response Example:
type=async-response
&by-request-sn=00000000-0000-0000-0000-000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
Preauth Response Parameter | Description |
---|---|
type |
The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
paynet-order-id |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
by-request-sn |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
error-message |
If status is error this parameter contains the reason for decline or error details |
error-code |
The error code is case of error status |
3D redirect preauth
If your gate supports 3D Secure you need to send status request and process html return parameter to send customer to 3D Secure Authorisation. The simplified schema looks like:
html
field is always present for 3D gates in status response, whether clients card supports 3D Secure or not.
Upon completion of 3D authorization process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.
3D redirect Parameter | Description |
---|---|
status |
See Status List for details. |
orderid |
Order id assigned to the order by Fibonatix |
merchant_order |
Merchant order id |
client_orderid |
Merchant order id |
error_message |
If status is declined or error this parameter contains the reason for decline or error details |
control |
Checksum used to ensure that it is Fibonatix (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control. |
descriptor |
Gate descriptor |
If Merchant has passed server_callback_url in original Preauth request Fibonatix will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters
Server callback result
Upon completion by the System of 3D request processing it returns the result on the specified server_callback_url with the following parameters described in Sale, Return Callback Parameters
The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:
Server callback result example:
status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65
- status
- orderid
- client_orderid
- merchant_control
A complete string example may look as follows:
approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:
e04bd50531f45f9fc76917ac78a82f3efaf0049c
All parameters are sent via POST method.
Process Capture Transaction
The Capture operation initiates after successful complete of the Preauth operation to deduct blocked amount from the customer’s card.
Capture Transaction by ENDPOINTID
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v1/capture/ENDPOINTID
– for capture transaction
Capture Request
Capture Request Parameter | Description |
---|---|
login |
Merchant login name |
client_orderid |
Merchant order identifier of the transaction for which the status is requested |
orderid |
Order id assigned to the order by Fibonatix |
by-request-sn |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
control |
Checksum used to ensure that it is Fibonatix (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + merchant-order-id + paynet-order-id + amount_in_cents(if sent) + currency(if amount sent) + merchant-control. |
Capture Response
Capture Response Example:
type=async-response
&by-request-sn=00000000-0000-0000-0000-000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
Capture Response Parameter | Description |
---|---|
type |
The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
paynet-order-id |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
by-request-sn |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
error-message |
If status is error this parameter contains the reason for decline or error details |
error-code |
The error code is case of error status |
4. Recurring init Transactions
Recurring payments are often referred to as autopay or subscription payments. Your customers give you authorisation to charge their card to pay for goods or services on a regular, recurring basis. Payments continue until the end of the billing term or until the customer cancels the service.
Recurring payments can be used to pay for any type of goods or services, for example: household bills, car loans, mortgage, rent, insurance and other monthly bills. In addition, the recurring payments functionality can be used for installment payments to make it easier for customers to pay for a higher ticket item over a period of time.
Process Recurring transaction
Sale transactions are initiated through HTTPS POST request by using URL in the following format:
Recurring transaction request 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
– for Recurring init transaction
https://channel.paragon.online/v2/recurring-form/ENDPOINTID
- for Recurring init-form transaction
Recurring init-Form Request Parameters
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
Recurring Request Parameters | Length/Type | Comment | Necessity |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier | Mandatory |
order_desc |
64k/String | Brief order description | Conditional |
card_printed_name |
128/String | Card printed name | Mandatory |
first_name |
50/String | Customer’s first name | Mandatory |
last_name |
50/String | Customer’s last name | Mandatory |
ssn |
200/Numeric | Last four digits of the customer’s social security number | Optional |
birthday |
200/Numeric | Customer’s date of birth, in the format YYYYMMDD | Optional |
address |
150/String | Customer’s address line 1 | Optional |
city |
50/String | Customer’s city | Optional |
state |
2-3/String | Customer’s state . Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
zip_code |
16/String | Customer’s ZIP/Postal code | Optional |
country |
2/String | Customer’s country (two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes | Mandatory |
phone |
200/String | Customer’s full international phone number, including country code | Optional |
email |
200/String | Customer’s email address | Mandatory |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes | Mandatory |
site_url |
1024/String | URL the original Sale is made from | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details | Mandatory |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non3D schema for transactions processing and you have no need to return customer anywhere | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
merchant_data |
64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback | Optional |
first_payment_date |
Date format DD.MM.YYYY | First date for payment | Mandatory |
recurring_date_type |
time type Day, Week or Month | The payment event interval type | Mandatory |
time_interval |
3/Numeric | The time between payment events | Mandatory |
number_of_payments |
3/Numeric | The number of payment events that would comprise the recurring cycle | Mandatory |
Recurring init Request Parameters
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
&credit_card=411111111111111
&expired_month= 08
&expired_year=1994
&cvv=123
&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
Recurring Request Parameters | Length/Type | Comment | Necessity |
---|---|---|---|
client_orderid |
128/String | Merchant order identifier | Mandatory |
order_desc |
64k/String | Brief order description | Conditional |
card_printed_name |
128/String | Card printed name | Mandatory |
first_name |
50/String | Customer’s first name | Mandatory |
last_name |
50/String | Customer’s last name | Mandatory |
ssn |
200/Numeric | Last four digits of the customer’s social security number | Optional |
birthday |
200/Numeric | Customer’s date of birth, in the format YYYYMMDD | Optional |
address |
150/String | Customer’s address line 1 | Optional |
city |
50/String | Customer’s city | Optional |
state |
2-3/String | Customer’s state . Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
zip_code |
16/String | Customer’s ZIP/Postal code | Optional |
country |
2/String | Customer’s country (two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes | Mandatory |
phone |
200/String | Customer’s full international phone number, including country code | Optional |
email |
200/String | Customer’s email address | Mandatory |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
credit_card_number |
20/Numeric | Customer’s credit card number | Mandatory |
expire_month |
2/Numeric | Credit card expiration month | Mandatory |
expire_year |
4/Numeric | Credit card expiration year | Mandatory |
cvv2 |
3-4/Numeric | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card | Mandatory |
currency |
3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
ipaddress |
20/String | Customer’s IP address, included for fraud screening purposes | Mandatory |
site_url |
1024/String | URL the original Sale is made from | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details | Mandatory |
redirect_url |
1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Fibonatix gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non3D schema for transactions processing and you have no need to return customer anywhere | Mandatory |
server_callback_url |
1024/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
merchant_data |
64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback | Optional |
first_payment_date |
Date format DD.MM.YYYY | First date for payment | Mandatory |
recurring_date_type |
time type Day, Week or Month | The payment event interval type | Mandatory |
time_interval |
3/Numeric | The time between payment events | Mandatory |
number_of_payments |
3/Numeric | The number of payment events that would comprise the recurring cycle | Mandatory |
Modify Recurring details
You can change details of a recurring transaction template (such as the payment details of a Spend Money transaction or the schedule of a recurring invoice) or edit the schedule.
If you need to change a recorded transaction, send POST request with the serial_number
of the Recurring transaction and the parameters that you want to modify:
https://channel.paragon.online/v2/modify-recurring/ENDPOINTID
- for Modify Recurring transaction
Recurring Request Parameters to modify Example:
&card_printed_name=John Smith
&amount=10.42
&credit_card=411111111111111
&expired_month= 08
&expired_year=1994
&cvv=123
&recurring_sn=sCVf15w58
Modify Recurring Request Parameters | Length/Type | Comment | Necessity |
---|---|---|---|
recurring_sn |
10/String | Unique number assigned by Fibonatix server to particular request from the Merchant | Mandatory |
number_of_payments |
3/Numeric | The number of payment events that would comprise the recurring cycle | Optional |
control |
40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details | Optional |
expire_year |
4/Numeric | Credit card expiration year | Optional |
expire_month |
2/Numeric | Credit card expiration month | Optional |
card_printed_name |
128/String | Card printed name | Optional |
credit_card_number |
20/Numeric | Customer’s credit card number | Optional |
amount |
10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Optional |
5. Order Status
The Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Fibonatix's server and the Order ID is returned, the Merchant should poll to receive the transaction status. When the transaction is processed on Fibonatix's server it returns the status back to the Merchant and at this moment the Merchant is ready to show the customer the transaction result, whether it’s approved or declined.
Status API URL
Status API calls are initiated through HTTPS POST request by using URL in the following format:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://channel.paragon.online/v1/status/ENDPOINTID
Order status call parameters
Status call parameters | Description |
---|---|
login |
Merchant login name |
client_orderid |
Merchant order identifier of the transaction for which the status is requested |
orderid |
Order id assigned to the order by Fibonatix |
by-request-sn |
Serial number assigned to the specific request by Fibonatix. If this field exist in status request, status response return for this specific request. |
control |
Checksum used to ensure that it is Fibonatix (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum. |
Order Status Response
Order Status Response Example:
type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
Status Response Parameter | Description |
---|---|
type |
The type of response. May be status-response |
status |
See Status List for details. |
amount |
Amount of the initial transaction. |
currency |
Currency of the initial transaction. |
paynet-order-id |
Order id assigned to the order by Fibonatix |
merchant-order-id |
Merchant order id |
phone |
Customer phone. |
html |
HTML code of 3D authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Customer. The Fibonatix System returns the following response parameters when it gets 3D authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3D this never happens. For 3D HTML has value after some short time after the processing has been started. |
serial-number |
Unique number assigned by Fibonatix server to particular request from the Merchant. |
last-four-digits |
Last four digits of customer credit card number. |
bin |
Bank BIN of customer credit card number. |
card-type |
Type of customer credit card (VISA, MASTERCARD, etc). |
gate-partial-reversal |
Processing gate support partial reversal (enabled or disabled). |
gate-partial-capture |
Processing gate support partial capture (enabled or disabled). |
transaction-type |
Transaction type (sale, reversal, capture, preauth). |
processor-rrn |
Bank Receiver Registration Number. |
processor-tx-id |
Acquirer transaction identifier. |
cardholder-name |
Cardholder name. |
card-exp-month |
Card expiration month. |
card-exp-year |
Card expiration year. |
card-hash-id |
Unique card identifier to use for loyalty programs or fraud checks. |
email |
Customer e-mail. |
bank-name |
Bank name by customer card BIN. |
terminal-id |
Acquirer terminal identifier to show in receipt. |
paynet-processing-date |
Acquirer transaction processing date. |
approval-code |
Bank approval code. |
order-stage |
The current stage of the transaction processing. See Order Stage for details. |
loyalty-balance |
The current bonuses balance of the loyalty program for current operation. if available |
loyalty-message |
The message from the loyalty program. if available |
loyalty-bonus |
The bonus value of the loyalty program for current operation. if available |
loyalty-program |
The name of the loyalty program for current operation. if available |
descriptor |
Bank identifier of the payment recipient. |
error-message |
If status in declined, error, filtered this parameter contains the reason for decline |
error-code |
The error code is case status in declined, error, filtered. |
by-request-sn |
Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn. |
verified-3d-status |
See 3d Secure Status List for details |
verified-rsc-status |
See Random Sum Check Status List for details |
Status request authorization through control parameter
The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Fibonatix. This SHA-1 checksum, the parameter control, is created by concatenation of these parameters values in the following order:
* login
* client_orderid
* orderid
* merchant_control
For example, assume these parameters have the values as listed below:
Parameter Name | Parameter Value |
---|---|
login |
cool_merchant |
client_orderid |
5624444333322221111110 |
orderid |
9625 |
merchant_control |
r45a019070772d1c4c2b503bbdc0fa22 |
The complete string example may look as follows:
cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:
c52cfb609f20a3677eb280cc4709278ea8f7024c
6. Common Utilities
Merchant Callbacks
When ENDPOINT is created for Merchant’s website callback URLs might be defined for any type of transaction type and transaction status.
These callback URLs will be called when the transaction is completed, whether approved, declined or reaching error or unknown state. This gives a Merchant better control how the transaction is processed on Merchant’s side, for example to add appropriate records to Merchant’s internal accounting system.
Please remember, callbacks are guaranteed to report merchant about transaction status. Merchants on their side must provide a means of preventing receiving the same callback twice - in case of network or other technical problems.
Callback simple URL
If you want to make sure that the customer has paid for the item, you should specify a callback URL. If you do, Fibonatix sends an HTTP GET message to the callback URL whenever a purchase completed, no metter if the result is approved or declined. Your server needs to answer this GET message 200 OK status RFC, or else Fibonatix will continue to send the callback 30 times for 14 days applying the progressive timeline. Simple form of Sale or Return callback is just an URL to Merchant’s target page or script without any parameters, for example https://www.i-cool-merchant.com/sale.php. You can use only following ports in callback URL:
- for HTTP 80, 8080
- for HTTPS 443, 8443
In this case the system automatically adds the following parameters to callback URL.
Sale, Refund Callback Parameters
Fibonatix Callback Parameter | Description |
---|---|
status |
See Status List for details. |
merchant_order |
Merchant order identifier, client_orderid |
client_orderid |
Merchant order identifier |
orderid |
Fibonatix transaction id |
type |
Transaction type, sale reversal chargeback |
amount |
Transaction amount |
currency |
Transaction currency |
descriptor |
Payment descriptor of the gate through which the transaction has been processed. |
error_code |
Error Code |
error_message |
Error Message |
name |
Cardholder Name |
email |
Customer’s email |
approval-code |
Authorization approval code, if any |
last-four-digits |
Last four digits of customer credit card number. |
bin |
Bank BIN of customer credit card. |
card-type |
Type of customer credit card (VISA, MASTERCARD, etc). |
phone |
Customer phone number. |
bank-name |
Customer bank name. |
card-exp-month |
Card expiration month. |
card-exp-year |
Card expiration year. |
gate-partial-reversal |
Processing gate support partial reversal (enabled or disabled). |
gate-partial-capture |
Processing gate support partial capture (enabled or disabled). |
reason-code |
Reason code for chargebak or fraud operation. |
processor-rrn |
Bank Receiver Registration Number. |
comment |
Comment in case of Return transaction |
rapida-balance |
Current balance for merchants registered in Rapida system (only if balance check active) |
control |
Checksum is used to ensure that it is Fibonatix (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum. |
merchantdata |
Reserved |
serial-number |
Serial number of the request. |
processor-tx-id |
Transaction id set by processor. |
processor-auth-credit-code |
Reserved |
card-hash-id |
Unique identifier of card. |
verified-3d-status |
Will return AUTHENTICATED if a transaction was approved by 3D. |
processor-credit-rrn |
Reference Retrieval Number set by acquirer. |
processor-credit-arn |
Acquirer card reference number for credit card. |
processor-debit-arn |
Acquirer card reference number for debit card. |
eci |
Electronic Commerce Indicator (Visa). |
ips-src-payment-product-code |
Code for card set by multinational financial service. (Visa/Mastercard). |
ips-src-payment-product-name |
Decrypted code for card set by multinational financial service. (Visa/Mastercard). |
ips-src-payment-type-code |
Type of card code set by multinational financial service. (Visa/Mastercard). |
ips-src-payment-type-name |
Decrypted code for type of card set by multinational financial service. (Visa/Mastercard) |
initial-amount |
Amount, set in initiating transaction, without any fees or commissions. |
Sale, Refund, Chargeback customizable callback URL
Customizable callback URL is a fully defined URL with all the parameters Merchant’s target page or script would require. Customizable URL allows defining Merchant’s own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}
. Thus Fibonatix substitutes respective parameter values into final customized URL before calling it.
Example:
https://www.i-cool-merchant.com/sale_completed.php?cardholder_name= ${name}&tx_status=${status}&order_id=${merchant_order}
Sale, Refund Callback Macros
Fibonatix Callback Macros name | Description |
---|---|
${status} |
Transaction status, approved declined processing |
${merchant_order} |
Merchant order identifier, client_orderid |
${orderid} |
Fibonatix transaction id |
${type} |
Transaction type, sale return chargeback |
${amount} |
Transaction amount |
${descriptor} |
Payment descriptor of the gate through which the transaction has been processed. |
${error_message} |
Error message: when ${status} meaning declined |
${name} |
Cardholder Name |
${email} |
Customer’s email |
${last-four-digits} |
Last four digits of customer credit card number. |
${bin} |
Bank BIN of customer credit card. |
${card-type} |
Type of customer credit card (VISA, MASTERCARD, etc). |
${card-exp-month} |
Card expiration month. |
${card-exp-year} |
Card expiration year. |
${gate-partial-reversal} |
Processing gate support partial reversal (enabled or disabled). |
${gate-partial-capture} |
Processing gate support partial capture (enabled or disabled). |
${reason-code} |
Reason code for chargebak or fraud operation. |
${processor-rrn} |
Bank Receiver Registration Number. |
${approval-code} |
Bank approval code. |
${comment} |
Comment in case of Return transaction |
${rapida-balance} |
Current balance for merchants registered in Rapida system (only if balance check active) |
${control} |
Checksum is used to ensure that it is Fibonatix (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum. |
${merchantdata} |
Reserved |
Callback authorization through control parameter
The checksum is used to ensure that the callback is sent to the merchant by Fibonatix, and not by a fraudster. WARNING! If Merchant does not check the “control” parameter in the callback script, a fraudster might use the callback URL to carry out fraudulent activities on the Merchant’s system. This SHA-1 checksum (the “control” parameter) is created by concatenation of the parameters’ values in the following order:
- status
- orderid
- merchant_order
- merchant_control_key
The complete string example may look as follows:
approved123invoice-1AF4B5DE6-3468-424C-A922-C1DAD7CB4509
Encrypt the string using SHA-1 algorithm. The resultant string yields the “control” parameter which is required for authorizing the callback. For the example the “control” above will take the following value:
5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1
Callback to Status Parameters Mapping
The following table contains a correspondence between callback parameters and status response fields.
Callback parameter Name | Status parameter Name |
---|---|
amount |
amount |
approval-code |
approval-code |
bin |
bin |
card-type |
card-type |
last-four-digits |
last-four-digits |
bank-name |
bank-name |
name |
name |
card-exp-month |
card-exp-month |
card-exp-year |
card-exp-year |
client_orderid |
client_orderid |
comment |
comment |
descriptor |
descriptor |
dest-bin |
dest-bin |
dest-card-type |
dest-card-type |
dest-last-four-digits |
dest-last-four-digits |
dest-bank-name |
dest-bank-name |
email |
email |
error_code |
error_code |
error_message |
error_message |
gate-partial-capture |
gate-partial-capture |
gate-partial-reversal |
gate-partial-reversal |
loyalty-balance |
loyalty-balance |
loyalty-bonus |
loyalty-bonus |
loyalty-message |
loyalty-message |
loyalty-program |
loyalty-program |
merchant_order |
merchant_order |
merchantdata |
merchantdata |
orderid |
orderid |
phone |
phone |
processor-rrn |
processor-rrn |
processor-tx-id |
processor-tx-id |
rapida-balance |
rapida-balance |
reason-code |
reason-code |
serial-number |
serial-number |
status |
status |
type |
type |
Callback Signature check example on Java
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();
}
}
7. Reference
Country and State Codes
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 the | CD |
52 | Cook Islands | CK |
53 | Costa Rica | CR |
54 | Cote d’Ivoire | CI |
55 | Croatia | HR |
56 | Cuba | CU |
57 | Cyprus | CY |
58 | Czech Republic | CZ |
59 | Denmark | DK |
60 | Djibouti | DJ |
61 | Dominica | DM |
62 | Dominican Republic | DO |
63 | Ecuador | EC |
64 | Egypt | EG |
65 | El Salvador | SV |
66 | Equatorial Guinea | GQ |
67 | Eritrea | ER |
68 | Estonia | EE |
69 | Ethiopia | ET |
70 | Falkland Islands (Malvinas) | FK |
71 | Faroe Islands | FO |
72 | Fiji | FJ |
73 | Finland | FI |
74 | France | FR |
75 | French Guiana | GF |
76 | French Polynesia | PF |
77 | French Southern Territories | TF |
78 | Gabon | GA |
79 | Gambia | GM |
80 | Georgia | GE |
81 | Germany | DE |
82 | Ghana | GH |
83 | Gibraltar | GI |
84 | Greece | GR |
85 | Greenland | GL |
86 | Grenada | GD |
87 | Guadeloupe | GP |
88 | Guam | GU |
89 | Guatemala | GT |
90 | Guernsey | GG |
91 | Guinea | GN |
92 | Guinea-Bissau | GW |
93 | Guyana | GY |
94 | Haiti | HT |
95 | Heard Island and McDonald Islands | HM |
96 | Holy See (Vatican City State) | VA |
97 | Honduras | HN |
98 | Hong Kong | HK |
99 | Hungary | HU |
100 | Iceland | IS |
101 | India | IN |
102 | Indonesia | ID |
103 | Iran, Islamic Republic of | IR |
104 | Iraq | IQ |
105 | Ireland | IE |
106 | Isle of Man | IM |
107 | Israel | IL |
108 | Italy | IT |
109 | Jamaica | JM |
110 | Japan | JP |
111 | Jersey | JE |
112 | Jordan | JO |
113 | Kazakhstan | KZ |
114 | Kenya | KE |
115 | Kosovo | QZ |
116 | Kiribati | KI |
117 | Korea, Democratic People’s Republic of | KP |
118 | Korea, Republic of | KR |
119 | Kuwait | KW |
120 | Kyrgyzstan | KG |
121 | Lao People’s Democratic Republic | LA |
122 | Latvia | LV |
123 | Lebanon | LB |
124 | Lesotho | LS |
125 | Liberia | LR |
126 | Libya | LY |
127 | Liechtenstein | LI |
128 | Lithuania | LT |
129 | Luxembourg | LU |
130 | Macao | MO |
131 | Macedonia, the former Yugoslav Republic of | MK |
132 | Madagascar | MG |
133 | Malawi | MW |
134 | Malaysia | MY |
135 | Maldives | MV |
136 | Mali | ML |
137 | Malta | MT |
138 | Marshall Islands | MH |
139 | Martinique | MQ |
140 | Mauritania | MR |
141 | Mauritius | MU |
142 | Mayotte | YT |
143 | Mexico | MX |
144 | Micronesia, Federated States of | FM |
145 | Moldova, Republic of | MD |
146 | Monaco | MC |
147 | Mongolia | MN |
148 | Montenegro | ME |
149 | Montserrat | MS |
150 | Morocco | MA |
151 | Mozambique | MZ |
152 | Myanmar | MM |
153 | Namibia | NA |
154 | Nauru | NR |
155 | Nepal | NP |
156 | Netherlands | NL |
157 | Netherlands Antilles | AN |
158 | New Caledonia | NC |
159 | New Zealand | NZ |
160 | Nicaragua | NI |
161 | Niger | NE |
162 | Nigeria | NG |
163 | Niue | NU |
164 | Norfolk Island | NF |
165 | Northern Mariana Islands | MP |
166 | Norway | NO |
167 | Oman | OM |
168 | Pakistan | PK |
169 | Palau | PW |
170 | Palestine, State of | PS |
171 | Panama | PA |
172 | Papua New Guinea | PG |
173 | Paraguay | PY |
174 | Peru | PE |
175 | Philippines | PH |
176 | Pitcairn | PN |
177 | Poland | PL |
178 | Portugal | PT |
179 | Puerto Rico | PR |
180 | Qatar | QA |
181 | Reunion | RE |
182 | Romania | RO |
183 | Russian Federation | RU |
184 | Rwanda | RW |
185 | Saint Barthelemy | BL |
186 | Saint Helena, Ascension and Tristan da Cunha | SH |
187 | Saint Kitts and Nevis | KN |
188 | Saint Lucia | LC |
189 | Saint Martin (French part) | MF |
190 | Saint Pierre and Miquelon | PM |
191 | Saint Vincent and the Grenadines | VC |
192 | Samoa | WS |
193 | San Marino | SM |
194 | Sao Tome and Principe | ST |
195 | Saudi Arabia | SA |
196 | Senegal | SN |
197 | Serbia | RS |
198 | Seychelles | SC |
199 | Sierra Leone | SL |
200 | Singapore | SG |
201 | Slovakia | SK |
202 | Slovenia | SI |
203 | Solomon Islands | SB |
204 | Somalia | SO |
205 | South Africa | ZA |
206 | South Georgia and the South Sandwich Islands | GS |
207 | Spain | ES |
208 | Sri Lanka | LK |
209 | Sudan | SD |
210 | Suriname | SR |
211 | Svalbard and Jan Mayen | SJ |
212 | Swaziland | SZ |
213 | Sweden | SE |
214 | Switzerland | CH |
215 | Syrian Arab Republic | SY |
216 | Taiwan, Province of China | TW |
217 | Tajikistan | TJ |
218 | Tanzania, United Republic of | TZ |
219 | Thailand | TH |
220 | Timor-Leste | TL |
221 | Togo | TG |
222 | Tokelau | TK |
223 | Tonga | TO |
224 | Trinidad and Tobago | TT |
225 | Tunisia | TN |
226 | Turkey | TR |
227 | Turkmenistan | TM |
228 | Turks and Caicos Islands | TC |
229 | Tuvalu | TV |
230 | Uganda | UG |
231 | Ukraine | UA |
232 | United Arab Emirates | AE |
233 | United Kingdom | GB |
234 | United States | US |
235 | United States Minor Outlying Islands | UM |
236 | Uruguay | UY |
237 | Uzbekistan | UZ |
238 | Vanuatu | VU |
239 | Venezuela, Bolivarian Republic of | VE |
240 | Viet Nam | VN |
241 | Virgin Islands, British | VG |
242 | Virgin Islands, U.S. | VI |
243 | Wallis and Futuna | WF |
244 | Western Sahara | EH |
245 | Yemen | YE |
246 | Zambia | ZM |
247 | Zimbabwe | ZW |
248 | Europe | EU |
249 | Asia/Pacific Region | AP |
250 | Satellite Provider | A2 |
251 | Anonymous Proxy | A1 |
252 | Sint Maarten (Dutch part) | SX |
253 | Curaçao | CW |
254 | Bonaire, Sint Eustatius and Saba | BQ |
255 | South Sudan | SS |
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 |
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 | |
42198 | Transaction Exceeds Daily Amount Limit per ID/SSN | The volume of transactions using this ID/SSN has exceeded the daily amount limit | T1 | PA, SL, RC, RI, RB |
42199 | Transaction Exceeds Weekly Amount Limit per ID/SSN | The volume of transactions using this ID/SSN has exceeded the weekly amount limit | T1 | PA, SL, RC, RI, RB |
42200 | Transaction Exceeds Monthly Amount Limit per ID/SSN | The volume of transactions using this ID/SSN has exceeded the monthly amount limit | T1 | PA, SL, RC, RI, RB |
42201 | Transaction Exceeds Daily Count Limit per ID/SSN | The number of transactions using this ID/SSN has exceeded the daily count limit | T1 | PA, SL, RC, RI, RB |
42202 | Transaction Exceeds Weekly Count Limit per ID/SSN | The number of transactions using this ID/SSN has exceeded the weekly count limit | T1 | PA, SL, RC, RI, RB |
42203 | Transaction Exceeds Monthly Count Limit per ID/SSN | The number of transactions using this ID/SSN has exceeded the monthly count limit | T1 | PA, SL, RC, RI, RB |
42301 | Card Usage Frequency Exceeds Parameter | The customer’s card was used multiple times within a short time period that exceeds applied parameter(s) | T0, T1 | PA, SL, RI, RB, CR, AV |
42302 | Customer Name Differs from Cardholder Name | The customer’s name (first name + last name) differs from the name printed on the card | T0, T1 | PA, SL, RI, CR, AV |
42303 | Customer is Not of Age | The customer’s age is below an applied limit | T0, T1 | PA, SL, RI, CR, AV |
42304 | Temporary Email Domain Detected | The customer’s email address belongs to a temporary (disposable) email address provider | T1 | PA, SL, RI, CR, AV |
42305 | IP Address Differs from BIN Country | The customer’s IP address country differs from the country where the issuer is located | T1 | PA, SL, RI, AV |
42306 | Physical Address Differs from BIN Country | The customer’s physical address country differs from the country where the issuer is located | T1 | PA, SL, RI, AV |
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 |
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 |
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 |
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 |
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 |
Language Codes
Country ID | Country | Code |
---|---|---|
1 | Afar | aa |
2 | Abkhazian | ab |
3 | Afrikaans | af |
4 | Akan | ak |
5 | Albanian | sq |
6 | Amharic | am |
7 | Arabic | ar |
8 | Aragonese | an |
9 | Assamese | as |
10 | Avaric | av |
11 | Avestan | ae |
8. Integration Helpers
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.
Status signature
Sale signature
Callback signature
String to sign |
---|
njhgjh12345232123dsdsd |
Signature |
---|
51b5886f438a04309e93305c54806d0db9a11236 |