Praxis Wiki logo

Cashier API {cashier}


The section explains how to interact with API.

In some cases the customer activity within the Cashier requires the agent's interaction: payout request approval, finalizing (capture) of the authorized deposit transaction, etc.

Often it is critical for the business flow to interact with the customer in time, whereas it is not always possible for the agent to react instantly. For that purpose the CRM can call API functions in order to follow the same steps as the agent would do, so you will know that a certain action is taken instantly upon the customer's activity, with all the regulatory considerations.

{danger.fa-exclamation-triangle} IMPORTANT #1: The validation callback will be triggered only if the validation_url is provided within the Cashier session request.

Cashier session allows the customer to access the Cashier UI - an interface where the customer may choose one of the payment methods, offered according to the merchant's visibility rules, limits and priorities.

{danger.fa-exclamation-triangle} IMPORTANT #2: It is crutial to perform the redirect from a browser by following the redirect link or in the iframe, thus the browser adds the needed headers with Origin/Refer need for our system to compare the request with the list of allowed domains for an application.

Upon sending the request to Cashier API, you receive json response that contains redirect_url parameter. The redirect_url parameter is a link that will automatically perform the customer login to Cashier.

This redirect_url value should be set as src attribute of an iframe within the payment page at the merchant website.

ENDPOINTS

Name URL
Sandbox https://pci-gw-test.praxispay.com/cashier/cashier
Live https://gw.praxisgate.com/cashier/cashier

Request Parameters

✓ - required value
? - optional, value or null
✕ - always appears as null

Variable Type Description
merchant_id varchar(50) Merchant API client account identifier
application_key varchar(32) Identifier of your application (website)
intent varchar(32) Action to be taken within the cashier. Allowed values are:
- authorization for authorization (hold) for the following capture
- payment for payment transaction
- withdrawal for withdrawal request
currency varchar(10) Intended transaction currency
amount int(20) ? Intended transaction amount in cents (send null to let the customer decide).
Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents
balance int(20) ? Customer's withdrawable balance in cents. Can be used for automatic amount validation during the withdrawal request submission (send null to bypass the validation).
Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents
cid varchar(50) Unique customer id in your system.
Note: Personally Identifiable Information such as an e-mail address are strictly forbidden;
if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis.
locale varchar(5) User locale. See locales reference for the full list of supported locales
customer_token varchar(32) ? HASH value of customer's identity
customer_data <Object> ? Customer data object
payment_method varchar(50) ? Payment method. The gateway will override this value if provided.

* gateway parameter is not applicable for Credit Card method for payouts;

** the predefined gateway hash value: "credit_card_cascade_gateway_0000" can be used instead of "payment_method": "Credit Card" for payments.
Either gateway or payment method should be provided in case of 0-Auth and CIT transactions.
gateway varchar(32) ? For payment: hash of the gateway doing the processing;
For withdrawal: hash of non-credit card gateway doing the processing.
Either gateway or payment method should be provided in case of 0-Auth and CIT transactions.
validation_url varchar(256) ? URL to which the pre-deposit validation will be sent
notification_url varchar(256) URL to which the deposit status notification will be sent
return_url varchar(256) User will be redirected to a specified URL (relevant for cashier login, virtual terminal, 3D Secure and E-Wallet login redirect)
order_id varchar(50) Transaction identifier in your system
variable1 varchar(256) ? Your custom field to tag the transaction with some necessary information
variable2 varchar(256) ? Your custom field to tag the transaction with some necessary information
variable3 varchar(256) ? Your custom field to tag the transaction with some necessary information. E.g. profile value for the customer which is sent from CRM to us. (Please note that if it is a new user that is not yet recorded in our system, it is needed to use customer_data “profile” parameter to set the needed profile level with the first transaction)
version varchar(3) API version
timestamp int(11) Request time (unix timestamp, seconds)
mit <Object> ? MIT object will contain the list of settings for processing merchant-initiated transactions (MIT).
session_configuration <Object> ? The object will contain overriding configuration rules for this session attempt.
session_type varchar(32) ? Type of the session. Allowed values are: - cashier, - payment_link. Payment Link type allows to initiate Cashier session with an extended lifetime (expires) - up to 72 hours.
expires int(11) ? Payment Link lifetime. The unix epoch timestamp (in seconds) when the login URL will expire (up to 72 hours from now). Used for payment_link session types only. If not set, the Payment Link lifetime will default to 15 minutes.
cashier_ui_preset varchar(256) ? Cashier UI Preset. If empty, the default preset for Cashier UI from the application configuration will be used. If not empty, the value will override the application configuration.

