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.pay-cross.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, PayCross will dispatch those emails in the `language` locale. Possible values are: `en` - English (default); `es` - Spanish; `tr` - Turkish; `de` - German; `it` - Italian; `ru` - Russian; `zh` - Chinese; `fr` - French; `da` - Danish; `sv` - Swedish; `no` - Norwegian; `fi` - Finnish; `pl` - Polish; `ja` - Japanese; `be` - Belarusian; `uk` - Ukrainian; `ka` - Georgian; `ro` - Romanian.
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, 2007). 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 PayCross 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":"2020"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"[email protected]"
      }
  }
}

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":"[email protected]"
      }
  }
}

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	A detected card brand. Possible values: `visa`, `master`, `jcb`, `discover`, `dinersclub`, `amex`, `belkart`, `unionpay`, etc.
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":"[email protected]"
      },
      "credit_card":{
        "holder":"John Doe",
        "stamp":"3709786942408b77017a3aac8390d46d77d181e34554df527a71919a856d0f28",
        "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e",
        "brand":"visa",
        "last_4":"0000",
        "first_1":"4",
        "exp_month":5,
        "exp_year":2015
      },
      "receipt_url": "https://admin.pay-cross.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":{},
          "PayCross":{}
        }
      },
      "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":"[email protected]"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://admin.pay-cross.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":{},
        "PayCross":{}
      }
    },
    "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":"[email protected]"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://admin.pay-cross.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":{},
        "PayCross":{}
      }
    },
    "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",
  }
}