Charge request

Acquirers might apply various scenarios and transaction flows to process card payments for your billing scheme. It would make you implement different request types if you work with several acquirers or change your acquiring partner.

PayCross suggests using a single charge request which unifies the process of handling payments by saved card details.

When the PayCross system receives the charge request, it automatically modifies this request either to a payment or to an authorization operation. It depends on what transaction flow is supported by your acquirer which will process a payment. Moreover, if the charge request is modified to the authorization request, PayCross automatically sends the capture request.

In the back office the charge request is reported respectively to the type of the processed transaction, i.e. either as a payment or as an authorization and a capture.

Request

Send the POST request to https://gateway.pay-cross.com/services/credit_cards/charges with the following parameters:

Parameter	Type	Description
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 order description.
tracking_id	string(255)	Your transaction or order ID. Please, use unique values to get the relevant transaction information by query requests. Otherwise, you get informed on the first transaction that matches `tracking_id`.
expired_at	string	Date and time till a transaction should be finalized. Use ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), 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 или –hh:mm). If a payment is not paid till the indicated date, the transaction status is set to `expired`.
duplicate_check	boolean	`true` or `false`. Used to avoid payment duplicates. By default, it is set to `true`, so requests with the same `amount` and `number` or `token` within 30 seconds will be rejected.
dynamic_billing_descriptor	string	Dynamic billing descriptor.
language	string	The language of your checkout page. It also specifies the language of email notifications sent out to your customers, if customer notifications are enabled. English (`en`) is set by default. Possible values of `language` parameter.
notification_url	string	URL where the system should send the notifications about a transaction. The notification request format matches the transaction response format.
verification_url	string	A URL where the system should send the transaction verification. The verification request format matches the transaction response format.
return_url * conditionally required	string	A URL on the merchant side where PayCross should redirect the customer after 3-D Secure verification is finished. The parameter is mandatory if your merchant account is 3-D Secure enabled. Contact your account manager for more details.
test	boolean	`true` or `false`. The transaction is processed as a test if the parameter is set to `true`.
credit_card	object	A section of card credentials.
number * required	string	A card number. The length is from 12 to 19 digits.
verification_value * required	string	3- or 4-digit security code (CVC2, CVV2 or CID depending on the credit card brand). It can be sent along with the `token` value, PayCross will transmit the card details with the given CVC2/CVV2/CID to your acquirer.
holder * required	string	A cardholder name as it appears on the card. The maximal length is 32 characters.
exp_month * required	integer	A card expiration month indicated with two digits (for example, 01).
exp_year * required	integer	A card expiration year indicated with four digits (for example, 2026).
token * conditionally required	string	A card token received earlier. The parameter is mandatory if you do not send card credentials. If a card token is used, you should specify the `additional_data.contract` parameter.
skip_three_d_secure_verification	boolean	The parameter is used when you want your customer skip the 3-D Secure verification. Contact the Tech Support Team to check if you can apply this parameter. If `true`, PayCross doesn't launch the 3-D Secure verification for charge requests when a card token is submitted. Set to `false`, by default. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`.
force_three_d_secure_verification	boolean	The parameter enables the option to make the 3-D Secure verification check mandatory for the customer. Contact the Tech Support Team to check if you can apply this parameter. If `true`, PayCross forces the 3-D Secure verification for charge requests when a card token is submitted. Set to `false`, by default. The `force_three_d_secure_verification` parameter overrides the `skip_three_d_secure_verification` parameter, if both are set to `true`.
additional_data	object	A section with additional transaction data. Check with the Support Team if you should send any section parameters.
p2p	object	A parameter section for AFT transactions.
service_id * conditionally required	string	Request the parameter value from your manager.
service_extension * conditionally required	string	Request the parameter value from your manager.
excluded_gateways	array	An array for working with cascading payments
masterpass	object	A Masterpass service section.
params	object	A section for Masterpass parameters.
session	string	A user session ID.
receipt_text	array	Text added to the customer notification. Submit it as an array of strings, for example `["First line", "Second line"]`.
contract	array	An array of elements: `recurring` - PayCross provides a card token to use for recurrent payments when customers are not required to enter their card data again. Customers indicate their full card details including CVC/CVV codes and pass the 3-D Secure verification only during the initial payment; `oneclick` - PayCross provides a card token for the oneclick payment flow, when the customer is redirected to the checkout page with the prefilled card details and is just required to enter the CVC/CVV code and pass the 3-D Secure verification to complete the payment; `credit` - PayCross provides a card token to use for a payout transaction; `card_on_file` - PayCross returns a card token, so you can link it to the customer account and use it for payments initiated by the customer or by your application. See `card_on_file` section below for use cases. Note! The `card_on_file` option might not be supported by your acquirer. If you want to use the `card_on_file` option, please, contact your account manager.
avs_cvc_verification	object	AVS/CVC verification.
card_on_file	object	A section specifying the option parameters which are transmitted on to a payment network. If not specified, the `initiator` and `type` parameters are set to default values.
initiator	string	Applicable values: `merchant` (default) - the payment is initiated by the merchant, no action by the customer is required (for example a taxi ride cost is charged automatically from the customer's card after the ride is finished); `customer` - the payment is initiated by the customer, the payment confirmation by the customer is required (for example the customer pays a bill with the saved card).
type	string	Used only if `additional_data.card_on_file.initiator` is set to `merchant`. `delayed_charge` (default) - delayed charge (for example for the additionally rendered service); `increment` - you should charge an extra amount (for example in case of the upsale); `resubmission` - you re-submit a transaction request due to the payment failure (for example no money on the card); `reauthorization` - you want to renew the authorization (for example to keep money reserved on the card for future charges); `no_show` - you want to charge the card when the customer didn't use the product or service (for example no visit to a hotel).
browser	object	A section of client browser details. Section parameters are required for the 3-D Secure 2.0 flow only.
accept_header	integer	A value of `Accept` request HTTP header sent by the cardholder browser.
screen_width	integer	Screen width in pixels. Equals the `screen.width` parameter of JavaScript.
screen_height	integer	Screen height in pixels. Equals the `screen.height` parameter of JavaScript.
screen_color_depth	integer	Screen color depth in bits per pixel. Equals the `screen.colorDepth` parameter of 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 of JavaScript.
window_height	integer	Browser window height in pixels. Equals the `document.body.clientHeight` parameter of JavaScript.
language	string	Language of the navigator. Equals the `navigator.language` parameter of JavaScript.
java_enabled	boolean	Indicates if the browser is Java-enabled or not. Equals the `navigator.javaEnabled()` parameter of JavaScript.
user_agent	string	User agent string for the browser. Equals the `navigator.userAgent` parameter of JavaScript.
time_zone	integer	Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the `new Date().getTimezoneOffset()` parameter of JavaScript.
time_zone_name	string	A time zone name. Equals the `Intl.DateTimeFormat().resolvedOptions().timeZone` parameter of JavaScript.
customer * conditionally required	object	A section of the customer information. Contact the Tech Support Team to check what section parameters are required.
ip	string	An IP address of the customer placing an order.
email	string	An email of the customer placing an order.
device_id	string	A device ID (desktop, smartphone, etc.) of the customer placing an order.
birth_date	string	The customer's date of birth in the ISO 8601 format `YYYY-MM-DD`.
taxpayer_id	string	The customer's taxpayer ID.
billing_address	object	A section of parameters related to the customer's billing address. Contact the Tech Support Team to check if your acquirer requires any of the section parameters.
first_name * conditionally required	string	The customer's first name. The maximal length is 30 characters.
last_name * conditionally required	string	The customer's last name. The maximal length is 30 characters.
country * conditionally required	string	The customer's billing country in ISO 3166-1 Alpha-2 format.
city * conditionally required	string	The customer's billing city. The maximal length is 60 characters.
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 the country is `US`, the `zip` format must be NNNNN or NNNNN-NNNN.
address * conditionally required	string	The customer's billing address. The maximal length is 255 characters.
phone * conditionally required	string	The customer's phone number. The maximal length is 100 characters.
travel	object	Section with travel related data.
airline	object	Section for airline ticket addendum data.
agency_code	string	IATA agency code (for example `03`).
agency_name	string	Agency name that sold the ticket (for example `Coral travel`).
ticket_number	string	14-digit ticket number. Contains 3-digit ticketing code, 4-digit form number, 6-digit serial number, and the check digit (for example `390 5241 025377 1`).
booking_number	string	Booking code (for example `DKZVUA`).
restricted_ticked_indicator	string	Information on ticket returns. `0` - when the ticket can be returned. `1` - when the ticket may not be returned.
legs	array	Array of travel legs. Every leg consists of:
airline_code	string	2-letter IATA code (for example `B2`).
stop_over_code	string	IATA stop-over 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	Flight number (for example `A3 971`).
departure_date_time	string	Departure date and time (for example `2014-05-26T05:15:00`).
arrival_date_time	string	Arrival date and time (for example, `2014-05-26T07:30:00`).
originating_country	string	Country of origin (`RU`).
originating_city	string	City of origin (for example `Moscow`)
originating_airport_code	string	3-letter IATA code of the airport of origin (for example `DME`).
destination_country	string	Country that the traveler goes to (for example `Greece`).
destination_city	string	City that the traveler goes to (for example `Athens`).
destination_airport_code	string	3-letter IATA code of the airport that the traveler goes to (for example `ATH`).
coupon	string	Coupon number if applicable.
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	Passenger's first name (for example `KONSTANTIN`).
last_name	string	Passenger's last name (for example `IVANOV`).

Example of the request

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "credit_card": {
      "number": "5204240000015003",
      "verification_value": "123",
      "holder": "John Doe",
      "exp_month": "10",
      "exp_year": 2026
    },
    "additional_data": {
      "browser": {
        "screen_width": 1920,
        "screen_height": 1080,
        "screen_color_depth": 24,
        "language": "en",
        "java_enabled": false,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
        "time_zone": -180,
        "time_zone_name": "Europe/Helskinki",
        "accept_header": "*/*",
        "window_height": 667,
        "window_width": 600
      }
    },
    "three_d_secure": {
      "advanced": false
    },
    "test": true
  }
}

