# 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)** ```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)** ```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)** ```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 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)** ```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-idOrder ID from start-session request
salt10-character random value for each call
amountCompleted amount (with installments, etc.), 2 digits after the decimal point
installment-countInstallment count
interest-feeInterest fee for installment
status2 (REJECTED), 3 (RESOLVED), 4 (PENDING)
substatus5 (PROCESSING_ERROR), 6 (RISKY), 7 (RESOLVED), 8 (PAYMENT_WAITING)
hashSHA512 (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 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)** ```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)** ```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)** ```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 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)** ```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)** ```json { "version": "", //version of produced service "guid": "", //idempotency key "orderId": "", //akinon order identity number } ``` **Response Body raw 200 (json)** ```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)** ```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 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)** ```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)** ```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)** ```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)** ```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 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)** ```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)** ```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)** ```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)** ```json { "errors": [ { "code": "", // error code "field": "", // error field if exist "message": "" // error detail message } ] } ``` **Example** **Request (cURL)** ```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)** ```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)** ```json { "version": "", //version of produced service "guid": "", //idempotency key "orderId":"", } ``` **Response Body raw 200 (json)** ```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)** ```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 STATUSDEFINITION
HTTP 200SUCCESS - Hook processed successfully
HTTP 4xxFAILURE - Client Side Error
HTTP 5xxFAILURE - Server Side Error
**Example** **Request (cURL)** ```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" } }' ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/flows/payment-flows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.