h2h | Qostiq

Host2Host interaction protocol

Interaction via Host2Host protocol allows to perform the process of collecting card data on the resource's side, if PCI DSS certificate is applicable. Interaction between the resource and Qostiq system is performed via API requests.

To create a payment with Host2Host method, it is necessary to send an Invoice create request. The invoice creation response returns ID session_id, that is necessary for passing the card data.
Send a H2H Data request to receive a token. The response returns a form_token token and payform_url URL, that are necessary for passing the card data.
After receiving a response for H2H Data request, it is necessary to form and verify an HTML-form Pay Form on payform_url with POST method with payer's card data

H2H Data request [/h2hdata]

Test URL: https://test-core.tech-icard.com/h2h_data

Production URL: https://core.tech-icard.com/h2h_data

Method: POST

Mandatory parameters: session_id

It is necessary to pass the session_id in H2H Data request. The response returns a form_token token and payform_url URL, that are necessary for passing the card data.

Example of request:

{
    "session_id": "26d90ef012e34b44aa9d74a3556e15a6"
}

Where:

Parameter	Description	Format
`session_id`	ID received in the Invoice create request response	string

Example of response:

{
    "data": {
        "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
        "payform_url": "https://card.qostiq.com/payform/"
    },
    "error_code": 0,
    "message": "success",
    "result": true
}

Where:

Parameter	Description	Format
`form_token`	token for passing the card data	string
`payform_url`	URL for redirecting the user with card data	string

Payform HTML-form formation [/Payform]

Method: POST

Mandatory parameters: session_id, card_number, card_holder, expiry_month, expiry_year, cvv, payform_url, form_token

Parameter session_id is taken from the response on the Invoice create request.

After HTML-form is approved, user will be redirected to the 3DS verification page.
After passing 3DS verification, user will be returned to the correspondent success or failed URL, that are passed in the Invoice create request.
Simultaneously, you will receive a callback. If payment was unsuccessful, then callback will include a reason for rejection, if it was passed by the paygate.

Example of form:

{
    "action": "https://card.tech-icard.com/en/payform",
    "method": "POST",
    "fields": {
        "session_id": "26d90ef012e34b44aa9d74a3556e15a6",
        "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
        "card_number": "4111111111111111",
        "card_holder": "TEST TEST",
        "expiry_month": "12",
        "expiry_year": "22",
        "cvv": "123"
    },
    "submit": true
}

Parameter	Description	Format
`expiry_year`	year of expiry of the card	`22`
`card_holder`	cardholder name	`TEST TEST`
`card_number`	user's card number	`4111111111111111`
`expiry_month`	month of expiry of the card	`12`
`cvv`	three-digit card authentication number	`123`
`session_id`	unique payment operation ID	`26d90ef012e34b44aa9d74a3556e15a6`
`form_token`	token for passing the card data	`0e61dd5935054d7e99d3da0cef411758`
`action`	URL for redirecting the user with card data	`https://card.tech-icard.com/en/payform`

Recurrents

Recurring payments make it possible to perform regular withdrawals from the payer's bank card without re-entering the card details and without the payer's participation in the initiation of the next payment.

IMPORTANT: This feature is available only with your manager's approval.

Initiation of the first recurrent payment occurs by "payway": "card_uah" in several stages:

To create a first payment in the chain of recurrents, it is necessary to pass an additional parameter "required_pay_token": "true" in Invoice/Create request. The request will be followed by a callback with an additional "pay_token" parameter in "ps_data" field.

IMPORTANT: Parameter pay_token will be sent only if transaction was processed successfully.

To initiate the subsequent payments, it is necessary to pass previously received pay_token in an Invoice/Create request.

IMPORTANT: The response will return method: offline and url: offline — that means that payer does not need to be redirected to the payment page. Also, Invoice/Pay request won't be initiated.

Payment result will appear in the Callback.

Example of request:

Test URL: https://core.test-qostiq.com/invoice/create

Production URL: https://core.qostiq.com/invoice/create

Method: POST

Mandatory parameters: amount, currency, payway, shop_id, shop_order_id, "required_pay_token": "true", sign.

{
    "amount": "1",
    "currency": "980",
    "description": "Test invoice",
    "payway": "card_uah",
    "pay_token": "9af6e26f3b4b44e28c26c2bd994987c4",
    "shop_id": "158",
    "shop_order_id": "49135760",
    "sign": "f63b494eb33e5d3549385d0ba2cb68b139e4a1b4483fd707aaac2095ab01bf42"
}

Example of successful response:

{
    "data": {
        "data": {
            "en": "No manual. Please, pay invoice",
            "ru": "Инструкция отсутствует. Пожалуйста, оплатите выставленный счет",
            "uk": "нструкція відсутня. Будь ласка, оплатіть рахунок"
        },
        "id": "OFFLINE",
        "method": "OFFLINE",
        "url": "OFFLINE"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true,
    "shop_id": 158,
    "transfer_id": null,
    "withdraw_id": null
}

Example of unsuccessful response:

{
    "data": null,
    "error_code": 1,
    "message": "IncorrectRequestParam",
    "result": false
}

Host2Host interaction protocol​

H2H Data request [/h2hdata]​

Payform HTML-form formation [/Payform]​

Recurrents​

Host2Host interaction protocol

H2H Data request [/h2hdata]

Payform HTML-form formation [/Payform]

Recurrents