Skip to content

API version 3

Introduction

To make API responses more user-friendly and comprehensive for you, PayCross starts introducing the API version 3 (API v.3). The main changes relate to the response parameters and transaction status codes. The codes now go along with friendly messages for you to get more information about transaction processing.

As of September 15, 2022, the API v.3 is already configured for all https://gateway.pay-cross.com/ - endpoints. To submit requests, just add the X-API-Version: 3 header to the request. For response parameters and their description, please use the guide below.

For any other questions related to the PayCross API v.3, you are welcome to contact our Tech Support Team on [email protected].

Requests

To send POST or GET requests to the API v.3 of the https://gateway.pay-cross.com/- endpoints, add the X-API-Version: 3 header to the request, or use the header instead of X-API-Version: 2, if the latter was required.

As for the request parameters, use the parameters described for the required endpoint. No additional parameters are required.

Responses

The API v.3 responses have the following parameters:

Parameter Type Description
uid string A UID of the processed transaction.
status string A status of the processed transaction.
code string A transaction processing code.
friendly_message string Message for the customer.
message string A message from the bank system.
amount integer An amount of the transaction in minimal currency units. For example, USD 12.00 is transmitted as 1200.
currency string A currency of the transaction in the ISO-4217 format, for example, USD.
description string A transaction description.
type string A transaction type.
tracking_id string Set to the tracking_id value from the request.
test boolean Set to true if a transaction is a test one.
created_at string A time when the transaction was created at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD.
updated_at string A time when the transaction was last updated at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD.
paid_at string A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. Set to null if the transaction is incomplete.
expired_at string A time when the transaction expires in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD, i.e. a time till which the customer can complete the transaction. Set to null if the parameter is not applicable to the transaction.
closed_at string A time when a banking day in the acquiring bank ends in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. Set to null if the parameter is not applicable to the transaction.
settled_at string A time when the acquiring bank settled the transaction amount to the merchant's current account in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. Set to null if the parameter is not applicable to the transaction.
manually_corrected_at string A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. Set to null if the parameter is not applicable to the transaction.
redirect_url 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.
parent_uid string A UID of the parent transactions, if applicable.
reason string A description of the chargeback reason.
recurring_type string A type of the recurring transaction. Set to null if the parameter is not applicable to the transaction.
language string A language parameter value from the request, or en, if the parameter is not sent in the request.
status_code integer A status code of the 3-D Secure verification. Set to null if the parameter is not applicable to the transaction.
errors object A section of error details and parameters.
customer object A section of the customer information.
ip string The customer's IP address.
email string The customer's email.
device_id string The customer's device ID.
birth_date string The customer's date of birth.
first_name string The customer's first name.
last_name string The customer's last name.
address string The customer' billing address.
country string The customer's billing country in the ISO 3166-1 alpha-2 format.
city string The customer's billing city.
state string The customer's two-letter billing state, if the billing address country is US or CA.
zip string The customer's billing ZIP or postal code. If country=US, the zip format must be NNNNN or NNNNN-NNNN.
phone string The customer's phone number.
payment_method object A section of details of the payment method used by the customer to make the transaction.
payment_method_type string A payment method type used to make the transaction.
holder string The cardholder name.
stamp string The card stamp.
brand string The card brand.
last_4 string The last 4 digits of the card.
first_1 string The first digit of the card.
bin string The card BIN.
issuer_country string The country of the card issuing bank.
issuer_name string The issuing bank of the card.
product string The card product type.
exp_month integer The card expiration month represented with two digits, for example 01.
exp_year integer The card expiration year represented with four digits, for example 2021.
token_provider string The card token provider, if any.
token string The card token.
recipient object A section of the recipient's details. Applicable for payouts and P2P transactions initiated by the customer to the recipient.
customer object A section of the recipient's personal and address details.
first_name string The recipient's first name.
last_name string The recipient's last name.
address string The recipient's billing address.
country string The recipient's billing country in the ISO 3166-1 alpha-2 format.
city string The recipient's billing city.
state string The recipient's two-letter billing state, if the billing address country is US or CA.
zip string The recipient's billing ZIP or postal code. If country=US, the zip format must be NNNNN or NNNNN-NNNN.
phone string The recipient's phone number.
payment_method object A section of details of the payment method used to receive a payout or P2P transfer.
holder string The recipient cardholder name.
stamp string The recipient card stamp.
brand string The recipient card brand.
last_4 string The last 4 digits of the recipient card.
first_1 string The first digit of the recipient card.
bin string The recipient card BIN.
issuer_country string The recipient card country.
issuer_name string The issuing bank of the recipient card.
product string The recipient card product type.
exp_month integer The recipient card expiration month represented with two digits, for example 01.
exp_year integer The recipient card expiration year represented with four digits, for example 2021.
token string The recipient card token.
token_provider string The source card token provider, if any.
payment_method_type string A payment method type used to receive a payout or P2P transfer.
smart_routing_verification object A section of the Smart Routing service parameters. Applicable if the Smart Routing service is activated.
status string A status of the Smart Routing service processing.
three_d_secure_verification object A section of the 3-D Secure verification parameters.
additional_data object A section of additional details about the transaction.
browser object A section of the customer's browser data.
contract object A section of the parameters related to card tokens issued for payments by saved cards.
avs_cvc_verification object A section of the AVS/ CVC verification check.
avs_verification object A section with the result of the AVS verification check.
result_code string A code of the AVS verification check result.
cvc_verification object A section with the result of the CVC verification check.
result_code string A code of the CVC verification check result.
transaction object A section of the transaction details.
ref_id string A transaction reference ID assigned by the bank.
message string A transaction processing message.
amount integer A transaction amount in minimal currency units.
currency string A currency of the transaction in the ISO-4217 format, for example, USD.
billing_descriptor string A transaction billing descriptor.
gateway_id integer An ID of the payment gateway through which the transaction was processed in the PayCross system.
status string A transaction status.
auth_code string A transaction authorization code.
rrn string A Retrieval Reference Number of the transaction assigned by the bank.
bank_code string A transaction processing code assigned by the bank.
links object A section of links.
receipt_url string A URL of the transaction receipt.
bank_info object A section of parameters of the balance request.

