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://demo-gateway.begateway.com/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.
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, Demo PSP 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 Demo PSP 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.
be_protected_verification object A section of parameters of the beProtected verification service.
Example of the response when no configured beProtected rules on account 
{
  "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://demo-backoffice.begateway.com/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
      },
      "be_protected_verification":{
        "status":"successful",
        "white_black_list":{
          "email":"absent",
          "ip":"absent",
          "card_number":"white"
        },
        "rules":{
          "1_123_My Shop":{},
          "1_John Doe":{},
          "Demo PSP":{}
        }
      },
      "uid":"4107-310b0da80b",
      "status":"successful",
      "message":"Successfully processed",
      "amount":100,
      "currency":"USD",
      "description":"Test order",
      "type":"payment",
      "tracking_id":"your_uniq_number",
      "language":"en"
  }
}
Example of the response with failed beProtected section 
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
        "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2026
    },
    "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/1-2d4b20c72a/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"failed",
      "message":"Merchant terminal limits exceeded (maximum transaction amount). Transaction didn't pass anti-fraud checks.",
      "limit":{
        "volume":false,
        "count":false,
        "max":true,
        "current_volume":100,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"black",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "Demo PSP":{}
      }
    },
    "uid":"1-2d4b20c72a",
    "status":"failed",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "message":"Merchant terminal limits exceeded (maximum transaction amount). Transaction didn't pass anti-fraud checks.",
    "test":true,
    "created_at":"2014-06-11T12:05:54+03:00",
    "updated_at":"2014-06-11T12:05:54+03:00",
    "id":"1-2d4b20c72a"
  }
}
Example of the response example with successful beProtected section 
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2026
    },
    "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"successful",
      "limit":{
        "volume":false,
        "count":false,
        "max":false,
        "current_volume":90,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"absent",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "Demo PSP":{}
      }
    },
    "uid":"2-52671c8733",
    "status":"successful",
    "amount":90,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "message":"Successfully processed",
    "test":true,
    "created_at":"2014-06-11T12:04:59+03:00",
    "updated_at":"2014-06-11T12:04:59+03:00",
  }
}