Callbacks

In order to allow you to capture relevant API data as the modal process occurs, we provide the following callbacks:

token_error

If you have incorrectly hashed and salted the Payment Modal auth string, or if the auth string has expired, an error message is output to the modal, and the token_error callback is triggered. The error response from the token endpoint is passed to the token_error callback.

// token_eror
{
    code: "jwt_auth_invalid_request"
    message: "Session has expired"
    data: {
        status: 403
    }
}

booking_logged

If you do not create a booking prior to the user arriving at your payment page, and therefore set the value of your .tmt_booking_id input to 0, a booking will be created prior to the transaction being attempted using the POST /bookings endpoint. The response to this request will be passed to the booking_logged callback. It is advisable to log the ID of the booking as this can be used to establish whether a transaction was successful or not if timeouts occur.

// booking_logged
{
    author: "24"
    channels: 84
    content: ""
    countries: "GB"
    created: "2019-08-12 10:29:15"
    currencies: "USD"
    date: "2020-05-12"
    email: "john.smith@example.org"
    firstname: "John"
    id: 2600
    modified: "2019-08-12 10:29:15"
    pax: 0
    reference: ""
    status: "draft"
    surname: "Smith"
    title: "Smith | john.smith@example.org"
    total: 999
    total_unpaid: 999
    transaction_ids: []
    trust_id: "21-2600"
    ...
}

booking_exists

This callback is triggered when passing a booking ID for an already existing booking to the modal.

You may wish to create bookings prior to the user arriving at the payment page using the POST /bookings endpoint and then include the ID for that booking in the input with class .tmt_booking_id or keyed with booking_id in a data object. The booking is looked up via the GET /bookings/ID endpoint and the response is passed to the booking_exists callback.

// booking_exists
{
    author: "24"
    channels: 84
    content: ""
    countries: "GB"
    created: "2019-08-12 10:29:15"
    currencies: "USD"
    date: "2020-05-12"
    email: "john.smith@example.org"
    firstname: "John"
    id: 2600
    modified: "2019-08-12 10:29:15"
    pax: 0
    reference: ""
    status: "draft"
    surname: "Smith"
    title: "Smith | john.smith@example.org"
    total: 999
    total_unpaid: 999
    transaction_ids: []
    trust_id: "21-2600"
}

booking_error

This callback is triggered instead of the booking_logged or booking_exists callbacks in the event of an error in the booking data provided. The error message is output to the modal and the booking_error callback is triggered with the error message passed as the single argument that the booking_error callback receives.

For example, the channel ID supplied corresponds with a channel that has GBP as its base currency, but the booking currency is supplied as USD.

{
    response: code: "rest_invalid_param"
    data: {
        status: 400, 
        params: {
            channels: "Channel ID currency does not match nominated currency."
        }
    }
    message: "Invalid parameter(s): channels"
}

transaction_result_available

This callback is triggered as soon as the user has completed 3DS validation and been redirected back to the modal. It includes the response from the original transaction request made prior to 3DS validation taking place. Note that the status of the response will be set to "pending" at this point. On this callback, you have the option of closing the modal and redirecting the user to an outcome page, while polling the TMT API for the outcome of the 3DS validation.

NB: This callback is only triggered on transactions where 3DS validation has been applied

{
    3ds_redirect_url: "https://3ds2-sandbox.ckotech.co/interceptor/3ds_2q7embsry47erkrysaxnk24cpe"
    3ds_response: "https://3ds2-sandbox.ckotech.co/interceptor/3ds_2q7embsry47erkrysaxnk24cpe"
    adjustments: []
    allocations: []
    attempt_3ds: true
    auth_code: null
    author: null
    author_id: 1
    authorname: "modaluser3"
    bin_number: "424242"
    bookings: [
        {
            id: 7109, 
            total: 5000, 
            reference: null, 
            country: 'GB', 
            channels: '1568'
        }
    ]
    card_type: null
    card_types: null
    channels: 1568
    content: "Pending"
    countries: "GB"
    created: "2021-12-01 11:51:25"
    currencies: "USD"
    document: null
    forex: null
    forex_id: null
    forex_rate: null
    hash: "a4799a4d915f33f726b5da2af11c753135ad008bdaadc148a2e09cb3a3d85f57"
    id: 5718
    ip_address: "192.168.10.1"
    language: "enGB"
    last_four_digits: null
    linked_id: null
    modified: "2021-12-01 11:51:33"
    payee_email: "jane.smith@example.org"
    payee_name: "Jane"
    payee_surname: "Smith"
    payment_ids: [13816]
    payment_methods: "credit-card"
    psp: "checkout"
    redirect_url: "https://3ds2-sandbox.ckotech.co/interceptor/3ds_2q7embsry47erkrysaxnk24cpe"
    statement_date: "2021-12-01 00:00:00"
    status: "pending"
    title: "Jane Smith | jane.smith@example.org | purchase"
    token: "pay_4tkwf62ilp4khgrpihm6sewsty"
    total: 5000
    total_remaining: 0
    transaction_type: "purchase"
    transaction_types: "purchase"
    trust_id: "3-5718"
    uuid: "f9ec3afd-7fb8-4ae0-9a14-776f88e195ca"
}

