Transaction Flow – Hosted Session
You should implement the Hosted Session first on the integration with Spiral gateway. This flow is applied to all supported payment. You may consider to implement the direct transaction if you need to do extra functions like tokenization or refund.
In the Hosted Session, the card holders will be redirected into a page (or handled in a SDK for mobile App) which is hosted by payment gateway instead of merchants, to handle the transaction data inputting like Card PAN, display QR code, etc. This would reduce the development time and certification cost of the PCI compliance.
There are 3 steps in the Hosted Session flow:
Step 1: Create Order Session
Merchant's backend server should send the transaction operation API with cmd=SALESESSION and order information (e.g. amount, merchant reference) to Spiral PG, and Spiral PG will return the session ID and other transaction information.
If a session ID is returned, proceed the payment session in the step 2. Otherwise, create a new session with a new merchant reference.
Step 2: Process Payment at Frontend
After getting the session ID, the page should call the payment function with our provided Javascript library (or SDK library when using mobile App).
When the payment is completed, the Javascript library will redirect the result to the merchant’s result page (When using mobile App, the SDK will return the result to App).
Step 3: Receive Notification (webhook) at Backend
When the payment is completed, Spiral PG will send a notification (webhook) to the merchant’s backend.
If the Spiral PG did not get the acknowledgement from web server, it will keep resend the notification for around 2 hours with the interval around 15 minutes.
If webhook cannot be received within a reasonable time, merchants can send 'Query API' to check for the transaction status.
For payment, it is very important to identify a specified transactions among a batch of records. Thus, it is very important to know how to use the proper reference to match your record.
Merchant Reference (merchantRef) – The reference created by merchants on this order which must be unique for every transaction. If refund/capture is going to be made, a new merchant reference must be provided which is different from the original sale/authorization transaction.
Format: Max. 25 characters. [A-Za-z0-9_-] but the last 3 characters cannot be ‘_’.
Transaction ID (txnId) – similar to merchant reference, but is generated by Spiral instead of merchant.
Order ID (orderId) – generated by Spiral which is same as transaction ID, however, for a series of transactions (e.g. capture/refund) which is ride on the same sale/authorization transaction, they will share the same Order Id. Order Id is also needed to be provided when doing capture/refund to indicate the original order.
The difference scenario between Checkout Session flow and Direct Transaction.
Direct Transaction | Checkout Session Transaction |
|
|