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 eastablish 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_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: ""
    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. This callback can be called up to three times before a transaction is rejected.

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: ""
    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

On the third and final unsuccessful transaction, the user is prevented from making any further attempts to pay, and the transaction_rejected callback is triggered with an object containing an error message returned. At this point you can safely close the modal.

{
    message: "Three failed attempts"
}

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
}

results matching ""

    No results matching ""