Payment Flows

With Auth/Capture Support

The user proceeds to the payment step, and a start session request is sent to the payment provider with the summary information of the user’s cart. The session begins, and the end user proceeds to the payment provider's payment page. After entering all payment details, the user returns to Akinon return page with the payment summary information. Akinon views the last status of payment and notifies the provider that this transaction has been completed or cancelled. At the end of this flow, the user is informed about the result.

Without Auth/Capture Support

In cases where the payment provider has no option for Auth/Capture, they should write an Akinon Extension. The extension proceeds to update the payment status based on Akinon's preference to complete the transaction. Below is an example about unsuccessful payment after returnUrl checks.

Webhook/IPN Support

In cases where a user's payment is interrupted due to any error or in situations where expediting or completing the payment flow outside of routine payment status checks is required, a webhook request can be sent to Akinon systems. Webhook requests sent by the payment provider will be processed after a certain period of time. Webhooks can be processed with or without Auth/Capture support.

Payloads

Below is the list of services that can be integrated with the aforementioned flows.

Three configuration parameters will be shared during integration.

username	Username for basic authentication
password	Password for basic authentication
hash-key	a key info for hashing

start-session (POST)

URL

^^/start-session

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
    "version": "", //version of produced service
    "guid": "", //idempotency key
    "orderId": "", //Akinon order identity number
    "orderAmount": 0.00, //Akinon order total amount for payment, 2 digits after the decimal point
    "locale": "", //IETF BCP 47 language tag
    "returnUrl": "", //Return URL after user entries
    "type": "", // payment method choice; SALE,AUTH
    "currency": "", //Three-letter ISO 4217 currency code
    "clientIp": "", //client ip !!! DEPRECATED It will be deleted with the next version
    "customer": { 
      "firstName": "", 
      "lastName": "", 
      "phoneNumber": "", 
      "email": "",
      "clientIp": "", //client ip
    },
    "targetProvider": "" //Optional. Specifies the intended sub-provider or payment method to be used
}

Response Body raw 200 (json)

{
    "type": "", //started payment type; values SALE,AUTH
    "redirectUrl": "" //end user redirection url
    "redirectMethod": "" // GET or POST
    "sessionId": "", // unique id for started session
    "transactionId":"" //generated unique payment transaction id on payment provider, if exists
}

Response Body raw 4xx/5xx (json)

{
   "transactionId":"", //generated unique payment transaction id on payment provider, if exists
   "status": "", // last status after this error of session, REJECTED, RESOLVED, PENDING
   "subStatus": "", // last substatus after this error of session, values  substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING
   "errors": [
       {
           "code": "", // error code 
           "field": "", // error field if exist
           "message": "" // error detail message
       }
   ]
}

Example

Request (cURL)

curl --location --request POST '^^/start-session' \
--header 'x-akinon-request-id: 91048724-c040-468e-b87c-cbe01f61ac91' \
--header 'x-akinon-api-version: 1.1' \
--header 'Authorization: Basic Y2VtOnnDvGNlbA==' \
--data-raw '{
    "version": "1",
    "guid": "1f2ed848-d0b5-400c-8a33-fea6c0b4bf35",
    "orderId": "41422452",
    "orderAmount": 570.20,
    "locale": "tr",
    "currency": "TRY",
    "returnUrl": "https://firm.com.tr/return-url",
    "clientIp": "255.255.255.0",
    "type": "SALE",
}'

Response (json)

{
  "type": "SALE",
  "redirectUrl": "https://firm.com.tr/user-page?sessionId=78e6c67e-4d21-43ab-a955-d806a3802507"
 "redirectMethod": "GET",
 "sessionId": "4bc3d3d2-9962-4671-8eb4-714522a90caf",
 "transactionId": "32376315-c799-4249-928c-273ac8dceea1"
}

return-url (browser POST)

URL

(merchant-url)/return-url

Request Body (form-data)

