Editing PlatiOnline API - software developers


== Plati Online API ==

This document guides the new merchants to implement PlatiOnline system modules. The document provides step-by-step implementing instructions along with code examples. Document appendixes contain useful information such as definition tables for frequently used terms in card industry, error codes, state / country codes and other information.

=== How to do requests to Plati Online ===

All the calls to/from Plati Online system use SOAP method:

Every HTTP request between Plati Online system and the merchants servers are done using 3 XML tags:

{| class="wikitable"
|-
! Field name
! Comments
|-
| '''F_LOGIN'''
| this value is provided by Plati Online
|-
| '''F_MESSAGE'''
| this field contain an XML encrypted with AES algorithm. For every call you/we have to generate a new AES key '''an random 32 length alphanumeric'''
|-
| '''F_CRYPT_MESSAGE'''
| this field contain the AES key encrypted using the RSA algorithm
|}

=== Merchants security keys ===

Security keys are used to uniquely identify amount, currency and merchant who submits the transaction.

==== [[How_to_obtain_security_keys|How to obtain security keys]] ====


== Payment Authorization and Plati.online Tokenization ==

The authorization process is split-ed into 3 steps:

{| class="wikitable"
|-
! Step
! Comments
|-
| '''1. [[Validating_the_XML_Message_validation_schema|Validating the XML_Message validation schema]]'''
| Merchants will create the authorization XML named '''XML_Message''' request based on Plati Online version. 
'''XML_Message''' contain all the necessary information to initiate an authorization in the Plati Online system;

|-
| '''2. [[Redirect_URL|Redirect URL]]'''
| Once the '''XML_Message''' is successfully parsed the Plati Online system will echo an XML with the redirect URL. To continue transaction merchants have to send to the browser the '''URL HTTP Redirect'''. Plati Online system will load the card page.
|-
| '''3. [[Authorization_relay_response|Authorization relay response]] Authorized/Declined/On Hold'''
| Once the card is processed, the Plati Online system will send to merchant's server the response: 
*Authorized 
*Declined 
*On Hold 

|}

== Payment Settle Request ==
After the authorization process you have 5 days to do the '''Settle request'''

The settle process is split-ed into 2 step:

{| class="wikitable"
|-
! Step !! Comments
|-
| '''1. [[Validating the settle request XML_Message validation schema]]''' || Merchants will create the settle XML named '''XML_Message''' request based on Plati Online version.
'''XML_Message''' contain all the necessary information to initiate an transaction settlement request in the Plati Online system;
|-
| '''3. [[Settlement request response]] Settle/Error''' || Plati Online system will response:
*Settle request
*Error
|}

== Payment Void Request ==
After the authorization process you can void the transaction.

The void process is split-ed into 2 step:

{| class="wikitable"
|-
! Step !! Comments
|-
| '''1. [[Validating the void request XML_Message validation schema]]''' || Merchants will create the void XML named '''XML_Message''' request based on Plati Online version.
'''XML_Message''' contain all the necessary information to initiate an transaction void request in the Plati Online system;
|-
| '''3. [[Void request response]] Void/Error''' || Plati Online system will response:
*Pending Void
*Error
|}

== Payment Refund Request ==
After the Settle process you have 72 days to do the '''Refund request''' if you need.

The refund process is split-ed into 2 step:

{| class="wikitable"
|-
! Step !! Comments
|-
| '''1. [[Validating the refund request XML_Message validation schema]]''' || Merchants will create the refund XML named '''XML_Message''' request based on Plati Online version.
'''XML_Message''' contain all the necessary information to initiate an transaction refund request in the PlatiOnline system;
|-
| '''3. [[Refund request response]] Refund/Error''' || PlatiOnline system will response:
*Refund request
*Error
|}




== Query Request (Tranzaction status and Payment Token) ==

Any time you need to '''Query''' the status of a transaction you have to do a '''Query Request'''.

In order to get the Payment&nbsp;Token you have to make a Query Request with&nbsp;'''x_request_payment_token&nbsp;= 1'''

&nbsp;

The query process is split-ed into 2 step:

{| class="wikitable"
|-
! Step
! Comments
|-
| '''1. [[Validating_the_query_request_XML_Message_validation_schema|Validating the query request XML_Message validation schema]]'''
| Merchants will create the query XML named '''XML_Message''' request based on Plati Online version. 
'''XML_Message''' contain all the necessary information to initiate an query transactions status request in the PlatiOnline system;

|-
| '''3. [[Query_request_response|Query request response]] Info&Status/Error'''
| PlatiOnline system will response: 
*Transaction(s) information 
*Payment Token info 
*Error 

|}

== QueryByDate Request ==
Any time you need to get the list of transactions by date you need to do '''QueryByDate Request'''.

The "QueryByDate" process is split-ed into 2 step:

{| class="wikitable"
|-
! Step !! Comments
|-
| '''1. [[Validating the QueryByDate Request XML_Message validation schema]]''' || Merchants will create the QueryByDate XML named '''XML_Message''' request based on PlatiOnline version.
'''XML_Message''' contain all the necessary information to initiate an QueryByDate Request in the PlatiOnline system;
|-
| '''3. [[QueryByDate Response]] Info&Status/Error''' || PlatiOnline system will response:
*Transactions information
*Error
|}

== SMS Request ==
Any time you need to send SMS you have to do a '''SMS Request'''.

The SMS request process is split-ed into 2 step:

{| class="wikitable"
|-
! Step !! Comments
|-
| '''1. [[Validating the SMS request XML_Message validation schema]]''' || Merchants will create the SMS request XML named '''XML_Message''' request based on Plati Online version.
'''XML_Message''' contain all the necessary information to initiate an SMS request in the PlatiOnline system;
|-
| '''3. [[SMS request response]] Info&Status/Error''' || PlatiOnline system will response:
*SMS information
*Error
|}

== [[Testing the integration]] ==