Skip to content

Check-up

The request does a risk check of transaction details against configured risk management rules: white and black lists, amount limits, velocity limits and processing restrictions (for example to block certain card BINs).


Request

To check a transaction against risk rules, send a POST to https://gateway.overpay.io/transactions/checkups with the following parameters:

Parameter Type Description
amount * required
integer An amount in minimal currency units, for example $32.45 must be sent as 3245.
currency * required
string A currency in the ISO-4217 format, for example USD.
description * required
string (255) A short description of the order.
tracking_id * required
string (255) An ID of the transaction or the order. Use unique values to get relevant transaction information with a query request. Otherwise, you will get the first transaction with the matching tracking_id value. Can be multiple values separated with semicolons. For example, "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f". If multiple values are sent in the request, the transaction search in the back office system can be performed by any of them.
duplicate_check boolean The parameter controls whether the payment gateway will do duplicate check of received requests to check up a card. By default, it is true and requests submitted with the same amount and number or token within 30 seconds will be rejected.
language string A language of the merchant's checkout page or the customer.

If the parameter is set and transaction notification emails to customers are enabled, Overpay will dispatch those emails in the language locale. English (en) is set by default. Possible values of language parameter.
notification_url string A URL where a notification about a transaction will be posted to. The notification request format equals a transaction response format.
verification_url string A URL where a transaction verification request will be posted to. The verification request format equals a transaction response format.
test boolean true or false. The transaction will be a test one if it is true.
credit_card * required
object
number * conditionally required
string (19) A card number.

Required, if a card token is not submitted in the request.
holder * conditionally required
string (32) A cardholder name as it appears on the card.

Required, if a card token is not submitted in the request.
exp_month * conditionally required
integer A card expiration month expressed with two digits (for example, 01).

Required, if a card token is not submitted in the request.
exp_year * conditionally required
integer A card expiration year expressed with four digits (for example, 2026).

Required, if a card token is not submitted in the request.
verification_value * conditionally required
string A 3- or 4-digit security code (called CVC2, CVV2 or CID depending on a credit card brand).

Required, if a card token is not submitted in the request. It can be sent along with the token parameter, then Overpay will submit card details with the given CVC2/CVV2/CID to the acquiring bank.
token * conditionally required
string A card token that was received in the transaction response when the card was charged for the first time.

Required, if card details are not submitted in the request.
customer * conditionally required
object A section of the customer information.
Contact the Tech Support Team to check if your acquirer requires any of the section parameters.
ip * conditionally required
string The customer's IP address.
email * conditionally required
string The customer's email.
billing_address * conditionally required
object A section of the customer's address details. Contact the Tech Support Team to check if your acquirer requires any of the section parameters.
first_name * conditionally required
string (30) The customer's first name.
last_name * conditionally required
string (30) The customer's last name.
country * conditionally required
string The customer's billing country in the ISO 3166-1 Alpha-2 format.
city * conditionally required
string (60) The customer's billing city.
state * conditionally required
string The customer's two-letter billing state only if the billing address country is US or CA.
zip string The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address * conditionally required
string (255) The customer's billing address.
phone * conditionally required
string (100) The customer's phone number.
Example of the request
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "holder":"John Doe",
        "exp_month":"05",
        "exp_year":"2026"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Example of the request with card token
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Response

In the transaction section response parameters replicate request parameters except the additional ones:

Parameter Type Description
transaction * required
object
uid * required
string A UID of the processed transaction.
status * required
string A transaction status.
message * required
string A processing result message.
type * required
string A transaction type.
tracking_id * required
string A value of the tracking_id parameter sent in the transaction request.
language * required
string A value of the language parameter sent in the transaction request, or en if the parameter was omitted.
test * required
boolean If true, the transaction is a test one. Otherwise, false.
payment_method_type * required
string A payment method used to complete the transaction.

Possible values:
credit_card.
credit_card * required
object
brand * required
string The detected card brand.
last_4 * required
string The last 4 digits of the card number.
first_1 * required
string The first digit of the card number.
stamp * required
string A card hash. It is constant even if either the expiration date or the cardholder is changed.
token string A card token. Store the token and charge returning customers or run recurring charges without customers' billing details. The token allows you to save the customer's details and charge them whenever they make new purchases, or you renew their services.
receipt_url * required
string A transaction receipt URL.
Example of the response
{
  "transaction":{
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      },
      "credit_card":{
        "holder":"John Doe",
        "stamp":"3709786942408b77017a3aac8390d46d77d181e34554df527a71919a856d0f28",
        "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e",
        "brand":"visa",
        "last_4":"0000",
        "first_1":"4",
        "exp_month":5,
        "exp_year":2026
      },
      "receipt_url": "https://backoffice.overpay.io/customer/transactions/4107-310b0da80b/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "address":"1st Street",
        "country":"US",
        "city":"Denver",
        "zip":"96002",
        "state":"CO",
        "phone":null
      },          
      "uid":"4107-310b0da80b",
      "status":"successful",
      "message":"Successfully processed",
      "amount":100,
      "currency":"USD",
      "description":"Test order",
      "type":"payment",
      "tracking_id":"your_uniq_number",
      "language":"en"
  }
}