Skip to main content

Key Points Before Creating a Payment Session

A payment session can be created in the Akifast system with or without an associated Akinon User. If a merchant initiates a session for an Akinon user, the payment session becomes exclusive to that particular Akinon user.

NOTE

When conducting transactions with a logged-in Akinon User, the Akinon User's access token must be set in the Akinon-User-Access-Token header.

i. User Allocation​

While creating a payment session, the following points regarding user allocation should be noted:

If none of the parameters representing the user are defined in the request, the payment session is created in visitor mode. This session will be allocated to the first user logging in on the hosted payment page. The relevant parameters, listed in order of priority, are:

  1. Akinon-User-Access-Token: Only this parameter is considered if all parameters representing the user are defined.
  2. session_owner_id: For the use of this parameter, the Akinon-User-Access-Token parameter must not be defined.
  3. merchant_customer_id: For the use of this parameter, Akinon-User-Access-Token and session_owner_id parameters must not be defined.
  4. merchant_customer_email: This parameter is auxiliary. If no user is found in the system with merchant_customer_id, the email address is used.

If only the Akinon-User-Access-Token parameter, representing the user, is defined, the created payment session is allocated to the user associated with Akinon-User-Access-Token.

  • This session can be used by the user on the hosted payment page without logging in again.
  • The simultaneous defining of Akinon-User-Access-Token and session_owner_id parameters is not necessary. If defined, and the user ID associated with Akinon-User-Access-Token is not the same as the value defined in session_owner_id, the system returns an error.

If only the session_owner_id parameter, representing the user, is defined, and a user with this ID is found in the system, the created payment session is allocated to that user.

  • With this session on the hosted payment page, only the relevant user's email address can be used for login.
  • The user is directed to the HPP where they can enter the OTP code.
  • After the first successful login, no further login is required.
  • If the user is not found, the system returns an error.

If only the merchant_customer_id parameter, representing the user, is defined, the payment session is allocated to that user if they exist in the system.

  • With this session on the hosted payment page, only the relevant user's email address can be used for login.
  • The user is directed to a page where they can enter the OTP code directly.
  • After the first successful login, no further login is required.
  • If the user is not found, the system returns an error.
  • If no user is found, the merchant_customer_email parameter is assigned to the payment session as the user. On the hosted payment page, if a user with the email address exists in the system, the OTP login screen is displayed; otherwise, the registration screen opens. If the merchant_customer_email parameter is not sent, the payment session is created in visitor mode. If a different user logs into the system than the one specified in the merchant_customer_email parameter, an error will be returned.

ii. Basket Feature and Amount Parameter​

Key points to know about the basket feature and amount parameter are outlined below.

  • To use this feature, the basket parameter in the request must be created in the format specified in the request parameters table.

  • If both amount and basket parameters are defined, the total amount calculated in the basket must be equal to the amount parameter sent; otherwise, an error will occur during the creation of the payment session.

  • Objects sent in the discounts parameter within the basket parameter have a negative impact on the total amount, as they represent discounts.

iii. Provision of Agreements for the Merchant​

For agreements to be viewable on the hosted payment page, the merchant must prepare two different services in their own system.

The mandatory service URLs for the merchant must be defined with validation. According to this validation, either the agreements_iframe_url field must be filled, or both query_agreement_types_url and query_agreements_url fields must be filled together.

  • query_agreement_types_url: Service URL where agreement types will be provided.
  • query_agreements_url: Service URL where agreement will be provided.
  • agreements_iframe_url: Iframe URL where agreement will be provided.

iv. Provision of Delivery Options​

For delivery options to be queried and displayed based on the user's selected address on the hosted payment page, the merchant must prepare a service in their own system.

The mandatory service URL for the merchant must be defined in the following parameter.

  • query_shipping_option_url: Service URL where delivery options will be provided based on the user's address.

v. Notification for Successful Payment Result​

For the payment flow to be successfully completed, the merchant must prepare a service in their own system to handle notification requests.

The mandatory service URL for the merchant must be defined in the following parameter.

  • notification_url: Service URL that will feed the merchant's system with information about the successful payment result. If an error is encountered when sending the notification request and receiving a response from the system, it will not be resent; instead, it will be canceled.

vi. State Diagram of the Payment Session​

  • When the payment session is created, the status of the session is marked as ACTIVE. If no transaction is performed within a one-hour process, the status value is marked as EXPIRED through jobs.

  • If a successful payment transaction is made, the status value is changed from ACTIVE to COMPLETED.

  • If notification to the merchant cannot be provided after a successful payment, the status value is changed from ACTIVE to QUARANTINE.

  • While the status of the payment session is QUARANTINE, jobs attempt to provide notification to the merchant at certain intervals. If unsuccessful, the status value is changed from QUARANTINE to WAITING_FOR_VOID.

  • While the status of the payment session is WAITING_FOR_VOID, if a successful void operation occurs, the status value is changed to FAILED_AFTER_VOID. The system will attempt to void the payment up to 10 times, and if it fails after the 10th attempt, the payment session will be flagged for manual review.

  • While the status of the payment session is WAITING_FOR_VOID, if unsuccessful void operations occur, the status value is changed to MANUAL_REVIEW. The merchant can then review the session in the Merchant Dashboard or receive an email notification.