Merchant Back Office APIs

NOTE

The sandbox URL of the API must be added.

NOTE

The production URL of the API must be added.

Customer POS Operations

Services related to the management of Akinon customers' virtual POS are provided below.

NOTE

Each request must include a Bearer Token in the Authorization header.

`DELETE` Delete Virtual POS

When Akinon customers want to delete their registered virtual POS, the following endpoint is called. The code value of the virtual POS to be deleted is added to the URL. The ID value created for the customer is added in the Merchant-Id header.

A successful request returns HTTP Status 200 OK response with an empty body.

Path: /merchant-poses/{code}

Example Response 1

{
    "trace_id": "e9bccb47-c91f-48d8-8edc-098c73623dd6",
    "response": null
}

Example Response 2

{
    "trace_id": "7ddbb527-17da-4dc7-aa77-cba811235b83",
    "response": {
        "errors": [
            {
                "error_code": "MERCHANT_POS_NOT_FOUND",
                "message": "Pos not found.",
                "argument": null
            }
        ]
    }
}

`PATCH` Activate/Deactivate Virtual POS

When Akifast member businesses want to activate/deactivate their registered virtual POS, the following endpoint is called. The code value of the virtual POS to be processed is added to the URL. The ID value created for the customer is added in the Merchant-Id header.

A successful request returns an HTTP Status 200 OK response with POS details.

NOTE

If the virtual POS is currently active, it will be deactivated, and if it is currently deactive, it will be activated.

Path: /merchant-poses/{code}/toggle

Example Response 1

{
    "trace_id": "e9bccb47-c91f-48d8-8edc-098c73623dd6",
    "response": {
        "name": "İş Bankası Sanal Pos",
        "code": "ISBANK_VPOS",
        "payment_system": {
            "name": "T. İŞ BANKASI A.Ş.",
            "code": "ISBANK",
            "bank_eft_code": "0064",
            "logo": "isbank.png",
            "default_gateway_code": "NESTPAY",
            "created_date": "2022-07-26T09:34:09.72+03:00",
            "short_name": "İş Bankası"
        },
        "resource_url": "https://entegrasyon.asseco-see.com.tr/fim/api",
        "threed_resource_url": "https://entegrasyon.asseco-see.com.tr/fim/est3Dgate",
        "config": {
            "clientId": "700655000100",
            "user": "akinonapi",
            "password": "AKINON07",
            "storeKey": "TRPS0100"
            "authorizationUrl": "",
            "queryTransactionUrl": "",
            "voidUrl": "https://entegrasyon.asseco-see.com.tr/fim/api",
            "refundUrl": "https://entegrasyon.asseco-see.com.tr/fim/api"
        },
        "gateway_code": "NESTPAY",
        "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
        "status": "INACTIVE",
        "one_shot_default": true,
        "currency": "TRY",
        "created_date": "2022-07-26T03:00:00.00+03:00"
    }
}

Example Response 1

{
    "trace_id": "7ddbb527-17da-4dc7-aa77-cba811235b83",
    "response": {
        "errors": [
            {
                "error_code": "MERCHANT_POS_NOT_FOUND",
                "message": "Pos not found.",
                "argument": null
            }
        ]
    }
}

`GET` List Virtual POS

When Akinon customers want to list their registered virtual POS, the following endpoint is called.

A successful request results in an HTTP Status 200 OK response with a list of registered virtual POS in the body. The response is sorted in ascending order based on the code value.

Path: /merchant-poses

Return Values

