Card Payment API

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
&currency=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

• 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

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.

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.)
• email
• 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:

Payment Form Request Parameters

• 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

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
&currency=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 Response

Rebill Request Example:

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

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

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

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 processIn 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 formFibonatix 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

• 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

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.

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 Response

Capture Response Example:

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

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
&currency=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&card_printed_name=CARD HOLDER
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
&first_payment_date=30.10.20
&recurring_date_type=day
&time_interval= 3
&number_of_payments= 3

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
&currency=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&card_printed_name=CARD HOLDER
&redirect_url=http://doc.fibonatix.com/doc/dummy.htm
&server_callback_url=http://doc.fibonatix.com/doc/dummy.htm
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
&first_payment_date=30.10.20
&recurring_date_type=day
&time_interval= 3
&number_of_payments= 3

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

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

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 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:

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

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

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

State Codes

Status Classes

Within Paragon the following transaction status classes are used:

Status Codes

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

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

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

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

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

Received (10)

Approved (20)

Pending (30)

Declined by Validation (41)

Declined by Risk Management (42)

Declined by Authentication (43)

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

Declined by Processor (44)

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

Declined by Issuer (45)

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

Declined by Technical Error (46)

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

Unknown (90)

Language Codes

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