Response

The parameters of the response correspond to the parameters of the charge request and additionally specify the following:

Parameter	Type	Description
type * required	string	A transaction type, set to `charge`.
parent_uid * required	string	Transaction ID. Same as `uid`, if the general request was modified to the payment, or stands for the capture request identifier.
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.

Info

At the moment, if you accept payments on the PayCross widget and indicate charge as the transaction_type parameter value, you might not receive values for the rrn or bank_code parameters.

Example of the response to the charge request

{
    "uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "parent_uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "type": "charge",
    "payment_method_type": "credit_card",
    "tracking_id": "tracking_id_000",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2024-06-19T08:53:41.211Z",
    "updated_at": "2024-06-19T08:53:46.217Z",
    "paid_at": "2024-06-19T08:53:46.149Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://gateway.pay-cross.com/process/c74e1b00-9b94-4682-82c3-60167ce64841",
    "credit_card": {
        "holder": "John Doe",
        "stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
        "brand": "master",
        "last_4": "5003",
        "first_1": "5",
        "bin": "520424",
        "bin_8": "52042400",
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "exp_month": 10,
        "exp_year": 2026,
        "token_provider": null,
        "token": null
    },
    "status_code": null,
    "gateway": {
        "iframe": true
    },
    "mute_notifications": null,
    "id": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "additional_data": {},
    "links": {
        "receipt_url": "https://admin.pay-cross.com/customer/transactions/c74e1b00-9b94-4682-82c3-60167ce64841/33724a6fe94fe937575c6ed18d2ab8abdc34732df17e51be6da88e9b37356101?language=en"
    },
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
        "status": "successful"
    },
    "charge": {
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 100,
        "currency": "USD",
        "billing_descriptor": "test descriptor",
        "gateway_id": 3483,
        "status": "successful"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": "1"
        },
        "cvc_verification": {
            "result_code": "1"
        }
    },
    "customer": {
        "ip": null,
        "email": null,
        "device_id": null,
        "birth_date": null,
        "taxpayer_id": null,
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    },
    "billing_address": {
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    }
}