Authorization

The authorization request is used either to check if there are enough funds available on the card to make a payment, or to hold the required amount for a future charge. The funds are not deducted from the cardholder's account but the available funds limit is shown as decreased by the authorization amount.

The authorization transaction should be followed by a capture request to charge the amount, or by a void request to cancel the hold.

Info

It is required to be PCI DSS validated to use this transaction type and send plain unencrypted card data.

Request

To initiate an authorization transaction, send a POST request to https://gateway.pay-cross.com/transactions/authorizations with the following parameters:

Parameter	Type	Description
amount * required	bigInteger	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	string(255)	The ID of your transaction or order. Please, use unique values in order to get the correct transaction information by 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.
expired_at	string	Time in the ISO-8601 format until which the transaction must be made: `YYYY-MM-DDThh:mm:ssTZD`, where YYYY – year (for example, 2025), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC). If the payment is not made by the specified date and time, expired status is assigned to the transaction.
duplicate_check	boolean	The boolean parameter controls whether the payment gateway will do a duplicate check of the received requests to authorize a card. By default, it is true and duplicate requests with the same `amount` and `number` or `token` sent within 30 seconds after the original request will be rejected.
dynamic_billing_descriptor	string	A dynamic billing descriptor.
language	string	A language of the 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	The URL where the webhook notification about a transaction will be posted. The notification request format is the same as the transaction response format.
verification_url	string	The URL where the transaction verification request will be posted. The verification request format is the same as the transaction response format.
return_url * conditionally required	string	The URL on the merchant's website to which PayCross will redirect the customer once they complete 3-D verification. Required, if your merchant account is 3-D Secure enabled.
test	boolean	If set to `true`, the transaction will be a test one. By default, `false`.
credit_card	object
number * conditionally required	string(19)	The card number. The length is between 12 and 19 digits. Required, if a card token is not submitted in the request.
verification_value * conditionally required	string	3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand). It can be sent along with `token` parameter and in this case PayCross will submit the card details with the given CVC2/CVV2/CID to the acquiring bank. The parameter can be required depending on the shop settings and acquirer requirements.
holder * conditionally required	string (35)	The cardholder name as it appears on the card. The parameter is optional in the PayCross system but can be required by the acquirer.
exp_month * conditionally required	string (2)	Card expiration month. Must be one or two digits (for example, 01).
exp_year * conditionally required	string (4)	Card expiration year. Must be 4 digits (for example, 2027).
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.
skip_three_d_secure_verification	boolean	The parameter enables the option for the customer to skip the 3-D Secure verification check. If `true`, PayCross doesn't launch the 3-D Secure verification to authorize the transactions. By default, `false`. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`. Contact the Tech Support Team to check if you can apply this parameter. Overridden by Smart Routing rules with `Skip 3ds` or `Force 3ds` actions.
force_three_d_secure_verification	boolean	The parameter enables the option to make the 3-D Secure verification check mandatory for the customer. If `true`, PayCross forces the 3-D Secure verification to authorize the transactions. By default, `false`. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`. Contact the Tech Support Team to check if you can apply this parameter. Overridden by Smart Routing rules with `Skip 3ds` or `Force 3ds` actions.
three_d_secure	object	A section for setting up the advanced scenario of payment processing with the 3-D Secure 2.0 verification.
advanced	boolean	Set to `true` to apply the advanced scenario. Otherwise, set to `false`.
additional_data	object	A section with additional transaction data.
excluded_gateways	array	Array for working with cascading payments.
masterpass	object	A section of Masterpass service.
params	object	A section for Masterpass parameters.
session	string	user session id.
receipt_text	array	Text that will be added to the email for the client. Submit it as an array of strings, for example, `["First line", "Second line"]`.
contract * conditionally required	array	An array which can contain the following elements: `recurring` - PayCross returns a card token to be used in subsequent charges without entering the card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification. `oneclick` - PayCross returns a card token to use it in the oneclick payment scheme. It means PayCross will display a payment page with the prefilled card data and the customer will only be asked to enter CVC/CVV code and pass 3-D Secure verification to complete the payment. `credit` - PayCross returns a card token to be used for a payout `card_on_file` - PayCross returns a card token to be saved to the customer's profile and to be used in time-to-time charges initiated by the customer or by your application. See `card_on_file` section below to understand what cases the contract type covers.
avs_cvc_verification	object	A section of AVS/CVC verification check.
card_on_file	object	A section for parameters related to storing card details for future transactions. If not submitted, default values of `initiator` and `type` parameters are applied.
initiator	string	`merchant` - (default) merchant initiated a card charge (for instance, for a car ride service) `customer` - customer initiated a card charge (for instance, customer confirmed an order and wanted to pay with a saved card).
type	string	Used only in case `additional_data.card_on_file.initiator` is `merchant`. `delayed_charge` - (default) prepaid expense charged to the customer's card `increment` - additional charge beyond the initially charged amount (for example, in the case of an upsell or in the case the product is exchanged for a more expensive one) `resubmission` - transaction resubmission after the previous charge has failed (for example, not sufficient funds on the card) `reauthorization` - repeat authorization (for example, when the merchant wants to reauthorize the previously authorized amount for future charges) `no_show` - a no-show charge (for example, no visit to a hotel).
browser	object	Section of customer browser parameters. Used only for 3DS 2.0.
accept_header	string	Value of `Accept` request HTTP header sent by the customer's browser.
screen_width	integer	Screen width in pixels. Equals the `screen.width` parameter in JavaScript.
screen_height	integer	Screen height in pixels. Equals the `screen.height` parameter in JavaScript.
screen_color_depth	integer	Screen color depth in bits per pixel. Equals the `screen.colorDepth` parameter in JavaScript. Applicable values are: `1` - 1 bit `4` - 4 bits `8` - 8 bits `15` - 15 bits `16` - 16 bits `24` - 24 bits `32` - 32 bits `48` - 48 bits.
window_width	integer	Browser window width in pixels. Equals the `document.body.clientWidth` parameter in JavaScript.
window_height	integer	Browser window height in pixels. Equals the `document.body.clientHeight` parameter in JavaScript.
language	string	Language of the navigator. Equals the `navigator.language` parameter in JavaScript.
java_enabled	boolean	Indicates if the browser is Java-enabled or not. Equals the `navigator.javaEnabled()` parameter in JavaScript.
user_agent	string	User agent string for the browser. Equals the `navigator.userAgent` parameter in JavaScript.
time_zone	integer	Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the `new Date().getTimezoneOffset()` parameter in JavaScript.
time_zone_name	string	Time zone name. Equals the `Intl.DateTimeFormat().resolvedOptions().timeZone` parameter in JavaScript.
customer * conditionally required	object	A section of the customer information. Contact the Tech Support Team to inquire 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.
device_id * conditionally required	string	The customer's device ID (desktop, smartphone, etc.).
birth_date * conditionally required	string	The customer's date of birth in ISO 8601 format `YYYY-MM-DD`.
taxpayer_id * conditionally required	string	The customer's taxpayer ID.
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 inquire 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 (2)	The customer's billing country in 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.
travel	object	A section with travel related data.
airline	object	The section with airline ticket data.
agency_code	string	IATA agency code, for example `03`.
agency_name	string	Name of the agency that sold the ticket, for example, `Coral travel`.
ticket_number	string	14-digit ticket number. Should contain 3-digit ticketing code, 4-digit form number, 6-digit serial number, and check digit, for example, `390 5241 025377 1`.
booking_number	string	For example, `DKZVUA`.
restricted_ticked_indicator	string	If the ticket can be returned, the field value is `0`, otherwise it is `1`.
legs	array	An array of travel legs. Every leg consists of:
airline_code	string	2-letter IATA code, for example `B2`.
stop_over_code	string	IATA stopover code. If a traveler stays in the originating city more than 24h, then set the field value to `O` or leave it empty. If the originating airport is a transit airport, then set the field value to `X`.
flight_number	string	For example, `A3 971`.
departure_date_time	string	For example, `2014-05-26T05:15:00`.
arrival_date_time	string	For example, `2014-05-26T07:30:00`.
originating_country	string	For example, `RU`.
originating_city	string	For example, `Moscow`.
originating_airport_code	string	3-letter IATA code, for example `DME`.
destination_country	string	For example, `Greece`.
destination_city	string	For example, `Athens`.
destination_airport_code	string	3-letter IATA code, for example `ATH`.
coupon	string	Coupon number if it was applied.
class	string	Class flight, 1-letter IATA code. For example, `C`.
passengers	array	List of passengers where every list item consists of
first_name	string	First name of the passenger, for example, `KONSTANTIN`.
last_name	string	Last name of the passenger, for example, `IVANOV`.

Example of the authorization request

{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "verification_value":"123",
        "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",
      "test":true,
      "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]"
      }
  }
}

Example of the request with information about ticket and tour voucher sales

{
  "request":{
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "tracking_id":"your_uniq_number",
    "test":true,
    "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]"
    },
    "travel": {
      "airline": {
        "agency_code": "03",
        "agency_name": "Corel travel",
        "ticket_number": "390 5241 025377 1",
        "booking_number": "DKZVUA",
        "restricted_ticked_indicator": "0",
        "legs": [
          {
            "airline_code": "B2",
            "stop_over_code": "X",
            "flight_number": "A3 971",
            "departure_date_time": "2014-05-26T05:15:00",
            "arrival_date_time": "2014-05-26T07:30:00",
            "originating_country": "RU",
            "originating_city": "Moscow",
            "originating_airport_code": "DME",
            "destination_country": "Greece",
            "destination_city": "Athens",
            "destination_airport_code": "ATH",
            "coupon": "coupon code",
            "class": "C"
          }
        ],
        "passengers":[
          {
            "first_name": "KONSTANTIN",
            "last_name": "IVANOV"
          },
          {
            "first_name": "JULIA",
            "last_name": "IVANOVA"
          }
        ]
      }
    }
  }
}

Example of the request with additional receipt text

{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "verification_value":"123",
        "holder":"John Doe",
        "exp_month":"05",
        "exp_year":"2027"
      },
      "additional_data":{
        "receipt_text": ["First line", "Second Line"]
      },
      "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 transaction UID.
status * required	string	A transaction status.
message * required	string	A processing result message.
tracking_id * required	string	A value of the `tracking_id` parameter submitted in the transaction request.
language * required	string	A value of the `language` parameter submitted in the transaction request, or `en` if the parameter was omitted.
type * required	string	A transaction type.
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.
product * required	string	A card product type code.
last_4 * required	string	The last 4 digits of the card number.
first_1 * required	string	The first digit of the card number.
bin * required	string (6)	6-digit bank identification number (BIN). The first 6 digits of the card number.
bin_8 * required	string (8)	8-digit bank identification number (BIN). The first 8 digits of the card number. The value is returned for Visa, MasterCard, Maestro cards and the corresponding co-branded cards. Otherwise, `null` is returned.
issuer_country * required	string (2)	The country of the card issuing bank in ISO 3166-1 Alpha-2 format.
issuer_name * required	string	The name of the card issuing bank.
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. The token allows you to save the customer's details and run recurring payments or charge the customer whenever s/he makes a new purchase.
token_provider * required	string	The detected token provider. Possible values or `null`.
receipt_url * required	string	A transaction receipt URL.
additional_data	object	A section of detailed information about the payment.
masterpass	object	A section of Masterpass service.
params	object	A section for Masterpass parameters.
session	string	A user session ID.
result	string	A section of the transaction result in Masterpass.
status	string	A response status. Possible values: `successful`, `failed`.
message	string	A message about a result of a Masterpass operation generated by PayCross.
error	string	A message about an error reason in Masterpass generated by PayCross. Returned in case of an error.
error_message	string	An error message generated by Masterpass. Returned in case there is an error.
error_code	string	An error code generated by Masterpass. Returned in case there is an error.
token	string	A Masterpass card token. Returned if the card is saved in Masterpass.
receipt_text	array	Text that will be added to the customer email.
redirect_url * required	string	A URL of the page to finalize the transaction. If the `status` parameter is set to `incomplete`, redirect the customer to this URL. It runs the 3-D Secure verification of the cardholder.
code * required	string	Transaction processing code .
friendly_message * required	string	`code` description for the customer.
authorization * required	object
auth_code * required	string	An authorization code provided by the acquirer.
bank_code * required	string	A transaction bank code.
rrn * required	string	A retrieval reference number, a transaction ID issued by the cards processing network.
ref_id * required	string	A transaction reference ID issued by the acquirer.
message * required	string	A message provided by the acquirer.
billing_descriptor * required	string	A billing descriptor assigned to the transaction.
status * required	string	A transaction status in the acquiring bank.
avs_cvc_verification	object	An optional section with AVS/CVC verification results.
smart_routing_verification	object	A section of parameters of Smart Routing verification results.
status	string	Smart Routing check status for the transaction.

Example of the response

{
  "transaction": {
    "uid": "bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
    "status": "successful",
    "amount": 482,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "authorization",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-04-02T08:40:33.377Z",
    "updated_at": "2024-04-02T08:40:38.455Z",
    "paid_at": "2024-04-02T08:40:38.400Z",
    "expired_at": null,
    "recurring_type": "initial",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
      "brand": "visa",
      "last_4": "1097",
      "first_1": "4",
      "bin": "401200",
      "bin_8": "40120000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 7,
      "exp_year": 2027,
      "token_provider": null,
      "token": "854d95e6-b7a5-41fb-b2a0-b8a6a0ae2021"
    },
    "receipt_url": "https://admin.pay-cross.com/customer/transactions/bf2ebe5b-0a31-4769-b61d-a46afa3b98fa/e6d23017fb43c6e2be34992efef50cfbadd3bb64942d7a9fe74a3e726a3907a6?language=en",
    "status_code": null,
    "gateway": {
      "iframe": false
    },
    "mute_notifications": null,
    "id": "bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "redirect_url": "https://gateway.pay-cross.com/process/bf2ebe5b-0a31-4769-b61d-a46afa3b98fa",
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
      "status": "successful"
    },
    "authorization": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Authorization was approved",
      "amount": 482,
      "currency": "EUR",
      "billing_descriptor": "test descriptor",
      "gateway_id": 3208,
      "status": "successful"
    },
    "customer": {
      "ip": null,
      "email": null,
      "device_id": null,
      "birth_date": null
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}

Example of the response on incomplete 3-D Secure transaction

{
  "transaction": {
    "uid": "1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
    "status": "incomplete",
    "amount": 482,
    "currency": "EUR",
    "description": "Test transaction",
    "type": "authorization",
    "payment_method_type": "credit_card",
    "tracking_id": "your_uniq_number",
    "message": null,
    "test": true,
    "created_at": "2024-04-02T10:22:01.352Z",
    "updated_at": "2024-04-02T10:22:03.058Z",
    "paid_at": null,
    "expired_at": null,
    "recurring_type": "initial",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
      "brand": "visa",
      "last_4": "1097",
      "first_1": "4",
      "bin": "401200",
      "bin_8": "40120000",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 7,
      "exp_year": 2027,
      "token_provider": null,
      "token": "5d1392f2-864d-499b-b3ce-40e68d980d71"
    },
    "receipt_url": "https://admin.pay-cross.com/customer/transactions/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5/4bfe945ab88e76507becb0f792f14426ad261afe2f809932cdcfd6c713ad6339?language=en",
    "status_code": null,
    "gateway": {
      "iframe": true
    },
    "mute_notifications": null,
    "id": "1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "redirect_url": "https://gateway.pay-cross.com/process/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
    "code": "P.4012",
    "friendly_message": "Redirect to pass 3-D Secure verification.",
    "smart_routing_verification": {
      "status": "successful"
    },
    "three_d_secure_verification": {
      "status": "incomplete",
      "message": "Authentication Available",
      "ve_status": "Y",
      "acs_url": null,
      "pa_req": null,
      "md": null,
      "pa_res_url": "https://admin.pay-cross.com/process/1f63b7ec-c58f-4a38-87bc-e8ea55a7d9c5",
      "eci": null,
      "pa_status": null,
      "xid": null,
      "cavv": null,
      "cavv_algorithm": null,
      "fail_reason": null,
      "method_process_url": null,
      "creq": null
    },
    "authorization": {
      "auth_code": null,
      "bank_code": null,
      "rrn": null,
      "ref_id": null,
      "message": null,
      "amount": 482,
      "currency": "EUR",
      "billing_descriptor": null,
      "gateway_id": 3483,
      "status": "incomplete"
    },
    "customer": {
      "ip": null,
      "email": null,
      "device_id": null,
      "birth_date": null
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}