If the parameter is not applicable to the transaction, response parameter values are set to null.

Processing codes

An API v.3 response mandatory contains a code parameter value in the {Letter code}.{4 code digits} format, where:

  • {Letter code} stands for a transaction processing status;
  • {4 error code digits} relate to an error code of a system service that can not process a transaction.

Letter codes

API v.3 letter code API v2 status Status description
S successful The transaction is successfully processed.
F failed The transaction is failed due to some reason in the system of the bank / integration provider.
P pending
incomplete		 The transaction is still being processed, or the system waits for the customer's action to complete the transaction.
E error There was an error while processing the transaction by PayCross internal services.

4 error code digits

API v.3 4 digit range Description
0000 The operation is successful.
0001 - 0499 Error codes of the system validation and processing service for card transactions.
0501 - 0999 Error codes of the system validation and processing service for transactions that are initiated with alternative payment methods.
1000 - 1999 Error codes of the payment gateway service.
2000 - 3999 Error codes of the Smart Routing service.
4000 - 4999 Error codes of the 3-D Secure verification service.
6000 - 6999 Error codes of the AVS/ CVC verification check.
7000 - 7999 Error codes of the Verify service.
8001 Error code of the P2P verification service.
8010 Error code of the payment gateway service for requests in asynchronous mode.
8005 - 9999 Bank error codes.

You can find detailed description of all the codes in the API v.3 processing error codes appendix.

Example of the API v.3 response to the payment transaction request

The sample transaction has the incomplete status and the P.9998 code. Provided that the three_d_secure_verification is the only section with the incomplete status, the transaction could not be processed as the PayCross system waits for the customer to take the 3-D Secure verification check. 