transaction_logged

This callback is triggered when the user has successfully completed a transaction. It includes the response from the POST /transactions endpoint. The response to this request will be passed as the single argument that the transaction_logged callback receives.

{
    3ds_response: {}
    adjustments: []
    api_urls: []
    author: "24"
    bin_number: "411111"
    bookings: [
        {
            id: 2605, 
            total: 999, 
            currencies: "USD", 
            reference: ""}
    ]
    card_types: "visa"
    channels: 84
    content: "Succeeded!"
    countries: "US"
    created: "2019-08-12 10:39:26"
    currencies: "GBP"
    forex: []
    forex_rate: ""
    hash: "44a256f2e5150dc1d0341feb6346cef685e0c0a05d179757ab282298f31a8bb8"
    id: 2606
    ip_address: ""
    last_four_digits: "1111"
    linked_id: 0
    modified: "2019-08-12 10:39:29"
    payee_email: "matt.mb697@gmail.com"
    payee_name: "Matthew Bush"
    payee_surname: "Bush"
    payment_ids: [2607, 2608, 2609]
    payment_methods: "credit-card"
    psp: "spreedly"
    statement_batches: "WEEK-33-1-2019-test"
    status: "complete"
    title: "John Smith | john.smith@example.org | purchase"
    token: "VXOcZHZR2wSeOxAvPEGoPeB9Avp"
    total: 830
    total_remaining: 830
    transaction_types: "purchase"
    trust_id: "21-2606"
}

transaction_failed

When the user has attempted a transaction, but it has been rejected by the card issuing bank, the response from the POST /transactions endpoint will be passed as the single argument that the transaction_failed callback receives.

Example

{
    3ds_response: {}
    adjustments: []
    api_urls: []
    author: "24"
    bin_number: "510510"
    bookings: [
        {
            id: 2610, 
            total: 999, 
            currencies: "USD", 
            reference: ""}
    ]
    card_types: "master"
    channels: 84
    content: "Unable to process the purchase transaction."
    countries: "GB"
    created: "2019-08-12 10:43:29"
    currencies: "GBP"
    forex: []
    forex_rate: ""
    hash: "cf6a7a4504568672f16101a342c67982ed42d9d3042a6c9a87bab93e0d29fcaa"
    id: 2611
    ip_address: ""
    last_four_digits: "5100"
    linked_id: 0
    modified: "2019-08-12 10:43:31"
    payee_email: "john.smith@example.org"
    payee_name: "John Smith"
    payee_surname: "Smith"
    payment_ids: [2612]
    payment_methods: "credit-card"
    psp: "spreedly"
    statement_batches: "WEEK-33-1-2019-test"
    status: "failed"
    title: "John Smith | john.smith@example.org | purchase"
    token: "VdOZCqLvFowUIfi2cZVQxfqLDqF"
    total: 830
    total_remaining: 0
    transaction_types: "purchase"
    trust_id: "21-2611"    
}

transaction_rejected

  • Deprecated

transaction_timeout

At the point at which the user has completed their credit card details and submitted the transaction, the transaction process is in motion. Unless there is an issue at the TMTProtects side, the transaction request will be relayed to the bank. Should a timeout occur between the bank responding to TMTProtects or TMTProtects honouring the Payment Modal API request, an error message is displayed on the modal informing the user that there was a timeout but payment may have been successful and informing them of the booking ID for the transaction. The transaction_timeout callback is also triggered with details of the timeout and the booking ID pertaining to the transaction supplied.

The booking can be looked up using the GET /bookings/ID endpoint. The response will include an array of linked transactions under the field transaction_ids the last value in this array will pertain to the most recent transaction.

The transaction can then be looked up using the GET /transactions/ID endpoint to ascertain if it was successful or not.

{
    booking_id: 2622
    message: "Request timed out"
    name: "TimeoutError"
}

transaction_error

If the transaction attempt failed due to connectivity issues with the card issuing bank or for any reason other than being rejected for anything other than the card issuing bank's criteria, the transaction_error callback is triggered with the error response being passed as the single argument

{
    name: TypeError
    message: Failed to fetch
}

modal_closed

Should the user close the modal at any stage in the process, the modal_closed callback is triggered and an object is passed as the single argument

{
    message: modal closed
}

close_window_attempted

Should the user close attempt to close their browser window while the transaction is being processed, the close_window_attempted callback is triggered and an object is passed as the single argument. The user is prompted to confirm the close to try and prevent a disconnection.

{
    message: 'User attempted to close browser window while transaction is being processed!'
}

results matching ""

    No results matching ""