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:

Note

The request body must be wrapped in a top-level request{} object.

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 an array of up to 10 recent transactions with the matching tracking_id. 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, PayCross 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 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, 2027). 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. 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. external_id string (255) The customer's identifier in the merchant's system. 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 IN, US or CA. zip conditionally required 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":"2027"
      },
      "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:

transaction 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 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 required 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 Example of the response { "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":2027 }, "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 }, "uid":"4107-310b0da80b", "status":"successful", "message":"Successfully processed", "amount":100, "currency":"USD", "description":"Test order", "type":"payment", "payment_method_type": "credit_card", "tracking_id":"your_uniq_number", "language":"en", "test": true } }