{
  "uid": "46154-aba1cf5e57",
  "code": "P.9998",
  "friendly_message": "Incomplete transaction",
  "status": "incomplete",
  "amount": 100,
  "currency": "USD",
  "description": "Test transaction ütf",
  "type": "payment",
  "payment_method": {
    "payment_method_type": "credit_card",
    "holder": "John Doe",
    "stamp": "5f854c844e3007f2ecff2aa614f6a4cc6b8a2c241aab3e5776fe7912dc7b9d92",
    "brand": "visa",
    "last_4": "0013",
    "first_1": "4",
    "bin": "420000",
    "issuer_country": "LT",
    "issuer_name": "VISA",
    "product": "VISA",
    "exp_month": 10,
    "exp_year": 1,
    "exp_year": 2026,
    "token_provider": null,
    "token": "2efef4c9-d4de-4603-bc84-7a9bc5456939"
  },
  "tracking_id": "tracking_id_000",
  "message": null,
  "test": true,
  "created_at": "2022-09-15T08:43:56.521Z",
  "updated_at": "2022-09-15T08:43:57.943Z",
  "paid_at": null,
  "expired_at": null,
  "recurring_type": "initial",
  "closed_at": null,
  "settled_at": null,
  "manually_corrected_at": null,
  "language": "en",
  "redirect_url": "https://gateway.pay-cross.com/process/46154-aba1cf5e57",
  "status_code": 21,
  "links": {
    "receipt_url": "https://admin.pay-cross.com/customer/transactions/46154-aba1cf5e57/bbe9f4090e43351ca1ee724a202376cb24da3ffbfa86df30c80e95fb4fdee386?language=en"
  },
  "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/Vilnius",
      "accept_header": "*/*",
      "window_height": 667,
      "window_width": 600
    },
    "contract": [
      "recurring"
    ]
  },
  "customer": {
    "ip": "127.0.0.1",
    "email": "[email protected]",
    "device_id": "12312312321fff67",
    "birth_date": "1980-01-31",
    "first_name": "John",
    "last_name": "Doe",
    "address": "1st Street",
    "country": "US",
    "city": "Denver",
    "zip": "96002",
    "state": "CO",
    "phone": null
  },
  "smart_routing_verification": {
    "status": "successful"
  },
  "max_mind_verification": {
    "score": 45,
    "status": "successful",
    "distance": null,
    "countryMatch": "No",
    "countryCode": null,
    "freeMail": "No",
    "anonymousProxy": "No",
    "binMatch": "No",
    "binCountry": "LT",
    "err": "IP_NOT_FOUND",
    "proxyScore": "0.00",
    "ip_region": null,
    "ip_city": null,
    "ip_latitude": null,
    "ip_longitude": null,
    "binName": null,
    "ip_isp": null,
    "ip_org": null,
    "binNameMatch": "NA",
    "binPhoneMatch": "NA",
    "binPhone": null,
    "custPhoneInBillingLoc": "NotFound",
    "highRiskCountry": "No",
    "queriesRemaining": "14286",
    "cityPostalMatch": "No",
    "shipCityPostalMatch": null,
    "carderEmail": "No"
  },
  "three_d_secure_verification": {
    "status": "incomplete",
    "message": "Authentication Available",
    "ve_status": "Y",
    "acs_url": null,
    "pa_req": null,
    "md": null,
    "pa_res_url": "https://gateway.pay-cross.com/process/46154-aba1cf5e57",
    "eci": null,
    "pa_status": null,
    "xid": null,
    "cavv": null,
    "cavv_algorithm": null,
    "fail_reason": null,
    "method_process_url": "https://gateway.pay-cross.com/api/v1/transactions/bd79f747-a42f-4ee3-b993-069310ca8238/method-process",
    "creq": null
  },
  "transaction": {
    "auth_code": null,
    "bank_code": null,
    "rrn": null,
    "ref_id": null,
    "message": null,
    "amount": 100,
    "currency": "USD",
    "billing_descriptor": null,
    "gateway_id": 645,
    "status": "incomplete"
  },
  "avs_cvc_verification": {
    "avs_verification": {
      "result_code": null
    },
    "cvc_verification": {
      "result_code": null
    }
  }
}