Transaction Flow – Payment Link

In the case that the transaction will not be processed at web pages immediately and will be sent to customer by email or other communications. You can request payment link via Spiral API.

 

The Spiral will return a URL via the API. When the customer followed the link, it will prompt for the payment selection and proceed on the payment.

 

There are 3 steps in the Payment Link API flow: 



 

Step 1: Create Payment Link

Merchant's backend server should send the payment link creation API with order information (e.g. amount, merchant reference) to Spiral PG, and Spiral PG will return the URL.

Go to API Document

Step 2: Send the link to customer

Merchant's backend should send out the payment link to customer via email or other channels.

WebhooksCreated with Sketch.

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.

Go to API Document

  • Only sent API request by backend

    and not by frontend. The API message is required to be signed with merchant’s private key and the private key should never be deployed onto the frontend.

  • Trust only the webhook or query API

    As the user may close the browser or manipulated the URL, updating the transaction result based on the frontend actions is not a secured practice.

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. 22 characters. [A-Za-z0-9_-] 

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.