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