Return Value	Type	Description
merchant_poses	array	Holds a list of virtual POSes belonging to the customer.
merchant_poses[0].name	string	Name of the virtual POS provided by the customer.
merchant_poses[0].code	string	Code of the virtual POS provided by the customer.
merchant_poses[0].payment_system	object	Object of the the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.name	string	Name of the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.code	string	Code of the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.bank_eft_code	string	EFT code of the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.logo	string	Location of the logo for the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.default_gateway_code	string	Default gateway code of the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.created_date	string	Creation date of the payment system to which the virtual POS is connected.
merchant_poses[0].payment_system.short_name	string	Short name of the payment system to which the virtual POS is connected.
merchant_poses[0].resource_url	string	The resource URL that the virtual POS will use for integration requests.
merchant_poses[0].threed_resource_url	string	The resource URL that the virtual POS will use for 3D integration requests.
merchant_poses[0].config	object	Object holding specific settings for the virtual POS, which can be queried using the virtual POS template API.
merchant_poses[0].gateway_code	string	Code specifying the infrastructure to which the virtual POS is connected. Supported infrastructures can be queried with the relevant API based on payment system.
merchant_poses[0].merchant_id	string	ID of the customer to whom the virtual POS is connected.
merchant_poses[0].status	string	Returns one of the MerchantPosStatus values.
merchant_poses[0].one_shot_default	boolean	Indicates whether the virtual POS is the default for single payment.
merchant_poses[0].currency	currency	Currency of the virtual POS. If not specified, default TRY is added.
merchant_poses[0].created_date	string	Creation date of the virtual POS.
pagination	object	Contains information about the page within the request result.
pagination.list_size	number	Number of records within the page of the request result.
pagination.total	number	Total number of records found in the request result.
pagination.page	number	Page number returned in the request result, starting from 0.

Example Response

{
    "trace_id": "b63769de-80fa-48e5-a513-152f9ba5ed0e",
    "response": {
        "merchant_poses": [
             {
                "name": "İş Bankası Sanal Pos",
                "code": "ISBANK_VPOS",
                "payment_system": {
                    "name": "T. İŞ BANKASI A.Ş.",
                    "code": "ISBANK",
                    "bank_eft_code": "0064",
                    "logo": "isbank.png",
                    "default_gateway_code": "NESTPAY",
                    "created_date": "2022-07-26T09:34:09.72+03:00",
                    "short_name": "İş Bankası"
                },
                "resource_url": "",
                "threed_resource_url": "",
                "config": {
                    "clientId": "",
                    "user": "",
                    "password": "",
                    "storeKey": "",
                    "voidUrl": "",
                    "refundUrl": ""
                },
                "gateway_code": "NESTPAY",
                "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
                "status": "ACTIVE",
                "one_shot_default": true,
                "currency": "TRY",
                "created_date": "2022-07-26T03:00:00.00+03:00"
            },
            {
                "name": "QNB FINANS Sanal POS",
                "code": "QNB_FINANS_VPOS",
                "payment_system": {
                    "name": "QNB FİNANSBANK A.Ş.",
                    "code": "FINANSBANK",
                    "bank_eft_code": "0111",
                    "logo": "finansbank.png",
                    "default_gateway_code": "NESTPAY",
                    "created_date": "2022-07-26T09:34:09.72+03:00",
                    "short_name": "Finansbank"
                },
                "resource_url": "",
                "threed_resource_url": "",
                "config": {
                    "merchantId": "",
                    "mbrId": "",
                    "userCode": "",
                    "merchantPass": "",
                    "userPass": "",
                    "voidUrl": "",
                    "refundUrl": ""
                },
                "gateway_code": "QNB_FINANS",
                "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
                "status": "ACTIVE",
                "one_shot_default": false,
                "currency": "TRY",
                "created_date": "2022-07-26T03:00:00.00+03:00"
            },
            {
                "name": "YKB Sanal POS",
                "code": "YKB_VPOS",
                "payment_system": {
                    "name": "YAPI VE KREDİ BANKASI A.Ş.",
                    "code": "YKB",
                    "bank_eft_code": "0067",
                    "logo": "ykb.png",
                    "default_gateway_code": "YKB",
                    "created_date": "2022-07-26T09:34:09.72+03:00",
                    "short_name": "YKB"
                },
                "resource_url": "",
                "threed_resource_url": "",
                "config": {
                    "merchantId": "",
                    "terminalId": "",
                    "posNetId": "",
                    "encKey": "",
                    "voidUrl": "",
                    "refundUrl": "",
                    "threeDValidationUrl": "",
                    "preAuthUrl": ""
                },
                "gateway_code": "YKB",
                "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
                "status": "ACTIVE",
                "one_shot_default": false,
                "currency": "TRY",
                "created_date": "2022-07-26T03:00:00.00+03:00"
            }
        ],
        "pagination": {
            "list_size": 13,
            "total": 13,
            "page": 0
        }
    }
}

`POST` Add Virtual POS

When Akinon customers want to add a new virtual POS, the following endpoint is called. The Merchant-Id value created for the customer is added to the header.

A successful request returns an HTTP Status 200 OK response with the added virtual POS in the body.

Path: /merchant-poses

Parameters