Response Parameters

Variable Type Description
status int API communication status - for transaction processing status please refer to transaction.transaction.status
- 0 if the request was successful
- Negative integer if internal server/network error occurs
- Positive integer if application/logical error occurs
description varchar(256) Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production
redirect_url varchar(256) ? Cashier login URL. Appears as null for authentication/validation errors and expired session.
customer <Object> Customer object
session <Object> Session object
version varchar(3) API version
timestamp int(11) Response time (unix timestamp, seconds)

Signature

The full signature generation algorithm can be found in the Authentication section.

Request signature parameters

  1. merchant_id
  2. application_key
  3. timestamp
  4. intent
  5. cid
  6. order_id

Response signature parameters

  1. status
  2. timestamp
  3. redirect_url
  4. customer.customer_token

Example

Request

{
    "merchant_id": "Test-Integration-Merchant",
    "application_key": "Sandbox",
    "intent": "payment",
    "currency": "USD",
    "amount": 100,
    "cid": "1",
    "locale": "en-GB",
    "customer_token": null,
    "customer_data": {
        "country": "GB",
        "first_name": "John",
        "last_name": "Johnson",
        "dob": "12\/31\/1980",
        "email": "[email protected]",
        "phone": "44201112222",
        "zip": "WC2N 5DU",
        "state": "JS",
        "city": "London",
        "address": "Random st., 12\/3"
    },
    "payment_method": null,
    "gateway": null,
    "validation_url": null,
    "notification_url": "https:\/\/api.merchant.com\/v1\/deposits\/tx-1560610955",
    "return_url": "https:\/\/merchant.com\/payment_result\/tx-1560610955",
    "order_id": "test-1560610955",
    "variable1": "your variable",
    "variable2": "if that is not enough, you can pass even one more variable",
    "variable3": null,
    "version": "1.3",
    "timestamp": 1590611635
}

Response

{
    "status": 0,
    "description": "Ok",
    "redirect_url": "https:\/\/compute.praxispay.com\/login\/8a7sd87a8sd778ac961062c6bedddb8",
    "customer": {
        "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
        "country": "GB",
        "first_name": "John",
        "last_name": "Johnson",
        "avs_alert": 0,
        "verification_alert": 0
    },
    "session": {
        "auth_token": "8a7sd87a8sd778ac961062c6bedddb8",
        "intent": "payment",
        "session_status": "created",
        "order_id": "test-1560610955",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.000000,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "payment_method": "WireOnline",
        "gateway": null,
        "cid": "1",
        "variable1": "your variable",
        "variable2": "if that is not enough, you can pass even one more variable",
        "variable3": null
    },
    "version": "1.3",
    "timestamp": 1590611635
}

Visibility

In case the merchant wants to open iframe and not in a new window or full page, below might be useful for you:

  • Min dimensions for desktop to display Cashier Frame without scroll. Width static, height - dynamic (add fields differ).

  • Example below was taken for Deposit CC PM (due to static add fields setup)

    • Dark: 922 х 643

    • Mosaic: 710 x 727

    • Panoramic: 800 x 725

    • Table: 620 x 920

    • Tiles: 620 x 810

    • PowerSlide: 600 x 800

The display of elements inside the frame is adaptive