order-id	Order ID from start-session request
salt	10-character random value for each call
amount	Completed amount (with installments, etc.), 2 digits after the decimal point
installment-count	Installment count
interest-fee	Interest fee for installment
status	2 (REJECTED), 3 (RESOLVED), 4 (PENDING)
substatus	5 (PROCESSING_ERROR), 6 (RISKY), 7 (RESOLVED), 8 (PAYMENT_WAITING)
hash	SHA512 (salt|orderId|amount|installment-count|interest-fee|status|substatus|hash-key)

Response 200

Example

Hash generation:

90f34c2b@%|41422452|570.20|1|0.00|3|6|c127d642-7aec-4fa9-8199-9fdbaa323c9a

Request (cURL)

curl --location -g --request POST '^^/return-url' \
--form 'order-id="41422452"' \
--form 'guid="1f2ed848-d0b5-400c-8a33-fea6c0b4bf35"' \
--form 'amount="570.20"' \
--form 'installment-count="1"' \
--form 'interest-fee="0.00"' \
--form 'status="3"' \
--form 'substatus="6"' \
--form 'hash="eb3943935d40580b3d3f920a53038705b42c4ef2b4a7a9d7a6c38889123786532f0e37f01da05ec172fbe500c83df7aef21d8881cb59edb795b1c8ddc49b3293"'

Response 200

purchase (POST)

URL

^^/purchase

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
    "version": "", //version of produced service
    "guid": "", //idempotency key
    "orderId": "", //akinon order identity number
    "orderAmount": 0.00, //Optional. Final Amount for payment if it changed since authorization, 2 digits after the decimal point
}

⚠ orderAmount: parameter is only used for provisioned payments.

Response Body raw 200 (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "" // substatus information of current situation, values PROCESSING_ERROR, RISKY, RESOLVED, PAYMENT_WAITING
}

Response Body raw 4xx/5xx (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "", // substatus information of current situation,  substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING
    "errors": [
       {
           "code": "", // error code 
           "field": "", // error field if exist
           "message": "" // error detail message
       }
   ]
}

Example

Request (cURL)

curl --location --request POST '^^/purchase' \
--header 'x-akinon-request-id: 2e15affa-daa4-45f4-b129-11a3720e744d' \
--header 'x-akinon-api-version: 1.1' \
--header 'Authorization: Basic Y2VtOnnDvGNlbA==' \
--data-raw '{
    "version": "1",
    "guid": "8f46f678-4d5a-4b12-b658-6e5bb0472fbb",
    "orderId": "41422452"
}'

Response (json)

{
  "transactionId": "9201e160-989c-44d8-8a7e-0f2a06549343",
  "status": "RESOLVED",
  "subStatus": "RESOLVED"
}

void (POST)

URL

^^/void

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
    "version": "", //version of produced service
    "guid": "", //idempotency key
    "orderId": "", //akinon order identity number
}

Response Body raw 200 (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "" // substatus information of current situation,  substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING
}

Response Body raw 4xx/5xx (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "", // substatus information of current situation, substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING  "errors": [
       {
           "code": "", // error code 
           "field": "", // error field if exist
           "message": "" // error detail message
       }
   ]
}

Example

Request (cURL)

curl --location --request POST '^^/void' \
--header 'x-akinon-request-id: 771b54f5-c258-4523-850c-0a6eb161b9ed' \
--header 'x-akinon-api-version: 1.1' \
--header 'Authorization: Basic Y2VtOnnDvGNlbA==' \
--data-raw '{
    "version": "1.1",
    "guid": "53c3073d-86d8-498d-bd1f-f7e61c88cb97",
    "orderId": "41422452"
}'

Response (json)

{
  "transactionId": "80e48a11-f19e-4281-afd4-12dd61df2c5a",
  "status": "RESOLVED",
  "subStatus": "RESOLVED"
}

refund (POST)

URL