Parameter	Type	Required	Description
name	string	mandatory	Name of the virtual POS provided by the customer.
code	string	mandatory	Code of the virtual POS provided by the customer.
payment_system	object	mandatory	Object of the the payment system to which the virtual POS is connected.
payment_system.code	string	mandatory	Code of the payment system to which the virtual POS is connected.
resource_url	string	mandatory	The resource URL that the virtual POS will use for integration requests.
threed_resource_url	string	mandatory	The resource URL that the virtual POS will use for 3D integration requests.
config	object	optional	Object holding specific settings for the virtual POS, which can be queried using the virtual POS template API.
gateway_code	string	mandatory	Code specifying the infrastructure to which the virtual POS is connected. Supported infrastructures can be queried with the relevant API based on the payment system.
status	string	optional	Status information for the virtual POS. One of the values from MerchantPosStatus should be added. Default is INACTIVE.
one_shot_default	boolean	optional	Indicates whether the virtual POS is the default for single payment. If not provided, by default, it is set to false.
currency	currency	optional	Currency of the virtual POS. If not specified, default TRY is added.

Example Request

{
    "name": "DenizBank Sanal POS",
    "code": "DENIZBANK_USD_VPOS",
    "payment_system": {
        "code": "DENIZBANK",
    },
    "resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
    "threed_resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
    "config": {
        "shopCode": "test",
        "user": "test",
        "password": "password",
        "voidUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "refundUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "preAuthUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "storeKey": "test"
    },
    "gateway_code": "INTERTECH",

    "status": "ACTIVE",
    "one_shot_default": false,
    "currency": "USD"
}

Example Response

{
    "trace_id": "bca7b3c3-bbde-41ae-99ec-3fc0c89dfbc8",
    "response": {
        "name": "DenizBank Sanal POS",
        "code": "DENIZBANK_USD_VPOS",
        "payment_system": {
            "name": "DENİZBANK A.Ş.",
            "code": "DENIZBANK",
            "bank_eft_code": "0134",
            "logo": "denizbank.png",
            "default_gateway_code": "NESTPAY",
            "created_date": "2022-08-02T18:21:28.63+03:00",
            "short_name": "Denizbank"
        },
        "resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "threed_resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "config": {
            "shopCode": "test",
            "user": "test",
            "password": "password",
            "voidUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "refundUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "preAuthUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "storeKey": "test"
        },
        "gateway_code": "INTERTECH",
        "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
        "status": "ACTIVE",
        "one_shot_default": false,
        "currency": "USD",
        "created_date": "2023-01-20T12:28:12.70+03:00"
    }
}

`PUT` Edit Virtual POS

When Akinon customers want to edit an existing virtual POS, the following endpoint is called. The code value of the virtual POS to be updated is added to the URL, and the ID value created for the customer is added in the Merchant-Id header.

A successful request results in an HTTP Status 200 OK response with the edited virtual POS details in the body.

Path: /merchant-poses/{oldCode}

Parameters

Parameter	Type	Required	Description
name	string	mandatory	Name of the virtual POS provided by the customer.
code	string	mandatory	Code of the virtual POS provided by the customer.
payment_system	object	mandatory	Object of the payment system to which the virtual POS is connected.
payment_system.code	string	mandatory	The code of the payment system to which the virtual POS is connected.
resource_url	string	mandatory	The resource URL used for integration requests of the virtual POS.
threed_resource_url	string	mandatory	The resource URL used for 3D integration requests of the virtual POS.
config	object	optional	Object holding specific settings for the virtual POS. These settings can be queried with the virtual POS template API.
gateway_code	string	mandatory	Code specifying the infrastructure to which the virtual POS is connected. Supported infrastructures can be queried with the relevant API.
status	string	optional	Status information of the virtual POS. One of the values from the MerchantPosStatus should be added; by default, it is set to INACTIVE.
one_shot_default	boolean	optional	Indicates whether the virtual POS is the default for single payment. If not provided, by default, it is set to false.
currency	currency	optional	Currency of the virtual POS. If not specified, default TRY is added.

Return Values

