Skip to content

Transaction status query request

Request

To get information about a transaction status or transaction details, Merchant must know the payment token and send an HTTP GET request to https://checkout.ecomcharge.com/ctp/api/checkouts/:payment_token, where payment_token should be replaced with the payment token that you have generated earlier.

Response

In the transaction section response parameters replicate token request parameters except for the additional ones:
object
token
required
 string
A payment token.
shop_id
required
 integer
Shop ID that a transaction was done for.
gateway_response
required
 object
A section that contains payment or authorization sections of payment or authorization transaction responses. Additionally, the parameter uid is added to the section. uid is the eComCharge gateway assigned ID to the transaction. You will use uid either to search transactions in the eComCharge backoffice or to send a transaction status query.
finished
required
 boolean
true or false. It's the token status parameter. It is true if the transaction was processed by an external payment system.
expired
required
 boolean
true or false. It's the token status parameter. It is true if a payment period allowed to pay has been expired.
test
required
 boolean
true or false. It is true if the transaction is a test one.
status
required
 string
If it is not error, it matches gateway response statuses.
required
 object
The object with the information on the shop for which the transaction was initialized.
id
required
 string
The identifier of the shop in the eComCharge system.
name
required
 string
The name of the shop in the eComCharge system.
country
required
 string
The country of the shop if provided in the eComCharge system, in the ISO 3166-1 alpha-2 format, for example, GB.
url
required
 string
The URL of the shop.
contact_email
required
 string
The contact email for the shop.
contact_phone
required
 string
The contact phone for the shop.
brands
required
 array
An array of active brands for the shop.
required
 object
The object with the information on the merchant of the shop for which the transaction was initialized.
id
required
 string
The identifier of the merchant in the eComCharge system.
country
required
 string
The country of the merchant in the ISO 3166-1 alpha-2 format, for example, GB.
message
required
 string
If status is error, it has error descriptions. Refers to gateway error response message. Otherwise, it equals to message in gateway_response.
Surcharge rates (v1)
object
initial_amount
 integer
The initial amount of the transaction without surcharge rates. The parameter is sent in the response if surcharge billing is enabled for the shop.
surcharge_amount
 integer
The amount of surcharge rates applied to the transaction. The overall charged amount equals the sum of initial_amount and surcharge_amount values. The parameter is sent in the response if surcharge billing is enabled for the shop.
Surcharge rates (v2)
object
object
object
Object with the information about the transaction amount adjustment.
initial_amount
 bigInteger
The initial amount of the transaction without adjustment.
adjustment_amount
 bigInteger
The amount of the adjustment. The overall charged amount equals the sum of initial_amount and adjustment_amount values.
currency
 string (3)
A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
object
Object with the information about the applied surcharge rate.
id
 string
Identifier of the adjustment.
type
 string
Type of the adjustment. Possible values: surcharge_max (surcharge rates).
amount
 integer
The amount of surcharge rates applied to the transaction.
currency
 string (3)
A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
initial_amount
 integer
