Skip to content

Transaction verification

Transaction verification is a way to call a script on one of your own web servers whenever a transaction is being processing. Verification is used in order to accept or decline a transaction.

Set up the verification

To receive a verification request from the Overpay system, pass verification_url in transaction request parameters.

{
    ....

    "verification_url":"https://your-domain.com/verification",

    ....
}

A verification request uses HTTP Basic authentication with Shop ID and Secret Key.

A verification request has the following structure:

Example of verification request 
{
  "uid": "0f12aeaa-cb11-4549-9c94-40b705000fe1",
  "status": "incomplete",
  "amount": 501,
  "currency": "USD",
  "description": "Test transaction",
  "type": "payment",
  "payment_method_type": "credit_card",
  "tracking_id": "tracking_id_0012",
  "message": "Unknown transaction status. Contact technical support.",
  "test": true,
  "created_at": "2026-10-22T12:06:54.861Z",
  "updated_at": "2026-10-22T12:06:54.876Z",
  "paid_at": null,
  "expired_at": null,
  "recurring_type": "initial",
  "closed_at": null,
  "settled_at": null,
  "manually_corrected_at": null,
  "language": "ru",
  "credit_card": {
    "holder": "[FILTERED]",
    "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
    "brand": "visa",
    "last_4": "0000",
    "first_1": "4",
    "bin": "420000",
    "bin_8": "42000000",
    "hash_bin9": null,
    "issuer_country": "US",
    "issuer_name": "VISA Demo Bank",
    "product": "F",
    "exp_month": 9,
    "exp_year": 2027,
    "token_provider": null,
    "stamp_expdate": "0f1e430bf7b9484ad9cac27d36155ef0bb11a61f71892cfa3904c3df937833a4",
    "token": "0219b641-760c-4afb-860c-1a28e86a51e1"
  },
  "receipt_url": "https://backoffice.overpay.io/customer/transactions/0f12aeaa-cb11-4549-9c94-40b705000fe1/c12635d3e5783d05308f57f39a242e9bece440dbbbab1c48a8029ca9f9ffa165?language=ru",
  "status_code": 10,
  "gateway": {
    "iframe": true
  },
  "mute_notifications": null,
  "version": 1,
  "psp_settled_at": null,
  "registry_id": null,
  "three_ds_expired_at": null,
  "id": "0f12aeaa-cb11-4549-9c94-40b705000fe1",
  "additional_data": {
    "contract": [
      "recurring"
    ]
  },
  "redirect_url": "https://gateway.overpay.io/process/0f12aeaa-cb11-4549-9c94-40b705000fe1",
  "code": "P.9999",
  "friendly_message": "Unknown transaction status. Contact the merchant for details.",
  "smart_routing_verification": {
    "status": "successful"
  },
  "transaction_verification": {
    "message": null,
    "status": "incomplete"
  },
  "payment": {
    "auth_code": null,
    "bank_code": null,
    "rrn": null,
    "ref_id": null,
    "message": null,
    "amount": 501,
    "currency": "USD",
    "billing_descriptor": null,
    "gateway_id": 4318,
    "status": "incomplete"
  },
  "avs_cvc_verification": {
    "avs_verification": {
      "result_code": null
    },
    "cvc_verification": {
      "result_code": null
    }
  },
  "customer": {
    "ip": null,
    "email": null,
    "device_id": null,
    "birth_date": null,
    "external_id": null
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": null,
    "address": "Baker street 221b",
    "country": "GB",
    "city": "London",
    "zip": null,
    "state": null,
    "phone": null
  }
}

Accept or decline a transaction

Your web server should return the 200 HTTP status code and POST parameters in order to accept or decline a transaction.
Parameter Type Description
code * required
 integer Set to 0 to accept the transaction. Set to any other code to decline the transaction.
uid * required
 string Submit the UID copied from the request.
amount * required
 integer Submit the amount copied from the request.
message string A message why the transaction is declined, if the value of code is other than 0.
friendly_message string A message to the customer to explain a reason for decline.
created_at string A response time in the ISO-8601 format.
Example of the response to accept a transaction 
{
  "code":0,
  "uid": "35153123-9367e7e770",
  "amount": 100,
  "created_at": "2020-08-04T06:16:17.052Z"
}
Example of the response to decline a transaction 
{
  "code":1,
  "uid": "36279632-7127y612a6",
  "amount": 100,
  "message":"IP validation failed",
  "friendly_message": "Your transaction is declined. For details please contact our customer service",
  "created_at": "2020-08-04T06:16:22.141Z"
}