Praxis Wiki logo
Praxis Wiki
Version:
latest (API 1.3)
  • 3.3 (API 1.1)
  • 3.4 (API 1.2)
  • latest (API 1.3)

    • Cashier API virtual-terminal

    The virtual-terminal API function allows you to initiate a checkout session on behalf of the customer.

    Agent will be guided through the payment process for a specific amount. In case the transaction fails, the agent (or manager) will have the ability to retry using a different payment option.

    When you execute the request, you will receive a JSON response containing a redirect_url parameter.
    This redirect_url provides a link that automatically logs the customer into the Cashier.

    The link should be embedded as the src attribute of iframe.

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

    {danger.fa-exclamation-triangle} IMPORTANT 2:
    To use the Virtual Terminal feature within Atlas, you must implement the customer_sync callback and provide your callback URL.
    However, customer_sync is not required if the Virtual Terminal is initiated directly via API.

    Endpoints

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

    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).
    agent_name varchar(32) ✓ Name of the agent performing the VT login on behalf of the customer.
    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).
    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).
    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 (PII), such as email addresses, is strictly forbidden.
    If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
    locale varchar(5) ✓ User locale. See locales reference for the full list of supported locales.
    customer_data <Object> ? Customer object
    customer_token varchar(32) ? HASH value of customer's identity.
    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).
    gateway varchar(32) ? Credit card gateway doing the processing.
    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.
    version varchar(3) ✓ API version
    timestamp int(11) ✓ Request time (unix timestamp, seconds)

    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.
    customer <Object> ✓ Customer object
    session <Object> ✓ Session object
    version varchar(3) ✓ API version
    timestamp int(11) ✓ Response time (unix timestamp, seconds)
    redirect_url varchar(256) ✓ Cashier Autologin URL. When redirected to this URL, the customer will be navigated further to the Cashier deposit page.

    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
    7. agent_name

    Response signature parameters

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

    Example

    Request

     
    {
    "merchant_id": "Test-Integration-Merchant",
    "application_key": "Sandbox",
    "agent_name": "Sales - Andrew Swift",
    "intent": "sale",
    "currency": "USD",
    "amount": 100,
    "cid": "1",
    "locale": "en-GB",
    "customer": {
        "cid": "1",
        "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 (Success)

     
    {
    "status": 0,
    "description": "Ok",
    "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,
    "redirect_url" : "https://compute.praxispay.com/login/8F95LAal8VEsCs7Zm8lqebqGn9Grstyvva6y666hhjVUlIwsjvL3w0NWYNj95vmjzJsvnRjP90ww%2BaAxMtN2Uh0KX%2FCyEtEXNFqQS%2FvCTQ%3D"
}
    2022 © PRAXIS CASHIER