The initial amount of the transaction without surcharge rates.
Response example 
{
  "checkout": {
    "token": "cb967032c168e0b6b930906974594600d96e4df489df8f5e15673df533ca7df5",
    "shop_id": 1673,
    "transaction_type": "payment",
    "gateway_response": {
      "payment": {
        "uid": "f356bd32-22b0-4a21-8725-490e45b67a11",
        "type": "payment",
        "updated_at": "2025-01-15T14:28:27.901Z",
        "gateway": {
          "iframe": true
        },
        "avs_cvc_verification": {
          "avs_verification": {
            "result_code": "1"
          },
          "cvc_verification": {
            "result_code": "1"
          }
        },
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 500,
        "currency": "EUR",
        "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
        "gateway_id": 3549,
        "status": "successful",
        "redirect_url": "https://processing.ecomcharge.com/process/f356bd32-22b0-4a21-8725-490e45b67a11",
        "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/f356bd32-22b0-4a21-8725-490e45b67a11/f10043446829352affbf0fc3ae014036c89354b469282cacbf5357f6c407e3a2?language=en",
        "method": {
          "brand": "master"
        }
      }
    },
    "order": {
      "currency": "EUR",
      "amount": 500,
      "description": "Test transaction",
      "tracking_id": null,
      "additional_data": {
        "request_id": "5125f48d8e14265ad9d485a4df76dd9c",
        "browser": {
          "screen_width": 1536,
          "screen_height": 864,
          "screen_color_depth": 24,
          "language": "en",
          "java_enabled": false,
          "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0",
          "time_zone": -180,
          "time_zone_name": "Europe/Istanbul",
          "window_height": 926,
          "window_width": 1513,
          "challenge_window_size": 5,
          "accept_header": "application/json, text/plain, */*"
        },
        "vendor": {
          "name": "CTP",
          "token": "cb967032c168e0b6b930906974594600d96e4df489df8f5e15673df533ca7df5"
        }
      },
      "expired_at": null
    },
    "settings": {
      "success_url": null,
      "fail_url": null,
      "decline_url": null,
      "notification_url": "https://notificationUrl",
      "verification_url": null,
      "cancel_url": null,
      "return_url": "https://returnUrl",
      "language": "en",
      "customer_fields": {},
      "credit_card_fields": {},
      "auto_return": null,          
      "button_next_text": null,
      "save_card_toggle": {
        "display": true,
        "customer_contract": false
      },
      "another_card_toggle": {
        "display": true
      },
      "auto_pay": false,
      "style": {
        "footer": {
          "secureInfo": {
            "text": "Secure payment is provided by PSP"
          }
        },
        "widget": {
          "buttonsColor": "#ff8e09",
          "backgroundType": 8
        }
      },
      "widget_version": 2
    },
    "customer": {
      "first_name": null,
      "last_name": null,
      "address": null,
      "city": null,
      "country": null,
      "state": null,
      "phone": null,
      "zip": null,
      "email": null,
      "birth_date": null,
      "device_id": "25b98e6c5e40982e13a483fe48a62dea",
      "taxpayer_id": null,
      "external_id": "test"
    },
    "finished": true,
    "expired": false,
    "shop": {
      "id": "1673",
      "name": "Good Point 2",
      "country": "",
      "url": "https://example.com",
      "contact_email": "example@example.com",
      "contact_phone": "+1234567890",
      "brands": [
        "visa",
        "master",
        "bank_transfer"
      ]
    },
    "merchant": {
      "id": "1253",
      "country": "LT"
    },
    "test": true,
    "status": "successful",
    "message": "Transaction is successful.",
    "version": null,
    "card_info": {},
    "job_id": "22def0a8-6dc0-40d6-8798-625ca9c9e52e",
    "payment_method": {
      "types": [
        "credit_card",
        "bank_transfer"
      ],
      "excluded_types": [],
      "excluded_brands": [],
      "data": {},
      "created_at": "2025-01-15T14:27:55Z",
      "updated_at": "2025-01-15T14:27:55Z",
      "id": 80212,
      "checkout_data_id": 85976
    }
  }
}
Response example if surcharge billing (v1) is enabled for the shop 
{
  "checkout": {
    "token": "c08bd9b031d54a2921d9c392873d9f2270e231b4b283f5a653617bc0b9644f10",
    "shop_id": 1673,
    "transaction_type": "payment",
    "gateway_response": {
      "payment": {
        "uid": "698d69b7-da39-40c7-8d42-bd5447c49b59",
        "type": "payment",
        "updated_at": "2024-07-02T14:11:44.256Z",
        "gateway": {
          "iframe": true
        },
        "avs_cvc_verification": {
          "avs_verification": {
            "result_code": "A"
          },
          "cvc_verification": {
            "result_code": "U"
          }
        },
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 737,
        "currency": "EUR",
        "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
        "gateway_id": 3549,
        "status": "successful",
        "redirect_url": "https://processing.ecomcharge.com/process/698d69b7-da39-40c7-8d42-bd5447c49b59",
        "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/698d69b7-da39-40c7-8d42-bd5447c49b59/49e2c5c9d6cbce7003f18a662ef7e9cd46f867bbcfc0fb3a3b52ad936bbeae32?language=en"
      }
    },
    "order": {
      "currency": "EUR",
      "amount": 737,
      "description": "Test description",
      "tracking_id": null,
      "additional_data": {
        "request_id": "9b41a3dd-171d-4e8a-93b4-5ab3583094e2",
        "vendor": {
          "name": "CTP",
          "token": "c08bd9b031d54a2921d9c392873d9f2270e231b4b283f5a653617bc0b9644f10"
        }
      },
      "expired_at": null,
      "initial_amount": 700,
      "surcharge_amount": 37
    },
    "settings": {
      "success_url": "http://127.0.0.1:4567/success",
      "fail_url": "http://127.0.0.1:4567/fail",
      "decline_url": "http://127.0.0.1:4567/decline",
      "verification_url": null,
      "language": "en",
      "customer_fields": {},
      "credit_card_fields": {},
      "auto_return": null,          
      "save_card_toggle": {
        "display": true,
        "customer_contract": false
      },
      "another_card_toggle": {
        "display": true
      },
      "auto_pay": null,
      "style": {
        "button_color": "#ff1a1a",
        "background_type": 2
      },
      "widget_version": 2
    },
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": null,
      "zip": null,
      "email": null,
      "birth_date": null,
      "device_id": "2e33f7fbdc05bb5b3ea8dbb927fe0494",
      "taxpayer_id": null
    },
    "finished": true,
    "expired": false,
    "shop": {
      "id": "1673",
      "name": "Good Point 2",
      "country": "",
      "url": null,
      "contact_email": "example@example.com",
      "contact_phone": "11111111111111",
      "brands": [
        "bank_transfer"
      ]
    },
    "merchant": {
      "id": "1253",
      "country": "LT"
    },
    "test": true,
    "status": "successful",
    "message": "Successfully processed",
    "version": null,
    "card_info": {},
    "job_id": "d156b448-9290-42ec-9021-6212f2e1547e",
    "payment_method": {
      "types": [
        "credit_card"
      ],
      "excluded_types": [],
      "data": {},
      "created_at": "2024-07-02T14:11:16Z",
      "updated_at": "2024-07-02T14:11:16Z",
      "id": 69877,
      "checkout_data_id": 75603
    }
  }
}
Response example if surcharge billing (v2) is enabled for the shop 
{
  "checkout": {
    "token": "a2a834b4658afbb57e373fc72950522e56a192cc1e8e7502c4c39470f0ba8be4",
    "shop_id": 1673,
    "transaction_type": "payment",
    "gateway_response": null,
    "order": {
      "currency": "EUR",
      "amount": 10300,
      "description": "Test transaction",
      "tracking_id": null,
      "additional_data": {
        "request_id": "3ed1c50791fd03b999f7b050f4ca0afd",
        "adjustments": {
          "initial_amount": 10000,
          "adjustment_amount": 300,
          "currency": "EUR",
          "surcharge_info": {
            "id": "85865386-8f70-455c-9923-73afed9c5632",
            "type": "surcharge_max",
            "amount": 300,
            "initial_amount": 10000,
            "currency": "EUR"
          }
        }
      },
      "expired_at": null
    },
    "settings": {
      "success_url": null,
      "fail_url": null,
      "decline_url": null,
      "notification_url": "https://notification-url",
      "verification_url": null,
      "cancel_url": null,
      "return_url": "https://return-url",
      "language": "ru",
      "customer_fields": {},
      "credit_card_fields": {},
      "auto_return": null,          
      "button_next_text": null,
      "save_card_toggle": {
        "display": true,
        "customer_contract": false
      },
      "another_card_toggle": {
        "display": true
      },
      "auto_pay": false,
      "style": {
        "widget": {
          "buttonsColor": "#ff8e09",
          "backgroundType": 8
        }
      },
      "widget_version": 2
    },
    "customer": null,
    "finished": false,
    "expired": false,
    "shop": {
      "id": "1673",
      "name": "Good Point 2",
      "country": "",
      "url": "https://example.com",
      "contact_email": "example@example.com",
      "contact_phone": "+1234567890",
      "brands": [
        "visa",
        "master"        
      ]
    },
    "merchant": {
      "id": "1253",
      "country": "LT"
    },
    "test": false,
    "status": "error",
    "message": "Gateway response not found.",
    "version": null,
    "card_info": {},
    "job_id": null,
    "payment_method": {
      "types": [
        "credit_card"
      ],
      "excluded_types": [],
      "excluded_brands": [],
      "data": {},
      "created_at": "2025-02-25T09:33:22Z",
      "updated_at": "2025-02-25T09:33:22Z",
      "id": 83292,
      "checkout_data_id": 89056
    }
  }
}