Return Value	Type	Description
name	string	Name of the virtual POS provided by the customer.
code	string	Code of the virtual POS provided by the customer.
payment_system	object	Object of the payment system to which the virtual POS is connected.
payment_system.name	string	Name of the payment system to which the virtual POS is connected.
payment_system.code	string	Code of the payment system to which the virtual POS is connected.
payment_system.bank_eft_code	string	EFT code of the payment system to which the virtual POS is connected.
payment_system.logo	string	Location of the logo for the payment system to which the virtual POS is connected.
payment_system.default_gateway_code	string	Default gateway code of the payment system to which the virtual POS is connected.
payment_system.created_date	string	Creation date of the payment system to which the virtual POS is connected.
payment_system.short_name	string	Short name of the payment system to which the virtual POS is connected.
resource_url	string	The resource URL used for integration requests of the virtual POS.
threed_resource_url	string	The resource URL used for 3D integration requests of the virtual POS.
config	object	Object holding specific settings for the virtual POS. These settings can be queried with the virtual POS template API.
gateway_code	string	Code specifying the infrastructure to which the virtual POS is connected.
merchant_id	string	ID of the customer to whom the virtual POS is connected.
status	string	Returns one of the MerchantPosStatus values.
one_shot_default	boolean	Indicates whether the virtual POS is the default for single payment.
created_date	string	Creation date of the virtual POS.
currency	currency	Currency of the virtual POS. If not specified, default TRY is added.

Example Request

{
    "name": "DenizBank Sanal POS",
    "code": "DENIZBANK_TRY_VPOS01",
    "payment_system": {
        "code": "DENIZBANK"
    },
    "resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
    "threed_resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
    "config": {
        "shopCode": "3123",
        "user": "InterTestApi",
        "password": "3",
        "voidUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "refundUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "preAuthUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "storeKey": "gDg1N"
    },
    "gateway_code": "INTERTECH",
    "status": "ACTIVE",
    "one_shot_default": false,
    "currency": "TRY"
}

Example Response

{
    "trace_id": "3f1a3dc8-ccee-4bc0-861b-bbd63e7d0c2c",
    "response": {
        "name": "DenizBank Sanal POS",
        "code": "DENIZBANK_TRY_VPOS01",
        "payment_system": {
            "name": "DENİZBANK A.Ş.",
            "code": "DENIZBANK",
            "bank_eft_code": "0134",
            "logo": "denizbank.png",
            "default_gateway_code": "INTERTECH",
            "created_date": "2022-08-02T18:21:28.63+03:00",
            "short_name": "Denizbank",
            "supported_gateway_codes": [
                "INTERTECH"
            ]
        },
        "resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "threed_resource_url": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
        "config": {
            "shopCode": "3123",
            "user": "InterTestApi",
            "password": "3",
            "voidUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "refundUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "preAuthUrl": "https://test.inter-vpos.com.tr/mpi/Default.aspx",
            "storeKey": "gDg1N"
        },
        "gateway_code": "INTERTECH",
        "merchant_id": "9d36ec04-de2f-11ea-87d0-0242ac130003",
        "status": "ACTIVE",
        "one_shot_default": false,
        "currency": "TRY",
        "created_date": "2023-01-19T19:13:09.81+03:00"
    }
}

Enums

Enum	Values
MerchantPosStatus	`ACTIVE`, `INACTIVE`, `DELETED`
MerchantPosTemplateType	`TEXT`, `TEXT_HIDDEN`, `TOGGLE`, `SELECT`, `ARRAY`, `PASSWORD`, `SELECT_HIDDEN`, `TOGGLE_SELECT`
SessionTokenStatus	`ACTIVE`, `EXPIRED`, `COMPLETED`, `QUARANTINE`, `WAITING_FOR_VOID`, `FAILED_AFTER_VOID`, `MANUAL_REVIEW`

NOTE

NOTE

Customer POS Operations​

NOTE

DELETE Delete Virtual POS​

Example Response 1​

Example Response 2​

PATCH Activate/Deactivate Virtual POS​

NOTE

Example Response 1​

Example Response 1​

GET List Virtual POS​

Return Values​

Example Response​

POST Add Virtual POS​

Parameters​

Example Request​

Example Response​

PUT Edit Virtual POS​

Parameters​

Return Values​

Example Request​

Example Response​

Enums​

Customer POS Operations

`DELETE` Delete Virtual POS

Example Response 1

Example Response 2

`PATCH` Activate/Deactivate Virtual POS

Example Response 1

Example Response 1

`GET` List Virtual POS

Return Values

Example Response

`POST` Add Virtual POS

Parameters

Example Request

Example Response

`PUT` Edit Virtual POS

Parameters

Return Values

Example Request

Example Response

Enums