^^/refund

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
    "version": "", //version of produced service
    "guid": "", //idempotency key
    "orderId": "", //akinon order identity number
    "amount": 0.00, //amount to be refunded, , 2 digits after the decimal point
    "currency": "" //Three-letter ISO 4217 currency code
}

Response Body raw 200 (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "" // substatus information of current situation,  substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING
}

Response Body raw 4xx/5xx (json)

{
    "transactionId":"", //generated unique payment transaction id on payment provider
    "status": "", //status information current situation, values: REJECTED, RESOLVED, PENDING
    "subStatus": "", // substatus information of current situation,  substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING   "errors": [
       {
           "code": "", // error code 
           "field": "", // error field if exist
           "message": "" // error detail message
       }
   ]
}

Example

Request (cURL)

curl --location --request POST '^^/refund' \
--header 'x-akinon-request-id: 771b54f5-c258-4523-850c-0a6eb161b9ed' \
--header 'x-akinon-api-version: 1.1' \
--header 'Authorization: Basic Y2VtOnnDvGNlbA==' \
--data-raw '{
    "version": "1",
    "guid": "07469f3b-3813-4d37-bfd2-adc0411b80ad",
    "orderId": "41422452",
    "amount": 170.20,
    "currency": "TRY"
}'

Response (json)

{
  "transactionId": "6272d86a-d2d8-4833-9bc0-e34a201041ee",
  "status": "RESOLVED",
  "subStatus": "RESOLVED"
}

history (POST)

URL

^^/history

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
    "version": "", //version of produced service
    "guid": "", //idempotency key
    "orderId": "", //akinon order identity number
    "type": "", //optional for filtering, type for filtering results; values: START,REFUND,VOID,PURCHASE,HISTORY
    "transactionId": "",//optional for filtering, payment transaction id from purchase,refund,void response
    "status": "", //optional for filtering; values: REJECTED, RESOLVED, PENDING
    "subStatus": "" //optional for filtering; PROCESSING_ERROR, RISKY, RESOLVED, PAYMENT_WAITING
}

Response Body raw 200 (json)

{
    "lastAction": "", // last action of session, START,REFUND,VOID,PURCHASE,HISTORY
    "status": "", // last status of last action/total payment
    "substatus":"", // last substatus of last action/total payment
    "balance": 0.00, // total amount after refunds are subtracted, 2 digits after the decimal point
    "currency": "", // currency of session
    "paymentTransactionHistory": [ // steps of session
        {
            "guid": "", // guid information in requests
            "type": "", // request type, START,REFUND,VOID,PURCHASE,HISTORY
            "timestamp": "", // request datetime in ISO-8601 UTC+3
            "statusCode": "", // payment status; values: REJECTED, RESOLVED, PENDING
            "subStatusCode": "", // payment substatus; substatuses  for REJECTED status: PROCESSING_ERROR, RISKY substatuses  for RESOLVED status: RESOLVED for PENDING status: PAYMENT_WAITING
            "statusDetail": "", //detail message
            "subSteps": [ // substeps/retries between provider and extension
                {
                    "timestamp": "", // request datetime in ISO-8601 UTC+3
                    "statusCode": "", // payment provider status code
                    "statusDetail": "" // payment provider status detail
                }
            ]
        }
    ]
}

Response Body raw 4xx/5xx (json)

{
    "errors": [
       {
           "code": "", // error code 
           "field": "", // error field if exist
           "message": "" // error detail message
       }
   ]
}

Example

Request (cURL)

curl --location --request POST '^^/history' \
--header 'x-akinon-request-id: 35529fc2-75e8-4860-8c63-644f78bc8a7b' \
--header 'x-akinon-api-version: 1.1' \
--header 'Authorization: Basic Y2VtOnnDvGNlbA==' \
--data-raw '{
    "version": "1",
    "guid": "fac0bc4d-90fe-4dda-856a-587868ed28d0",
    "orderId": "41422452"
}'

Response (json)

{
  "lastAction": "REFUND",
  "status": "RESOLVED",
  "substatus": "RESOLVED",
  "balance": 400,
  "currency": "TRY",
  "paymentTransactionHistory": [
    {
      "guid": "1f2ed848-d0b5-400c-8a33-fea6c0b4bf35",
      "type": "START",
      "timestamp": "2022-11-08 07:44:26",
      "statusCode": "PENDING",
      "subStatusCode": "BUYER_ACTION_REQUIRED",
      "statusDetail": "User Entry Waiting",
      "subSteps": null
    },
    {
      "guid": "1f2ed848-d0b5-400c-8a33-fea6c0b4bf35",
      "type": "PURCHASE",
      "timestamp": "2022-11-08 07:45:26",
      "statusCode": "RESOLVED",
      "subStatusCode": "RESOLVED",
      "statusDetail": "Payment Completed",
      "subSteps": [
        {
          "timestamp": "2022-11-08 07:45:20",
          "statusCode": "06",
          "statusDetail": "Timeout error"
        },
        {
          "timestamp": "2022-11-08 07:45:25",
          "statusCode": "00",
          "statusDetail": "Completed"
        }
      ]
    },
    {
      "guid": "07469f3b-3813-4d37-bfd2-adc0411b80ad",
      "type": "REFUND",
      "timestamp": "2022-11-08 07:50:26",
      "statusCode": "RESOLVED",
      "subStatusCode": "RESOLVED",
      "statusDetail": "Refund Completed",
      "subSteps": [
        {
          "timestamp": "2022-11-08 07:50:25",
          "statusCode": "00",
          "statusDetail": "Completed"
        }
      ]
    }
  ]
}

query (POST)

This service is used to retrieve latest payment status.

URL

^^/query

Request Headers

x-akinon-request-id	Unique ID for problem solving & tracing.
x-akinon-api-version	Akinon Customer API version.
Authorization	Basic [BASE64_encoded(username:password)]

Request Body raw (json)

{
  "version": "", //version of produced service
  "guid": "", //idempotency key
  "orderId":"",
}

Response Body raw 200 (json)

{
  "orderId": "", // akinon order identity number
  "status": "", // 2 (REJECTED), 3 (RESOLVED) 4 (PENDING) 9 (AUTHORIZED)
  "subStatus": "", // 5 (PROCESSING_ERROR), 6 (RISKY), 7 (RESOLVED), 8 (PAYMENT_WAITING)
  "transactionId": "", //generated unique payment transaction id on payment provider
}

webhook/ipn (POST)

This service is used to handle payment webhook/IPN(Instant Payment Notification).

URL

^^/hooks/payment

Request Headers

Request Body raw (json)

{
  "event":"", // INITIALIZED, COMPLETED, DECLINED
  "eventBody":
    {
      "orderId":"",
      "status": "", // 2 (REJECTED), 3 (RESOLVED) 4 (PENDING)
      "subStatus": "", // 5 (PROCESSING_ERROR), 6 (RISKY), 7 (RESOLVED), 8 (PAYMENT_WAITING)
      "amount": "", // Amount of payment transaction
      "installment-count": "", // Installment count
      "interest-fee": "" // Interest fee for installment
    }
}

Response

HTTP STATUS	DEFINITION
HTTP 200	SUCCESS - Hook processed successfully
HTTP 4xx	FAILURE - Client Side Error
HTTP 5xx	FAILURE - Server Side Error

Example

Request (cURL)

curl --location --request POST '^^/hooks/payment/webhook' 
--header 'Authorization: Basic Y2VtOnnDvGNlbA=' 
--data-raw '{
	"event":"COMPLETED",
	"eventBody":{
		"order_id": "12341234",
		"status": "RESOLVED",
		"substatus": "RESOLVED",
		"interest_fee": "0",
		"installment_count": "1",
		"amount":"100.00"
	}
}'